PRAGMAs

Updated February 2013 (see PRIVATE_...)

PRAGMAs are commands to the compiler to specify compilation options or otherwise modify its behavior. The general syntax is:

++PRAGMA <pragma> {options}

For example:

++PRAGMA FORCE_EXT "LIT"

where the available pragmas and associated options are listed in the tables below.

A-Shell PRAGMAs

The following PRAGMAs are supported only when A-Shell Extensions are enabled (X:2 compiler switch).

A-Shell PRAGMA	Description
ALIGN2	Align MAP1 variables on 2 byte boundaries (default). See Alignment below.
ALIGN4	Align MAP1 variables on 4 byte boundaries. See Alignment below.
ALIGN8	Align MAP1 variables on 8 byte boundaries. See Alignment below.
EXTERN_BEGIN, EXTERN_END	Bracket MAP statements used to declare Global/External Variables.
SBX	Same as /X:3 (create an SBX instead of RUN).
TRACK_LAST_ROUTINE <boolean>	Updates .LAST_ROUTINE (see Dot Variables) each time a function or procedure is called.
TRACK_LAST_LABEL <boolean>	Updates .LAST_LABEL (see Dot Variables) each time execution passes a label in the program.
AUTO_EXTERN <boolean>	Used within User-Defined Functions or Procedures to allow the use of global variables within the local routine. Also see Global/External Variables.
PRIVATE_BEGIN and _END	Used within ++include files to ensure that the module's private variables (MAP and DIMX) are initialized once and only once before they are used.
GLOBAL_BEGIN and _END	Similar to PRIVATE_BEGIN and PRIVATE_END, except that they declare a block of variables intended to be visible to any other module in the program.
ASHELL_EXTENSIONS <boolean>	Enables/disables the switches /X:2, /P, and /PX respectively. The <boolean> argument is optional and defaults to "TRUE". Must be placed before any other code, except for comments, ++pragmas, ++IFxxx conditionals, and the PROGRAM statement.
PRE_PROCESS <boolean>
EXTENDED_PRE_PROCESS <boolean>
INCLUDE_GLOBAL_ONCE_ONLY <boolean>	When enabled, ++include is treated as ++include'once, except when it occurs inside a function or procedure. In such cases, it is likely that you are intentionally including an extra copy of some map statements.

BASIC Plus PRAGMAs

The following PRAGMAs are supported in BASIC Plus mode (X:1 compiler switch).

BASIC Plus PRAGMA	Description
NO_LINE_NUMBERS <boolean>	Same as /O
ERROR_IF_NOT_MAPPED <boolean>	Same as /M
FORCE_24_BIT <boolean>	Same as /A
FORCE_EXT "ext"	Force compiler output to use "ext" extension instead of .RUN.
FORCE_FSPEC	Allows you to change the name of the output file.
FORCE_IEEE <boolean>	Forces a floating point variable which does not have an explicit size to be treated as F,8 (rather than F,6). Also requires /X:1 or higher.
FORCE_OLD_ISAM <boolean>.	This is the equivalent of /I, causing the compiler to assume ISAM 1.x for OPEN statements that are otherwise ambiguous. Unlike /I, it can be turned on and off for different sections of the source code.

Valid replacements for the "boolean" argument are (not case sensitive): "YES", "TRUE", 1 or "NO", "FALSE", 0. Beginning with A-Shell 6.3.1528, the default for all pragmas accepting a <boolean> argument is "TRUE". Previously some of them required an explicit argument while others did not. For example, the following two are now equivalent, though previously , the first one would have triggered an invalid argument error:

++pragma ERROR_IF_NOT_MAPPED

++pragma ERROR_IF_NOT_MAPPED "TRUE"

AlphaBASIC PRAGMAs

The following PRAGMAs from Alpha BASIC Plus are recognized but ignored by A-Shell because the associated function is not important or relevant under A-Shell. The important point is that by being recognized, they do not generate compile errors, thereby keeping your code (more) source-compatible with AMOS.

• FORCE_SBR_EXT (see FORCE_EXT and SBX)

• LIFESIGNS (hardly needed when compilation time is measured in milliseconds)

• ADD_EXTRA_STRWRK (A-Shell's string work area can use the entire memory partition)

• EXTRA_STRWRK

• SET_SETWRK

Alignment

Align MAP1 variables on 8 byte boundaries. Aligning on 4 or 8 byte boundaries may be more efficient on modern processors, and can be useful for matching data layouts originating in other languages (such as C). But beware of the effect this can have when using map overlays. For example:

MAP1 A1,S,5

MAP1 A2,S,5

MAP1 AX,S,16,@A1

Under the normal 2-byte alignment, A2 will start in the 6th position of the AX overlay. But with 4 byte alignment, it would start in the 8 position.