
               ͻ
                TOPSPEED / CLARION COMPILER PRAGMA LIST 
               ͼ

This is intended to be a (unofficial and untested) list of all the
TopSpeed and Clarion compiler pragmas, so I may have missed some or
got some descriptions wrong.

If you discover any errors in these files, please send corrections
and additions to me rather than distributing a modified version, so
that all may benefit from your contribution.
Similarily, if you have any additions, find any spelling mistakes,
then please contact me at:

        Clarion Software (Europe) Ltd
        Clare House
        Thompsons Close
        Harpenden
        Hertfordshire
        AL5 4ES
        UNITED KINGDOM

        Voice           +44 (0)1582 763999
        Fax             +44 (0)1582 768222
        BBS             +44 (0)1582 769666
        CIS             76711,1101
        Internet        76711.1101@compuserve.com

Paul Attryde
Clarion Software TopSpeed Technical Support
Revision 01


                        ͻ
                         Compiler Pragmas 
                        ͼ

      call          -  controls calling convention
      check         -  controls level of runtime checking
      data          -  controls size and name of data elements
      debug         -  controls information for debugging
      define        -  project utility pragma
      expr          -  for promotion of Pascal expressions
      link          -  specifies which  .obj  files may be linked
      module        -  specifies global options for a module
      name          -  controls construction of public symbol names
      optimize      -  sets compiler optimizations
      option        -  sets options
      project       -  passes string to project system
      save          -  saves entire pragma state
      restore       -  restores formerly saved pragma state
      warn          -  controls warning messages produced

      Old-style TopSpeed pragmas


           Ŀ
            #pragma call - Calling Convention Pragmas 
           

The call pragma controls the default calling conventions.

   alloca           -  stack frame modification
   c_conv           -  C calling convention
   ds_entry         -  register handler
   ds_eq_ss         -  controls where ds & ss point
   inline           -  inline functions
   inline_max       -  controls largest inline function
   interrupt        -  interrupt options
   iopl             -  IO privilege options
   near_call        -  near or far call
   o_a_copy         -  copy open array value parameters
   o_a_size         -  size of open array params passed on stack
   opt_var_arg      -  generate optimized entry sequencies
   overlay          -  use of DOS overlaying
   reg_param        -  register parameters
   reg_return       -  register return values
   reg_saved        -  register preservation
   result_optional  -  procedure handler
   same_ds          -  register handler
   s_copy           -  controls copying of value parameter
   seg_name         -  segment names
   set_jmp          -  informs of non-standard reg saving
   standard_conv    -  use standard calling convention
   standard_float   -  uses stack model for 8087
   t_l_copy         -  typeless parameters in procedures
   t_l_size         -  size of typeless parameters
   var_arg          -  variable number of arguments
   var_str          -  checks parameter match
   windows          -  Microsoft Windows option


Ŀ
alloca


 #pragma call(alloca => on)

This pragma is only used for internal library routines. The
purpose of this pragma is to modify the stack frame of the
calling function.  When using the alloca function you must
include the header file alloc.h.  This pragma must not be used
in a project file.

Ŀ
c_conv


 #pragma call(c_conv => on | off)

Default: off

The  standard_conv  pragma has the same effect for C and C++.
When  on , this option enables the Microsoft C calling convention.
This is when the compiler pushes function parameters in right to
left order on the stack and the caller pops these parameters off
the stack.  You should only use this pragma when interfacing to
Microsoft C code. You can also use the  cdecl  keyword for the
same effect.

Ŀ
ds_entry


 #pragma call(ds_entry => <name>)

Default: no value  (project system will not define).

 <name>  implies that DS will be loaded with the segment
 <name>_DATA  during execution of a function. If  <name>  is  null ,
then the compiler names the segment  _DATA . If  <name>  is none,
the compiler doesn't assume a fixed DS during function execution
and uses DS as a general purpose segment register like ES.

Ŀ
ds_eq_ss


 #pragma call(ds_eq_ss => on | off)

Default: on   for Small & Medium models
         off  otherwise

The  ds_eq_ss  pragma instructs the compiler whether or not to
assume that the DS and SS registers are pointing to the same
segment.  It also controls whether  VAR  parameters use 16 or 32
bit pointers.

Ŀ
inline


 #pragma call(inline => on | off)

Default: off

When  on , the compiler makes a copy of the function in the code
rather than using a call instruction.

You can use this convention for any function, but you typically
use it together with  reg_param  for simple machine-code
functions.

Ŀ
inline_max


 #pragma call(inline_max => <number>)

Default: 50 bytes of code

Controls the largest function which is inlined.  Note that
functions are (currently) not inlined if they have parameters
not passed in registers, or if the body has not been compiled
before the call.  The pragma takes effect for each call, so a
function may be called in different ways at different places.

Ŀ
interrupt


 #pragma call(interrupt => on | off)

Default: off

This substitutes an interrupt return instruction (IRET) for an
normal return (RET). This allows you to write interrupt service
routines. You can also use the  interrupt  keyword for the same
effect.  A special entry sequence is generated which preserves
all registers.  When using  call(interrupt=>on) , you should also
use  call( reg_param =>(), same_ds=>off ) .  The saved machine
register may be declared as parameters; the order depends on
whether c_conv is on.  The orders are:

ON:      es, ds, di, si, bp, sp, bx, dx, cx, ax, ip, cs, flags
OFF:     flags, cs, ip, ax, cx, dx, bx, sp, bp, si, di, ds, es

Ŀ
iopl


 #pragma call(iopl => on | off)

Default:  off

This is for OS/2 only.  This allows procedures to use input and
output instructions by giving the code segment  IO privilege .

Ŀ
near_call


 #pragma call( near_call => on | off)

Default: on   for small and compact
         off  otherwise

Specifies whether function calls are near or far.  When  on , the
compiler calls functions with near calls even if compiled in a
large code model.  The compiler can use only near calls if the
calling and called functions are in the same segment.  The
compiler checks for both functions to be in the same segment.

The call

 #pragma call(near_call=>off)

forces compiler to use far calls independent of the memory model

Ŀ
o_a_copy


 #pragma call(o_a_copy => on | off)

Default: on

Copy Open Array value parameters

When on, open array value parameters are passed as a copy on the
stack.

Ŀ
o_a_size


 #pragma call(o_a_size => on | off)

Default: on

Size of Open Array Parameters passed on stack

If on then Modula-2 passes the size of open array parameters on
the stack. This is the default Modula-2 behavior. May be needed
off for other language calls.

Has no effect for  value  parameter open arrays, unless the
 o_a_copy  pragma is set  off .

Ŀ
opt_var_arg


 #pragma call(opt_var_arg => on | off)

Default: off  for stack calling convention, and for the
              overlay and dynalink (in DOS) models with the JPI
              calling convention.
         on   for other models in the JPI calling convention.

Controls whether optimized entry sequencies are generated for
procedures with variable parameter lists.

Ŀ
overlay


 #pragma call(overlay => on | off)

Default: on   for overlay models and DOS dynalink models
         off  otherwise

Tells the compiler that DOS overlaying (overlay or dynalink
model) is being used.  The effect is that extra stack frames may
be generated for  far  routines, and far routine constants are
always laid out as double word pointers in memory.

Ŀ
reg_param


 #pragma call(reg_param => <reg>|<freg>{,<reg>|<freg>})

Defaults:

JPI calling convention:
   #pragma call(reg_param => (ax,bx,cx,dx,st0,st6,st5,st4,st3))

stack calling convention:
   #pragma call(reg_param => ())

TopSpeed C passes function parameters in machine registers
rather than using the stack. This generates smaller and faster
code.  This pragma has no effect on  struct  parameters which are
always passed on the stack.

The argument for reg_param is a register list, specifying what
registers should be used. Registers for parameters are allocated
left to right from the list. The table on the next page shows
how the compiler allocates registers.

Ŀ
 Parameter type                Possible registers            
Ĵ
1 byte (char,unsigned char)   ax,bx,cx,dx                    
2 bytes (int,unsigned int)    ax,bx,cx,dx,si,di              
4 bytes (long, unsigned long) ax,bx,cx,dx,si,di              
4 bytes (far pointers)        ax,bx,cx,dx,si,di for low word 
                              ax,bx,cx,dx,es,ds for high word
                              If either the low or high      
                              word cannot be allocated,      
                              then the whole parameter is    
                              passed on the stack.           
 4 and 8 byte floats          st0,st1,st2,st3,st4,st5,st6    


Ŀ
reg_return


 #pragma call(reg_return => (<reg>[,<reg>][,<freg>)

Default: reg_return=>(ax,dx,st0)

This lets you specify the registers to be used for return values
such as integer, pointer and floating point return values.
For example:

   #pragma call(reg_return => (bx,cx))

Ŀ
reg_saved


 #pragma call(reg_saved => <reg>|<freg>{,<reg>|<freg>})

Default: #pragma call(reg_saved => (si,di,ds,st1,st2))

This specifies what registers the function preserves. The
argument is a list that specifies the set of registers.

The default set preserves SI, DI and DS, ST1 and ST2:

You usually combine the  reg_saved ,  c_conv  and  reg_param
pragmas to call an assembler routine written for Microsoft or
Turbo C compilers.

Ŀ
result_optional


 #pragma call(result_optional => on | off)

Default: off

The  result_optional  pragma can be used to call a procedure
as a proper procedure without generating a compiler error.
For example:
   (*# save,
       call( result_optional => on ) *)
   PROCEDURE FuncProc( x : CHAR ) : CARDINAL;
   (*# restore *)

With this declaration, you can write both of the following:
   i := FuncProc('a');
   FuncProc('a');

Ŀ
same_ds


 #pragma call(same_ds => on | off)

Default: off  for XLarge, MThread, Overlay, Dynalink
         on   otherwise

When on, the called function does not load the data segment (DS)
register on entry. This will only be correct when the DS setting
of the calling function matches that of the called function. The
compiler checks for DS settings being equal.

Ŀ
s_copy


 #pragma call( s_copy => on | off)

Default: on

Controls whether a copy of a value parameter of string type is
(done inside the procedure).  This pragma can be used to make a
procedure more efficient if the procedure does not write to the
string parameter.

Ŀ
seg_name


 #pragma call(seg_name => <name>)

Default: Language dependent

Specifies the code segment name:

 call(seg_name => <name>)  means that the compiler places the code
for the function in segment  <name>_TEXT .  Consult the manuals of
the individual languages.

Ŀ
set_jmp


 #pragma call( set_jmp => on | off)

Default: off

This should only be used for the library routines which
implement non-local jumps.  The effect is to inform the compiler
of the non-standard register-saving properties of these
routines.

Ŀ
standard_conv


 #pragma call( standard_conv => on | off)

Default: on   for stack calling convention
         off  for jpi calling convention

This is normally set together with the  standard_float  option.
The effect on C and C++ programs is the same as the c_conv
pragma.

For Modula-2 and Pascal there is no effect.

Ŀ
standard_float


 #pragma call( standard_float => on | off)

Default: on   for stack calling convention
         off  for jpi calling convention

This is only on when using the stack models. It must be used
consistently throughout a program. When on the compiler uses a
stack model for the 8087, which means that the 8087 stack is
empty after each statement.

Ŀ
t_l_copy


 #pragma call( t_l_copy => on | off)

Default: off

Controls whether value typeless parameters are copied inside the
procedure.

The use of this pragma must conform to  t_l_size .  It is not
possible to copy the parameter if the size is not passed.

Ŀ
t_l_size

 #pragma call( t_l_size => on | off)

Default: off

Controls whether typeless parameters have their size passed.

If passed, it is possible to use the size function on the
typeless formal parameters to establish the size of the actual
parameter.

Ŀ
var_arg


 #pragma call(var_arg => on | off)

Default: off

When ON, this pragma disables the strict argument checking for
for number of arguments when calling a function. This should
be used with  c_conv  to call TopSpeed Modula-2 functions.

Ŀ
var_str


 #pragma call( var_str => on | off)

Default: off

Controls whether the compiler should check whether the actual
parameter matches the formal parameter.  The pragma only affects
 var  string parameters.  This pragma should not be used except
for the conversion of programs from TurboPascal, which has the
same feature.

Ŀ
windows


 #pragma call( windows => on | off)

Default: off

This is used to generate the special entry sequence which
Microsoft Windows requires for call-back routines.  It only has
an effect when  c_conv =>off and  near_call =>off



           Ŀ
            #pragma check - Run-Time Checking Pragmas 
           

The check pragma allows you to control the level of run-time
checking performed.

       field             -  field checking
       guard             -  guard checking
       index             -  array index checking
       nil_ptr           -  nil pointer checking
       overflow          -  overflow checking
       range             -  range checking
       stack             -  stack overflow checking



Ŀ
field


 #pragma check(field => on | off)

Default: off

Controls whether checks are performed on access to record fields
in records with tagfields.

Ŀ
guard


 #pragma check(guard => on | off)

Default: off

Controls whether checks are performed on guards.

Ŀ
index


 #pragma check(index => on | off)

Default: off

When on, the run-time system checks for an array index larger
than the array size. Use Utilities  Find run time error  to find
the cause of the problem.

Ŀ
nil_ptr


 #pragma check(nil_ptr => on | off)

Default: off

When on, the run-time system checks for any dereference of  NULL
pointers, generating a run-time error. Use Utilities  Find
 run-time error  to find the position of the error in the source.

Ŀ
overflow


 #pragma check(overflow => on | off)

Default: off

Numeric overflow checking:  enables overflow checks at run-time.
If on, then numeric overflow will cause a run-time error.

Ŀ
range


 #pragma check(range => on | off)

Default: off

Range checking:  checks that values for enumeration-type and
sub-range objects are within the defined range.

Ŀ
stack


 #pragma check(stack => on | off)

Default: off

Stack overflow check.

When on, the run-time system checks that the program does not
run out of stack space. You can increase the size of the stack
with the  data  pragma. Use Utilities  Find run-time error  to find
the cause of the problem.



           Ŀ
            #pragma data - Global Data / Heap Pragmas 
           

The data pragma controls the machine's allocation of global data
and controls the size of the run-time stack and the near heap.

    c_far_ext               -    externals interface to C and C++
    class_hierarchy         -    include hierarchy information
    const_assign            -    assign to a structured constant
    const_in_code           -    constant data location
    cpp_compatible_class    -    include compatible information
    ds_dynamic              -    dynamic pointer usage
    ext_record              -    volatile variables
    far_ext                 -    external variables
    heap_size               -    memory sizing
    near_ptr                -    pointer type
    packed                  -    record field packing
    seg_name                -    segment name
    share_global            -    global sharing data
    ss_in_dgroup            -    register control
    stack_size              -    memory sizing
    threshold               -    sizing segmentation
    var_enum_size           -    enumeration size
    volatile                -    volatile variables
    volatile_variant        -    variant records



Ŀ
c_far_ext


 #pragma data(c_far_ext => on | off)

Default: on   for overlay, dynalink XLarge & MThread
         off  otherwise

When on, the code generator does not assume that external
variables are in the segment specified by the  seg_name  pragma.

This pragma is only useful to interface to C and C++.

Ŀ
class_hierarchy


 #pragma data(class_hierarchy => on | off)

Default:  on

Controls whether information about class hierarchy is included
in the class descriptor (method table).  The information is used
by the IS operator and TypeGuards with check on.

Ŀ
const_assign


 #pragma data(const_assign => on | off)

Default: off

Controls whether it is possible to assign to a structured
constant.

OS/2 and Windows consideration: if const_in_code => on,
assignments to constants will result in protection violations.

Ŀ
const_in_code


 data(const_in_code => on | off)

Default: on   for xlarge, mthread, overlay & OS/2 dynalink
         off  otherwise (including DOS dynalink)

Controls whether code is put a code or a data segment.

Care should be taken when using this option in small models
as constants will not be addressable using 16 bit pointers.

Ŀ
cpp_compatible_class


 #pragma data(cpp_compatible_class => on | off)

Default: off

Controls whether the compilers includes extra information in
class descriptor.

Ŀ
ds_dynamic


 #pragma data(ds_dynamic => on | off)

Default: off

Dynamic pointers using Data Segment

When on allows the data segment to store dynamic pointers.
Should be turned off for the whole program under OS/2, if the
program passes messages containing segments to other processes.

Ŀ
ext_record


 #pragma data(ext_record => on | off)

Default: off

Coinciding variant fields in records

When on, you are allowed to have the same name for fields in
different variants of a record, if the fields have the same
offset within that record and have the same type.

Ŀ
far_ext


 #pragma data(far_ext => on | off)

Default: on   for overlay, dynalink XLarge & MThread
         off  otherwise

When on, the code generator does not assume that external
variables are in the segment specified by the  seg_name  pragma.

Ŀ
heap_size


 #pragma data(heap_size => <number>)

Default: Maximum size available

The pragma heap_size specifies the maximum size of the near
heap.  The near heap is the pool of free memory stored in the
default data segment (DGROUP) which you can access with a near
pointer.

The default near heap size (0xFFFF) occupies all the free space
in the data segment after the allocation of stack and
static data.

Under DOS, the far heap size depends on the total memory
available to a process when loaded. The heap size will be equal
to the size of the memory block at load time, minus the total
size of all code, static data, stack and near heap belonging
to the process.

Under OS/2, the far heap size depends on the system memory
configuration and available disk space for swapping.

Under Presentation Manager, the heap size pragma only controls
the library near size; it does not control the size of the PM
near heap.

Under Microsoft Windows, the heap size pragma has no effect.

Ŀ
near_ptr


 #pragma data(near_ptr => on | off)

Default: on   for small and medium models
         off  otherwise

Specifies whether data pointers are near or far. This pragma
also affects pointers generated by the & operator and by
implicit array to pointer conversions.

near_ptr is on by default in small and medium models, but OFF
in the other models.

Ŀ
packed


 #pragma data(packed => on | off)

Default: off

The  packed  pragma instructs the compiler whether to pack
record fields to a bit level wherever possible. e.g.

   (*#data(packed=>on)*)

   RECORD
     a,b:[0..31];   (* a and b will occupy only 5 bits each *)
     c,d:BOOLEAN;   (* c and d will occupy only 1 bit each  *)
   END;

Ŀ
data(seg_name)


 #pragma data(seg_name => <name>)

Default: Language dependent .  Project system does not set

 <name> specifies that the compiler places global, initialized,
data objects in a segment named <name>_DATA and global,
uninitialized data objects in a segment named  <name>_BSS. These
both have group name <name> and are in the FAR_DATA class. If
the size of a data object is larger than the global data
threshold, the compiler places the object in a separate segment.

You can also specify null, making the names _BSS and _DATA.
The compiler uses null in all models except for extra large
and multi-thread.

Ŀ
share_global


 #pragma data(share_global => on | off)

Default: off

This pragma is for OS/2 only. This causes the data segment to be
shared among different OS/2 processes. You could use this pragma
to allow different programs to communicate using shared
variables.

Ŀ
ss_in_dgroup


 #pragma data(ss_in_dgroup => on | off)

Default: on   for small and medium models
         off  otherwise

This pragma specifies if the stack is allocated in the default
data segment (DGROUP). This is true in the small and medium
models, but in the other models the stack is allocated in a
segment of its own. In the larger models, you could want the SS
register to equal the DS register when using Presentation
Manager, or when linking with third party libraries. You need
not specify this pragma under Presentation Manager or Microsoft
Windows.

Ŀ
stack_size


 #pragma data(stack_size => <number>)

Default: 16K

Specifies the size of the stack. You must place this pragma in
the file containing the main function. If the stack size cannot
be set to the specified size, the compiler uses the largest
possible size. For example:

   #pragma data(stack_size => 0x6000)
   main()
   {
     /* statements */
   }

makes the size of the run-time stack 0x6000 bytes (24K).
Project does not set default.

Ŀ
threshold


 #pragma data(threshold => on | off)

Default: Model dependent:
    small    meaningless;   compact   32767;    medium   meaningless;
    large    32767      ;   xlarge    65535;    mthread  65535      ;
    overlay  65535      ;   dynalink  65535

Threshold will determine the size at which the compiler will
place an object in a separate data segment.

Ŀ
var_enum_size


 #pragma data(var_enum_size => on | off)

Default: on

Force 2 bytes for enumeration values

When on, the value of enumeration constants will always be a two
byte value.

Ŀ
volatile


 #pragma data(volatile => on | off)

Default: off

When ON, the  volatile  pragma instructs the compiler that the
variables following it are likely to be changed at any time.
This is often the case with variables shared between multiple
processes or used by interrupt handlers. Setting this option
ensures that the compiler uses the stored value of the variable
at all times and does not keep the value in the processors
registers. This generates more object code (and may be slower)
but it makes sure that the correct value for the variable is
always used.

Ŀ
volatile_variant


 #pragma data(volatile_variant => on | off)

Default: off

Specifies whether the variants of a record structure are
volatile.



           Ŀ
            #pragma debug - Debug Information Pragmas 
           

The debug pragma allows you to control debugging options from
within source.

      line_num            -    generates line number information
      proc_trace          -    enables procedure tracing
      public              -    make private objects public
      vid                 -    generates information for VID



Ŀ
line_num


 #pragma debug(line_num => on | off)

Default: off

Generates non-VID line number information for debuggers such as
symdeb.  This information is stored in object files and printed
in the .MAP file.

Ŀ
proc_trace


 #pragma debug(proc_trace => on | off)

Default: off

When the  proc_trace  pragma is ON, the compiler
generates instructions to call the procedures EnterProc
and ExitProc on, respectively, entering and exiting every
procedure. These procedures can then perform any procedure
tracing you may require. The two procedures must be visible
to the module in which proc_trace is set ON. This means that
the module itself must define the procedures ExitProc and
EnterProc or the module must specifically import them using
the FROM IMPORT statement.

Warning: You should ensure that this pragma is OFF for
the EnterProc and ExitProc procedures themselves, otherwise
infinite recursion will occur and your program will crash.

Ŀ
public


 #pragma debug(public => on | off)

Default: off

This causes private objects to be made public to allow use of
debuggers such as symdeb.  It may cause duplicated public
warnings at link-time in languages such as C and C++ which do
not have a modular structure.  These warnings may be safely
ignored, although it is recommended that such functions should
be renamed to avoid possible confusion.

Ŀ
vid


 #pragma debug(vid => off | min | full)

Default: off

This pragma enables you to enable or disable the generation of
VID debug information for a single module. The pragma should
only be placed at the start of an implementation module.

 OFF   disables the generation of VID information.        ( /V0 )
 FULL  generates full VID information but disables some   ( /V2 )
       optimizations and sets VOLATILE for all variables.
 MIN   generates debug information, but affects the code  ( /V1 )
       less. The stackframe and variables may then not be
       accessible to VID.



           Ŀ
            #pragma define - Flag Definition Pragmas  
           

#pragma define(<name> => on | off [| <c-token>] )

Modula-2, Pascal, Clarion
 The argument can be on or off:  defines a boolean value to be
 true or false.

C and C++
 The argument can be:
  on        defines a macro
  off       undefines a macro
  c-token   defines the macro-body to be the token



Clarion uses this pragma quite extensively in its environment-
generated project files.  The settings I am aware of include:

Ŀ
maincode


 #pragma define(maincode=>on|off)

The switch "maincode" is used on the main module when libraries
are being made. When this switch is turned off, it forces the
compiler to call the main entry code procedure programname$main
instead of _main, avoiding duplication conflicts.

Ŀ
generated


 #pragma define(generated=>on|off)

The generated switch is used on source modules created by the
Application Generator.  The project system uses its existence
to flag generated modules for special processing. Generated
modules cannot be deleted from the project system, they must
be deleted from the Application Generator.  A generated source
module also cannot be changed to any other type of module from
within the project system.

Ŀ
zero_divide


 #pragma define(zero_divide=>on|off)

The zero divide pragma allows the programmer to determine the outcome of a
divibe by 0.  The default is on, which will allow zero divides and set the
result to 0. IE

        real = 9.9 / 0
        !real now equals 0

Setting this pragma to off will cause the program to stop with a runtime
error.

Ŀ
logical_round


 #pragma define(logical_round=>on|off)

Logical_rounding is a way of preventing some unexpected side effects of
rounding errors, automatic type conversion and truncating from reals to
long. The classic 'problem' is :-

 L1 LONG
    CODE
        L1 = 125
        L1 = L1 ^ 10 / L1 ^ 9
        TYPE(L1)

Giving 124 not 125. The reason is that the r.h.s of L1 = ... yields the
real number 124.99999999999999, which when truncated (by assigning to L1)
yields 124.

Now with logical_rounding set to on the compiler checks (upon truncation)
if the number being truncated is _very_ close (2 l.s.bits) of the number
above, if so it goes up, otherwise it truncates down.



           Ŀ
            #pragma expr - Expression Promote Pragmas 
           

#pragma expr(promote => on | off )

Default: on   in ansi mode
         off  otherwise

If the compiler is running with  expr(promote => off) , which is
default in non-ISO mode, there is no automatic conversion to
guarantee the result of a binary operation.

If, for example, two variables, which are represented as 16-bit
unsigned words, are operated on, the result of the binary
operation will be a 16-bit unsigned word.

If, however, the two expressions have different representation,
a conversion to a common type will be performed before the
operation according to the following table:

           Int1    Int2    Int4   Card1   Card2  Float4  Float8
        Ŀ
 Int1     Int1    Int2    Int4    Int2    Int4  Float4  Float8
 Int2     Int2    Int2    Int4    Int2    Int4  Float4  Float8
 Int4     Int4    Int4    Int4    Int4    Int4  Float4  Float8
 Card1    Int2    Int2    Int4   Card1   Card2  Float4  Float8
 Card2    Int4    Int4    Int4   Card2   Card2  Float4  Float8
 Float4 Float4  Float4  Float4  Float4  Float4  Float4  Float8
 Float8 Float8  Float8  Float8  Float8  Float8  Float8  Float8
        



           Ŀ
            #pragma link - Expression Promote Pragmas 
           

#pragma link(<name>[,<name>])

The link pragma allows you to specify the names of object files
to be linked  within the source code  rather than making that
specification in a project file.  The following example pragma
could be placed in the header file for a module:

         #pragma link(myhelp, mydump, mydest)

This pragma causes the files MYHELP.OBJ, MYDUMP.OBJ and
MYDEST.OBJ to be linked into any program that includes the
header file.

The following pragmas are meaningful to #dolink:

 #pragma link( file1.obj, file2.obj, file3.lib )
 #pragma linkfirst (initexe.obj)

The named files are to be included in the link.  If no extension
is given,  .OBJ  is assumed. Files specified using  #pragma link
are added to the end of the link-list. A file specified using
#pragma linkfirst is linked before the link-list. Only one file
may be specified using linkfirst.



           Ŀ
            #pragma link_option - Link Option Pragmas 
           

      map                 - map file generation
      vid                 - debug information control
      case                - case significant linking
      pack                - segment packing
      export              - export function name
      windows             - Windows executable
      oldexe              -
      pm                  -
      non_pm              -
      overlay             -
      stub                - Windows/OS2 stub filename
      smart_method        -
      share_const         - identical constant sharing



Ŀ
map


 #pragma link_option( map => on|off )

Controls whether a map file is generated with information about
segment sizes and publics etc.

Ŀ
vid


 #pragma debug( vid => off|min|full )

Controls generation of information in .exe/.dll file for use by
VID debugger.

Ŀ
case


 #pragma link_option( case => on|off )

Controls whether upper/lower case is significant when linking.

Ŀ
pack


 #pragma link_option( pack => on|off )

Controls whether segments are packed together.

Ŀ
export


 #pragma link_option( export => on|off )

This is required if a .exe file has exports (for example a
windows program). It is not required for .dll files (since these
are assumed to always have exports).

Ŀ
windows


 #pragma link_option( windows => on|off )

This is needed when linking a windows executable.

Ŀ
oldexe


 #pragma link_option( oldexe => on|off )

This is needed when linking a DOS format exe file.

Ŀ
pm


 #pragma link_option( pm => on|off )

(refer to old Modula-2 users manual (OS2 version) )

Ŀ
non_pm


 #pragma link_option( non_pm => on|off )

(refer to old Modula-2 users manual (OS2 version) )

Ŀ
link_option


 #pragma link_option( overlay => on|off )

This is required when linking a DOS overlay program

Ŀ
stub


 #pragma link_option( stub => <filename> )

This specifies the name of the stub file to be used
for an OS2 format executable.

Ŀ
smart_method


 #pragma link_option( smart_method => on | off )

Controls whether unused virtual functions should be eliminated
from executable files.  The default is ON except when producing
a DLL or dynalink-model executable file.  This option must be
set OFF if your program shares class objects with a dynamic link
library.

Ŀ
share_const


 #pragma link_option( share_const => on | off )

Controls whether identical constants will be commoned up in a
.EXE file. This option will affect identical string literals,
constant aggregates, and function bodies.  If your program
relies on comparing the addresses of functions or constants
which might be affected by this option, or on string literals
being distinct, you should set this option OFF.



           Ŀ
            #pragma module - Call Convention Pragmas  
           

         implementation   -  accessing common procedures
         init_code        -  run initialization code
         init_priority    -  defines priority for static objects
         smart_link       -  enables smart linker
         turbo_comp       -  for Turbo to TopSpeed conversion



Ŀ
implementation


 #pragma module(implementation => on | off)

Default: on

This pragma specifies whether or not an object file is
associated with a definite file.  This is used to access
procedures physically stored in common libraries containing many
modules.  The effect of the pragma, when off, is to stop Make
and the linker from assuming that a  .OBJ  file must exist for
this module.  The procedures and data defined are then assumed
to be present in one of the libraries imported into the project.
In the implementation part of a module, it overrides the default
naming of the  .OBJ  file corresponding to a module taken from the
module name.  When off, the object file name will be taken from
the file name, not the module name.

Ŀ
init_code


 #pragma module(init_code => on | off)

Default: on

When on, it implies that the module contains initialization code
which must be run when the program is loaded and before the main
module is executed.  Switchin the option off is useful for
modules written in other languages as it will stop the linker
warning of undefined symbols:

         (*# module( init_code => on) *)

If a modules sets this pragma off, then there is a knock-on
effect, i.e., all imported modules must also have  init_code  set
to off.

Ŀ
init_priority


 #pragma module(init_priority => <number>)

Default: 16  (Project system does not set a default)

Defines a priority for the initialization code for static
objects.  Normally the initialization order is undefined between
files, but this pragma allows you to control the initialization
order in that files with higher priority is initialized before
modules with lower priority.  The number must be a value between
0 and 32.  The C++ library uses values between 25 and 32.  It is
therefore not recommended to use values between 25 and 32; part
of the library may not have been initialized before user code is
executed.

Ŀ
smart_link


 #pragma module(smart_link => on | off)

Default: on

Setting this off disables the smart linking feature, to the
extent that either all or none of the objects in each segment
from a compiler will be included in a link.  This may result in
quicker linking, and also may allow other linkers (such as
Microsoft) to be used.

Note that there are many potential problems with trying to use a
non-TopSpeed linker, and we definitely do not recommend it.

Ŀ
turbo_comp


 #pragma module(turbo_comp => on | off)

Default: off

For use with Turbo to TopSpeed conversion.



           Ŀ
              #pragma name - Module Naming Pragmas    
           

Allows the specifying of prefix and case of public names used by
the compiler.  Necessary for inter-language conversion.

   prefix       -  specifies prefix of public names
   upper_case   -  enable conversion of public names to uppercase



Ŀ
prefix


 #pragma name(prefix => none | modula | c | os2_lib | windows )

Default: Language dependent

Specifies the prefix and case of the public names that the
compiler uses.  The public names are names for non-static
procedures and external data objects.
 none :     does not prefix with anything.
 Modula-2 : prefix with module name and  @  for data and  $  for
            procedures.
 c :        add an underbar  _  to all external names.
 os2_lib :  uses OS/2 library standard (prefix with module name).
 windows :  uses Microsoft windows external naming convention.

Ŀ
upper_case


 #pragma name(upper_case => on | off )

Default: off

Specifies whether public names should be converted to uppercase.
Use to interface to a language like Pascal or third party
libraries where necessary. Available in C and C++ only.



           Ŀ
             #pragma optimize - Optimisation Pragmas  
           

Sets the compiler optimizations

   alias       -  restricts functions to direct use only
   const       -  hold frequently used code in registers
   copro       -  controls instructions used by code generator
   cpu         -  controls code used by code generator
   cse         -  restricts common subexpressions
   jump        -  eliminates unnecessary jumps
   loop        -  uses loop depth
   peep_hole   -  perform a variety of machine-code translations
   regass      -  optimises register allocation
   speed       -  speed or space optimization
   stk_frame   -  restricts stack frames



Ŀ
alias


 #pragma optimize(alias => on | off )

Default: on

When  on , this allows the compiler to assume that variables in a
function will not also be used indirectly via a pointer in the
same function.  This assumption isn't strictly allowed in ANSI C
but is correct for all meaningful programs.

Ŀ
const


 #pragma optimize(const => on | off )

Default: on

When  on , the compiler will hold frequently used constants in
registers to produce faster code.

Ŀ
copro


 #pragma optimize(copro => emu | 87 | 287 | 387 )

Default: emu

This controls what instructions the code generator may use by
declaring which co-processor will be used.

emu emulates the 8087 (if it is not detected at run-time).

Ŀ
cpu


 #pragma optimize(cpu => 86 | 286 | 386 | 486 )

Default:         286  under OS/2
                 86   otherwise

This option specifies the target processor your code will run
on.  All the processors are upwards compatible; you can, for
example, run 8086 code on a 80286 processor or 80386 code on a
80486.  The higher the processor number, the more instructions
the compiler can take advantage of to improve code.

Ŀ
cse


 #pragma optimize(cse => on | off )

Default: on

When  on , the compiler minimizes evaluation of complete
expressions by keeping partial results in a temporary register.

Ŀ
jump


 #pragma optimize(jump => on | off )

Default: on

When on, the compiler will rearrange loops to eliminate as many
jumps as possible, thus generating faster code.

Ŀ
loop


 #pragma optimize(loop => on | off )

Default: on

When on,  the compiler uses the loop depth when eliminating
common sub-expressions  and performing  jump optimizations.
The result  of this optimization is faster, but potentially
larger, code.

Ŀ
peep_hole


 #pragma optimize(peep_hole => on | off )

Default: on

When on, the compiler performs a variety of machine-code
translations, generating smaller and faster code.

Ŀ
regass


 #pragma optimize(regass => on | off )

Default: on

When on, the compiler spends time finding the best
allocation of registers for variables. This results in fast
and tight code but slower compilation.

Ŀ
speed


 #pragma optimize(speed => on | off )

Default: on

When set to  on , TopSpeed C tries to make the code run as fast
as possible without regard for the code size. When set to  off ,
TopSpeed C tries to make the code as small as possible.  As an
example of the difference between  on  and  off , let us look at
a  for  loop. With  on , the compiler uses  nop  instructions to
place jump destination labels inside the  for  loop at even
addresses. The 80x86 architecture makes this much faster than
odd addresses.boundaries, but each  nop  adds another byte to the
code size. This means that with  off , the compiler eliminates
the extra  nop  instructions.

Ŀ
stk_frame


 #pragma optimize(stk_frame => on | off )

Default: on

When on, the compiler will only make stack frames where
required, thus eliminating the need to set up the BP
register. This  optimization can only be made when all
parameters and local variables for a function can be held
in machine registers.

When off, the compiler always sets up the BP register, thus
allowing a complete activation stack listing while
debugging.



           Ŀ
             #pragma option - Compiler Option Pragmas 
           

This pragma gives control over the compilation process

         ansi          -  ANSI keywords only
         bit_opr       -  allow bitwise operations on cardinals
         incl_cmt      -  preserve comments
         iso           -  ISO standard Pascal
         lang_ext      -  language extension option
         min_line      -  minmizes blank lines in output
         nest_cmp      -  nested comments option
         pre_proc      -  preprocessor output option
         prototypes    -  generate prototypes option
         uns_char      -  unsigned char option



Ŀ
ansi


 #pragma option(ansi => on | off )

Default: off

When on, disables the non-ANSI special keywords.  Certain
warnings should be considered as errors if the ANSI standard is
to be strictly adhered to.  See the Language Reference guides.

Ŀ
bit_opr


 #pragma option(bit_opr => on | off )

Default: off

When on, will allow bitwise operations on CARDINALs:

        p AND q ,  p OR q ,  NOT y , etc.

Ŀ
incl_cmt


 #pragma option(incl_cmt => on | off )

Default: off

Is only effective with pre_proc=>on

When on the compiler produces a file that will preserve
comments.

Ŀ
iso


 #pragma option(iso => on | off )

Default: off

When on, will only accept ISO standard Pascal.

Ŀ
lang_ext


 #pragma option(lang_ext => on | off )

Default: on

When on, the compiler accepts a number of constructs that are
invalid under ANSI C but are included in TopSpeed C for
compatibility with other compilers.

See the Language Reference document for details.

Ŀ
min_line


 #pragma option(min_line => on | off )

Default: on

Is only effective with pre_proc=>on

When on, the compiler produces a file with the minimum number of
blank lines.

Ŀ
nest_cmp


 #pragma option(nest_cmp => on | off )

Default: off

When on, it is possible to nest comments:

         /* An outside comment that
         contains /* a nested, inner comment
         */ within it */

Ŀ
pre_proc


 #pragma option(pre_proc => on | off )

Default:         off

When on, the compiler produces preprocessor output in a file
with the same name but with a  .i  extension.  This output makes
it easy to debug the result of macro expansions.

When on it also enables  incl_cmt  and  min_line .

Ŀ
prototypes


 #pragma option(prototypes => on | off )

Default: off

When on, the compiler writes prototype declarations to a new
file with the source filename and extension  .PT .  This file can
then be included using the  #include  directive in source files
that call these functions.  In this way, you get the advantage
of argument type checking for function calls, which results in
safer programming and better code generation.

See the C Language reference documentation.

Ŀ
uns_char


 #pragma option(uns_char => on | off )

Default: off

When on, values declared as  char  lie between 0 and 255.  When
of, such values lie between -127 and 128.



           Ŀ
             #pragma project - Project String Pragmas 
           

 #pragma project <string>

Passes string to project system.

The string should be a project file command or sequence of
commands, which will be executed in the project file whenever
the corresponding object file is added to the link list.  This
can be done either explicitly, using  #pragma link , or implicitly
due to a  #compile  or  #autocompile .  The intended use of this is
to be included in the link if a header file that defines the
interface to that library is included.



           Ŀ
           #pragma save/restore - Save/Restore Pragmas
           

 #pragma save
 #pragma restore

The  save  pragma saves the entire pragma state so one can restore
it subsequently with a  restore  pragma.  They work in a
stack-like manner, allowing nesting.  For example:

        /* save pragma state; enable interrupt convention */
         #pragma save
         #pragma call(interrupt => on)
        /* interrupt functions are specified here */
         #pragma restore




           Ŀ
              #pragma warn - Project Warning Pragmas  
           

The warn pragma customises which warning checks are performed

        wacc         -   class specifier without access specifier
        wait         -   assignment in test expression
        wall         -   sets all warnings
        watr         -   different  const  attributes
        wcic         -   constant object in code-segment
        wcld         -   possible loss of significant digits
        wclt         -   check suffix of  long  constant
        wcne         -   code has no effect
        wcor         -   value of constant is out of range
        wcrt         -   class definition as function return type
        wdel         -   delete statement expression
        wdne         -   declaration has no effect
        wdnu         -   variable declared but not used
        wetb         -   value of escape sequence is too big
        wfnd         -   function not declared
        wftn         -   far to near pointer conversion
        wnid         -   address for local variable not in DGROUP
        wnre         -   no expression in return statement
        wnrv         -   no return value in function
        wntf         -   near to far pointer conversion
        wovl         -   overload keyword
        wovr         -   integer overflow
        wpcv         -   pointer conversion
        wpic         -   parameter declaration compatibility
        wpin         -   default type promotion in parameter
        wpnd         -   function prototype not declared
        wpnu         -   parameter never used in function
        wprg         -   unknown pragma
        wral         -   returns address of local variable
        wrfp         -   function redeclared with fixed parameters
        wsto         -   storage class redeclared
        wtxt         -   unexpected text in preprocessor command
        wubd         -   poss use of variable before assignment
        wvnu         -   variable assigned but never used



Ŀ
wacc


 #pragma warn(wacc => on | off | err)

Default: on

Object-Oriented Error

This warning is issued if a base class specification does not
have an access specifier and the default access is used
(i.e., public for a  struct  and  private  for a class).

Ŀ
wait


 #pragma warn(wait => on | off | err)

Default: on

Assignment In Test Expression

When on or err, the compiler checks for a possible mistyping of
the C equality ( == ) operator, which contains two equals signs.
For example:

         if (x=y) printf("X equals Y");   /* is a mistake */

Ŀ
wall


 #pragma warn(wall => on | off | err)

Default: No value , project system does not set a default.

wall sets all warnings to on.

Ŀ
watr


 #pragma warn(watr => on | off | err)

Default: on

Different 'const' Attributes

When on or err, the compiler checks whether a function that
expects a pointer to a variable gets a pointer to a constant.

Ŀ
wcic


 #pragma warn(wcic => on | off | err)

Default: on

Const object in code-segment has non-constant initialiser

This warning is issued when the pragma  data(const_in_code =>on)
is on, and an object declared const has a dynamic initialiser
expression, i.e.,

               int funct();
               const int i = funct();

i in the example with be placed in the code segment, and is
updated by funct().  This is illegal in OS/2, where objects in
the code segment cannot be updated.

Ŀ
wcld


 #pragma warn(wcld => on | off | err)

Default: on

Conversion May Lose Significant Digits

When on or err, the compiler checks for a conversion from  long
or  unsigned long  to  int  or  unsigned int .

Ŀ
wclt


 #pragma warn(wclt => on | off | err)

Default: off

Constant Is Long

When on or err, the compiler checks for an integral constant
that has type long because of its value but does not have an L
suffix.

Ŀ
wcne


 #pragma warn(wcne => on | off | err)

Default: on

Code Has No Effect

When on or err, the compiler checks expression statements and
the left operand in a comma expression for no side effects.  For
example:

        x + y;  /* expression has no side effects */
        f, x;   /* left operand has no side effects */

Ŀ
wcor


 #pragma warn(wcor => on | off | err)

Default: on

Value Of Constant Is Out Of Range

When on or err, the compiler checks whether an integer constant
is in the range of an unsigned long, or a floating point
constant is in the range of a long double .

Ŀ
wcrt


 #pragma warn(wcrt => on | off | err)

Default: on

Class Definition as Return Type Missing  ;  after  }

This warning is issued if a class is defined in a function
return type specification.  Such a constant is legal, but
unusual, and frequently results from omitting a semicolon
between a class definition and the following function
declaration.

Ŀ
wdel


 #pragma warn(wdel => on | off | err)

Default: on

When on, the expression between [] in the delete statement is
obsolete and will be ignored.

Ŀ
wdne


 #pragma warn(wdne => on | off | err)

Default: on

Declaration Has No Effect

When on or error the compiler checks for a declaration that has
no meaning, for example, long int; .  A declaration should
contain a variable declarator, a structure or union tag, or
members of an enumeration.

Ŀ
wdnu


 #pragma warn(wdnu => on | off | err)

Default: on

Variable Declared But Never Used

When  on  or  err , the compiler checks whether a local variable has
been declared but never used in the function.

Ŀ
wetb


 #pragma warn(wetb => on | off | err)

Default: on

Value Of Escape Sequence Is Too Big

When on or err, the compiler checks that an escape sequence is
in the range 0 to 255.

Ŀ
wfnd


 #pragma warn(wfnd => on | off | err)

Default:         off

        Function Not Declared

When  on  or  err , the compiler checks for functions that have been
called but not declared.  If these functions occur, TopSpeed C
assumes that the function is an  extern  function returning an
int.

Ŀ
wftn


 #pragma warn(wftn => on | off | err)

Default: on

Far To Near Pointer Conversion

When on or err, the compiler checks for conversion of a 32-bit
far pointer to a 16-bit near pointer.

Ŀ
wnid


 #pragma warn(wnid => on | off | err)

Default: on

Address For Local Variable Not In DGROUP

When on, the compiler checks that a local variable does not have
its address taken in small model when using the pragma:

         #pragma data(ss_in_dgroup => off)

Ŀ
wnre


 #pragma warn(wnre => on | off | err)

Default: off

No Expression In Return Statement

When on or err, the compiler checks for a return value in a
non-void function.  This should be  off  if compiling old-style C
without prototypes.

Ŀ
wnrv


 #pragma warn(wnrv => on | off | err)

Default: off

No Return Value In Function

When on or err, the compiler checks for a return statement in a
non-void function.

Ŀ
wntf


 #pragma warn(wntf => on | off | err)

Default: on

Near To Far Pointer Conversion

When on or err, the compiler checks for a conversion of a 16-bit
near pointer to a 32-bit far pointer.

Ŀ
wovl


 #pragma warn(wovl => on | off | err)

Default: on

Overload keyword obsolete.

Ŀ
wovr


 #pragma warn(wovr => on | off | err)

Default: on

Integer Overflow

When  on  or  err , the compiler checks for the overflow of a
constant integer expression.

Ŀ
wpcv


 #pragma warn(wpcv => on | off | err)

Default: on

ANSI Pointer Conversion Violation

When on or error, the compiler checks for a conversion between
two incompatible pointer types, or between a pointer and an
integral type.

Ŀ
wpic


 #pragma warn(wpic => on | off | err)

Default: on

Parameter Declaration Compatibility

When on or err, the compiler checks if a parameter declaration
is incompatible with the corresponding parameter in a previous
function declaration.

Ŀ
wpin


 #pragma warn(wpin => on | off | err)

Default: on

Default Type Promotion On Parameter

When on, the compiler compares the declaration of a parameter in
an old-style function definition with the prototype for
incompatible argument promotions.  For example:

         int func(char);        /* parameter declared as char */
         int func(IntegerByPromotion)
         char IntegerByPromotion;       /* incompatible */
         {
           ...
         }

NB: this violates the ANSI standard on compatible function
declarations.

Ŀ
wpnd


 #pragma warn(wpnd => on | off | err)

Default: off

Function Prototypes Not Declared

When on or err, the compiler checks whether a function has a
prototype associated with it.  Prototypes are important to
TopSpeed C since it cannot do much type checking without them.
You should, therefore, declare prototypes for all functions.  It
is best to keep this warning on or err.

Ŀ
wpnu


 #pragma warn(wpnu => on | off | err)

Default: off

Parameter Never Used In Function

When on or err, the compiler checks for a parameter that the
code never uses, so declarations of dummy parameters generate
warnings.

Ŀ
wprg


 #pragma warn(wprg => on | off | err)

Default: on

Unknown Pragma

When on or err, the compiler checks for foreign pragmas or
mistakes in TopSpeed C pragmas.  If you are only creating code
using TopSpeed C pragmas, you should switch this warning to
either  on  or  error .

Ŀ
wral


 #pragma warn(wral => on | off | err)

Default: on

Returns The Address Of A Local Variable

When on or err, the compiler checks for a return statement that
returns the address of a local variable.  This causes a problem
because C reclaims the variable storage on completion of the
function.  The pointer, therefore, points at undefined data.

Ŀ
wrfp


 #pragma warn(wrfp => on | off | err)

Default: on

Function Declared With Fixed Parameters

When on, the compiler checks for a prototype with a variable
number of arguments, but the corresponding function definition
specifies a fixed number of arguments.  This will work in
TopSpeed C, but it is a violation of the ANSI C rules for
compatible function declarations and therefore not portable.

Ŀ
wsto


 #pragma warn(wsto => on | off | err)

Default: on

Storage Class Redeclared

When on or err, the compiler checks that the same variable has
not been declared differently within the program.  For example:

         int         x;   /* external linkage */
         static int  x;   /* internal linkage */

The static storage class always takes preference.

Ŀ
wtxt


 #pragma warn(wtxt => on | off | err)

Default: on

Unexpected Text In Preprocessor Command

When on or err, the compiler checks for a newline character
terminating a preprocessor command.

Ŀ
wubd


 #pragma warn(wubd => on | off | err)

Default: on

Possible Use Of Variable Before Assignment

When on or err, the compiler checks if a local variable has been
used before it has been assigned a value.  TopSpeed C check this
warning with a simple scan through the function, which can cause
gotos, etc., to generate false warnings.

Ŀ
wvnu


 #pragma warn(wvnu => on | off | err)

Default: on

Variable Is Assigned But Never Used

When on or err, the compiler checks whether a local variable has
been declared and assigned a value but never used.



               Ŀ
                Old-Style Compiler Directives 
               

The $ compiler directives were first used in TopSpeed version
1.x, and are still supported in the present compiler for
backwards compatibility, although some directives have been
replaced by newer compiler pragmas.

Ŀ
Old-style compiler directives


In the list of old-style directives that follow, the default
value for the directive has been written in UPPERCASE.

$A +/-  ENABLE/disable aliased behavior on global variables.
        The compiler will assume that variables declared with
        the directive disabled cannot be accessed directly and
        indirectly at the same time.

$B +/-  INCLUDE/exclude a control-break handler in the program.
        The handler can be dynamically enabled and disabled with
        library procedures.  The directive must be in the main
        module.

$C h    Specifies which registers will be preserved by
        procedures. The hexadecimal number h specifies the
        registers, based on the following values:

                AX=1    CX=2    DX=4    BX=8
                DS=10   ES=20   SI=40   DI=80

        The BP register is always preserved.  Default
        configuration is F0H = DS+ES+SI+DI, specified
        as (*$C F0*)

$D n    Specifies the name, n, of the data segment in which to
        put the global variables declared by the module.  The
        default is to use the module name.  In any case, the
        name is prefixed by D_.  If used, this directive must
        appear before the MODULE keyword in both definition and
        implementation files.

$E +/-  Enable/DISABLE relaxed alias treatment of variant
        records. Because of overlapping the compiler will
        normally consider fields of variant records volatile,
        causing them to be kept in memory.

$F      Procedures will be called with FAR calls. Likewise,
        procedure types are 32-bit.  This is the default, and
        applies only to global procedures; local procedures are
        always called with NEAR calls.

$G +/-  ENABLE/disable module prefixes in external names.

$H +/-  Enable/DISABLE treating constant aggregates as
        variables, thereby allowing them to be modified.

$I +/-  Enable/DISABLE index checking.  If enabled, accessing a
        non-existant array element will produce a run-time
        error.  All variables are assumed to hold legal values
        corresponding to their type (see $R below). Likewise,
        type transfer on indices is assumed not to cause
        problems.

$J +/-  Enable/DISABLE interrupt procedures, by generating IRET
        instead returns instead of the normal RET instruction.

$K +/-  Enable/DISABLE the C calling convention for proceedures.
        The specifies that caller (not called) pops parameters.
        Across calls, the DS register is set to the group named
        'DGROUP'.

$M n    Specifies the name, n, of the code segment in which to
        put code. The default is to use the module name.  In any
        case, the name is prefixed by C_.  When used, this
        directive must appear before the MODULE keyword in both
        definition and implementation files.

$N      When used, procedures will be called with NEAR calls.
        This requires callers to be in the same code segment.
        Likewise, procedure types are 16-bit.

$O +/-  Enable/DISABLE overflow checking on whole number
        operations. If this directive is enabled, a numeric
        overflow will cause a run-time error.

$P +/-  Enable/DISABLE generating external names for local
        procedures. Enabling eases debugging but can cause name
        clashes.

$Q +/-  Enable/DISABLE procedure tracing.  If enabled,
        procedures will generate a INT 60H on entry and INT 61H
        on exit.  Handlers for these interrupts must be
        installed explicitly - EG using module ProcTrace.

$R +/-  Enable/DISABLE subrange checking.  If enabled, a run-
        time error is generated by assignment of parameter
        passing if the value is outside the bounds of the
        receiver's type.

$S h    The hexadecimal number, h, specifies the amount of stack
        allocated for the program.  The directive must be in the
        main module.

$S +/-  Enable/DISABLE stack overflow checking.  If this
        directive is enabled, a run-time error is generated if
        stack space is exhausted.

$V +/-  ENABLE/disable copying of open array value parameters.
        Disabling such copying increases efficiency but is
        potentially incorrect.

$W +/-  Enable/DISABLE the use of volatile variables.  Volatile
        variables are not kept in registers across statements.
        The ability to use volatile variables can be essential
        if concurrent processes communicate via shared global
        variables, and can make debugging easier.

$X +/-  Enable/DISABLE 8087 stack spilling for procedures.
        Spilling is necessary if nested function calls exhaust
        the 8087 stack. Spilling involves saving excess values
        from floating point computation on the hardware stack.

$Y +/-  Enable/DISABLE coinciding variant fields in a record. If
        enabled, it's legal to use the same name for fields in
        distinct alternatives, provided these fields have the
        same type and are at the same offset in the record.

$Z +/-  Enable/DISABLE checks for dereferencing of NIL pointers,
        which then generate a run-time error. When enabled, all
        local variables are initialised to 0.  If enabled in the
        main module, global variables are also zeroed.



Ŀ
Conversion of old-style compiler pragmas


In the original version of TopSpeed Modula-2, compiler
directives starting with a $ were used to specify compiler
options. These directives will still be accepted in this version
of TopSpeed Modula-2, with the following exceptions:

-$B (Ctrl-Break handler).
    This is no longer supported. Use Lib.EnableBreakCheck.

-$D (data segment name).
    This is  supported, but adds the suffix _BSS (for
    uninitialized data) or _DATA (for initialized data) to the
    name instead of the D_ prefix.

-$J (use IRET instead of RET).
    This is not supported. Instead, you should use the pragma:

        (*# call( interrupt => on ) *)

    However, you may find that you have to make other changes
    as well as the effect of the pragma is different from the
    $J directive:

-$K (C calling convention).
    This is not supported. Instead, you should use the pragma:

        (*# call( c_conv => on ) *)

-$M (code segment name).
    This is supported but adds the suffix _TEXT to the name
    instead of the C_ prefix.

-$P (external names for local procedures).
    This is no longer supported. It is no longer applicable.

-$Q (procedure tracing).
    This is no longer supported. Instead, you should use:

        (*# debug( proc_trace => on ) *)

    This enables a different method of tracing procedures. Refer
    to the proc_trace pragma for further details.

-$X (80x87 stack spilling).
    This is no longer supported (and is no longer necessary).

-$Z (NIL pointer checks).
    This still does NIL pointer checks but no longer clears
    memory.

-$@ (preserve DS).
    This is no longer supported.

The support for these directives has been included with later
systems so that your old programs and modules will recompile
with minimum changes. However, you should avoid using the old
directives with new programs, and use pragmas instead.



