++PRAGMAs

Updated February 2013 (see PRIVATE_...)

++PRAGMA <pragma> {options}

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

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.
TRACE_BEGIN and _END	Enable and disable automatic tracing of all enclosed statements
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.
AUTO_LARGE_CONSTANTS	Causes the compiler to automatically supply the "L" suffix to any integer constant, as appropriate.
LSX_FSPEC	Provides a way to assign a name to the LSX file that includes the vedit field of the program version.
FORCE_F1_HDR <boolean>	Forces a toggle of the /F1 switch.
EMBED_DEFSTRUCT	See Structure Definition Embedding.
EMBED_DEFSTRUCTS_BEGIN and EMBED_DEFSTRUCTS_END	See Structure Definition Embedding.

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 equivalent, though previously, the first one would have triggered an invalid argument error:

++pragma ERROR_IF_NOT_MAPPED

++pragma ERROR_IF_NOT_MAPPED "TRUE"

A-BASIC PRAGMAs

The following PRAGMAs from A-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

MAP1 variables are 2-byte aligned (ALIGN2) by default. Variables at all other MAP levels are always single-byte aligned. The ALIGN4 and ALIGN8 pragmas (for 4 and 8 byte alignment) may be more efficient on some 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.