Description
Subroutines are conceptually similar to Functions and Procedures but evolved from different origins. They fall into three categories:
In-Program Subroutines: These are basically just glorified GOTOs. They consist of a group of statements in the main body of your program, preceded by a label that can be referenced in a CALL or GOSUB statement, and ending in a RETURN, such as:
CALL FOOBAR
...
FOOBAR:
...
RETURN
These subroutines do not exist outside the running program, and cannot be called or otherwise referenced by other programs. To avoid confusion, these will henceforth be referred to as “GOSUBs”, while “subroutines” will be understood to refer only to the following categories.
Embedded Subroutines: For historical reasons, many frequently-used subroutines are built into A-Shell. They are written in C and have been linked into the A-Shell executable. You can call them from within any program, without reference to any files or folders. See Introduction to Subroutines for a more complete discussion.
SBX Subroutines: These are programs written in A-Shell BASIC and compiled into a subroutine format and filename (“.sbx”). The compiled programs are placed into one of the directories in the A-Shell environment SBX search path, and can then be called by any program without need to specify a location or full filespec. See SBX Subroutines for a more complete discussion.
Embedded and SBX subroutines are called using one of the following statement types:
XCALL name {, param1, ..., paramN}
VXCALL string-expr {, param1, ..., paramN}
XCALL requires a literal name, whereas VXCALL takes a string expression that evaluates to the target subroutine name. Note that SBX routines can also be invoked as functions; see External (XFUNC) Functions for details.
Organization
As mentioned above, the embedded subroutines are built into the A-Shell executable You never need to worry where they are, and you cannot modify them. You can, however, rename them, and thereby modify their behavior via the ALIAS and SBR directives in the system configuration file.
The SBX subroutines, hereafter referred to by their extension “SBX,” are individual files residing in the SBX search path. They originate from separate sources:
Included with A-Shell: these subroutines are installed along with the rest of A-Shell, and are documented in the “Subroutines” section of this document.
Your SBXes are those you have written for your application(s).
Shared SBXes are those maintained in the A-Shell Shared Open Source Library (SOSLIB), which you need to retrieve and install. These are programs written by MicroSabio or A-Shell developers and made available to the A-Shell community.
A final category of subroutines is External Library Functions. They are typically housed in DLLs for Windows and .so files for Linux. If the routine/function has a C-compatible interface, and most do, it can be called from A-Shell using the embedded subroutine DYNLIB.
Here is a diagram which provides a possibly-helpful visual of the relationship between the various components being discussed:
See Also:
