Calling External Routines
A key feature of ASB is the XCALL statement, which provides the ability to call routines that are external to the current program. The feature was included in the original BASIC to allow calling of subroutines written in assembly language, which could perform low-level or CPU-intensive actions that were not otherwise possible in BASIC. In the A-Shell environment, no one writes code in assembler any more, but the feature is widely used for:
| • | Calling one of the hundreds of subroutines written in C by MicroSabio and which are embedded in the A-Shell run-time environment. Many of these are rewritten versions of assembler routines which were popular in older environments, such as BASORT, INFLD, SPOOL, etc. |
| • | Calling subroutines written in ASB by independent developers, which are compiled into .SBX modules that are loaded from disk on demand and subsequently cached in memory. |
A-Shell supports the following syntax variations of the XCALL statement:
xcall NAME {,arg1, arg2, ... argN}
vxcall <stringexpr> (arg1, arg2, ... argN)
The first variation, with the parameter list separated from the subroutine name by a comma, is the original syntax supported all the way back to BASIC 1.3. The second variation, with the parameter list enclosed in parentheses, is an A-Shell extension; see History, below. The third variation, VXCALL, is another A-Shell extension that differs from XCALL in that the subroutine name is a string variable interpreted at run-time, rather than a literal interpreted at compile-time; see Calling Variably-Named Routines for more information.
Parameters
name
The literal name of the subroutine, made up of one to ten characters alphabetic and numeric characters. The first character must be alphabetic, case insensitive. Must match the name of a subroutine embedded within A-Shell, or the name of an external subroutine with an SBX extension. Traditionally, subroutine names were limited to six characters and were compiled into 4 rad50-encoded bytes in the RUN file. The standard search path for SBX modules is: current [p,pn], then [p,0], then dsk0:[7,6]. An alternate search path variation can be enabled with the SBX_RUNDIR flag (current [p,pn], .RUN location, then dsk0:[7,6].) Once the SBX is located on disk, its modification timestamp is compared to the previously-cached version in memory (if present), and the file is loaded from disk if necessary. Otherwise, the cached version is reused, reducing the calling overhead for subsequent calls dramatically.
stringexpr
A variable or expression evaluating to the name of the subroutine; one to ten alphabetic and numeric characters, case insensitive, no extension.
arg1, arg2, ... argN
From 0 to 1023Expressions passed as arguments to the subroutine. Any arguments passed in the form of variables may potentially be updated by the routine, although it is impossible to know which ones just from looking at the subroutine statement syntax.
See Also
History
2014 October, A-Shell 6.1.1392, compiler edit 718: You may now optionally use procedure-style syntax with the XCALL statement. In other words, instead of: XCALL NAME,ARG1,...ARGN, you can instead use XCALL NAME(ARG1,...ARGN). The advantage of the alternate syntax is perhaps mainly aesthetic, but will seem more natural to programmers coming from other language backgrounds.
