Subroutines written in BASIC are written and compiled just like normal BASIC programs, except for a few differences. The first is that after compiling (which you must do with the /X:2 option), you must change the extension from RUN to SBX; better yet, use the ++PRAGMA SBX which automatically creates an SBX instead of a RUN. The extension "SBX" was chosen, rather than SBR, to eliminate confusion between machine language SBRs or XBRs for AMOS and BASIC SBXs for A-Shell, particularly for dealers that distribute their application on both AMOS and non-AMOS platforms. The search path for SBXs is the same as that for RUN programs (i.e. current [p,pn], [p,0], BAS:), unless the system parameter OPTIONS=SBX_RUNDIR is set, in which case the [p,0] part of the search path is replaced with the location whence the current RUN file was loaded.

Because of the SBX extension used by subroutines written in BASIC, these routines are often referred to, elsewhere in this document or in other documents, as SBX Modules or SBX Routines or simples SBXes.

The biggest difference has to do with parameter passing. Standard RUN programs do not receive parameters, except via the command line or via some indirect method (such as COMMON or a shared file.) Subroutines, on the other hand, generally receive parameters from the calling program, often updating one or more of them for return to the calling program. Parameter passing to/from SBXs is similar in concept to that to/from Functions and Procedures; see Subroutines vs. Functions/Procedures for a more detailed comparison. From the standpoint of the calling program, there is no difference in the way parameters are passed between a traditional subroutine and one that was written in BASIC. But from the standpoint of the subroutine itself, special techniques must be used to retrieve and return parameters. These steps are actually analogous to the procedure used in subroutines written in assembler under AMOS to process the parameters. In this case, however, you use special statements (X-ARGs) or MIAMEX functions rather than system library calls (as with AMOS subroutines) or direct binding (as with many other languages.)

Some other differences between SBXs and programs

•   SBXs must have a PROGRAM statement. Programs should, but it is optional.

•   Files opened within an SBX are not automatically closed at the end of the SBX unless the AS_SBXASRUN flag is set; see ASFLAG.

These and other differences and details specific to SBXs are explored in the following sections.