A-Shell Extensions

Development Topics > BASIC Extensions

A-Shell Extensions

In addition to the AlphaBASIC and AlphaBASIC Plus statements, A-Shell also supports a set of statements which are only available under A-Shell—i.e., are not part of the AlphaBASIC environment. These statements are listed in the table below, and are referred to as the A-Shell Extensions. To invoke these extensions, use:

• /X:2 to create a standard .RUN file

• /X:3 to create an .SBX file

Note that /X:3 does not disturb an existing .RUN, so it is possible to compile the same source into both a .RUN and a .SBX, as follows:

.COMPIL MYPROG/X:2 ; create MYPROG.RUN

.COMPIL MYPROG/X:3 ; create MYPROG.SBX

However, in order to make this workable, you'll need to modify the ASHINC:XCALL.BSI file to merely set a flag indicating if it is running in SBX mode or not, instead of aborting with an error message if run directly using RUN MYPROG. You would then test that flag to decide whether to pick up and return parameters.

Extension	RC?	Meaning
Three-D Print Tab	Note 1	Tab(x,y,z).
Comment	Yes	Comment may follow an & on a continuation line
Conditional Compilation Statements	Yes
DEBUG		Control variable. If /DEBUG compile switch specified, acts as if it equals 1, otherwise 0. If /DEBUG switch is not specified, then it may still be activated at runtime by using SET DEBUG, or MX_DEBUG,op,debugvalue. Note that for backwards compatibility, mapping DEBUG explicitly as an ordinary variable will disable the control variable DEBUG. Also see DEBUG.xxxx below.
DEBUG statements		See TRACE and DEBUG Statements.
Defined Structures	Yes	Allows you to assign a type name to a set of MAP statements and then use that as if it was a data type.
DIMX		Enhanced dynamic array allocation
Dot Variable		Read-only system variables.
Dot Functions		Reserved-word functions.
DPRINT	Note 3	Like PRINT but creates a static text control using the current default GUI (proportional) font and with the sunken attribute. (Note that if the /X:2 switch not specified, TPRINT is compiled as PRINT.) Intended for displaying data fields.
		Dynamically-Sized S and X Variables.
ELSEIF Clauses		One or more ELSEIF clauses may be inserted into an extended IF/ELSEIF/ELSE/ENDIF statement.
ERROR <message>		Causes the message to be displayed and is treated as a compiler error. This is particularly useful in conjunction with conditional compilation, as shown in the preceding example.
MAP Statement		PRIVATE and PUBLIC keywords for fine tuning scope of variables (MAP or DIMX).
INCLUDE Nesting		Nesting to 13 levels deep
INPUT CSV		Input comma separated values
INSTR()		When the fourth parameter (flags) is specified (even if 0), the pattern is treated as a regular expression.
Line length	Yes
MESSAGE <message>		Equivalent to ++ERROR <message> except that no error is generated. It is useful primarily for giving you visual feedback during compilation that your conditions are working as expected. See prior example.
PAD		Pad a string with spaces
PRAGMAs	Yes	Compiler directives.
Procedures
REDIMX		Re-dimensions an array originally created with DIMX.
RETURN (<expression>)		Return value from XFUNC
Shortcut Operators
SIZEOF(VAR)	Yes	Used to reference the size of a previously mapped variable. For example: MAP1 VAR2,S,SIZEOF(VAR1) or X = Y * SIZEOF(Z). Note also that it is possible to use sizeof(var) to reference the size of the immediately preceding variable even when it is a structure.
TPRINT	Note 2	Same as DPRINT but without the sunken effect. Also note that SET AUTOTPRINT causes all PRINT statements to behave at runtime as if they were compiled as TPRINT.
TRACE and DEBUG Statements	Note 3	These statements open, print to, and close the debug message window.
Underlines in variable names	Yes	Variable names (and constants) may contain underlines. Although this has no special meaning, by convention it is used primarily with constants.
User-defined Functions
WRITECD		Output comma delimited values
WRITETD		Deprecated; see WRITECD for important note. Old documentation: same as WRITECD, except that it outputs Tab delimiters instead of comma delimiters.
Subroutine Name Length		XCALL names may be up to 10 characters long.
XFUNC		Call an external (SBX) function
XGETARG, XGETARGS		Retrieve XCALL parameters. See XGETARG, XGETARGS, XPUTARG.
XPUTARG		Return XCALL parameters. See XGETARG, XGETARGS, XPUTARG.
XREAD and XWRITE		Allow record access via explicit record numbers.

Note 1: Compiler ignores "z" value

Note 2: DPRINT / EPRINT / TPRINT are compiled as if PRINT

Note 3: TRACE.xxxx / DEBUG.xxxx are compiled as XCALL EVTWIN; need to supply AMOS implementation.