Click above to get retro games delivered to your door ever month!

The following form of the auxiliary pragma can be used to describe the way a
function is to be called.

+--------------------------------------------------------------------------+
|      #pragma aux sym far [;]                                             |
|          or                                                              |
|      #pragma aux sym near [;]                                            |
|          or                                                              |
|      #pragma aux sym = in_line [;]                                       |
|                                                                          |
|      in_line ::= { const | (seg id) | (offset id) | (reloff id)          |
|                          | (float fpinst) | "asm" }                      |
|                                                                          |
+--------------------------------------------------------------------------+

where
    description

sym
    is a function name.

const
    is a valid C/C++ integer constant.

id
    is any valid C/C++ identifier.

fpinst
    is a sequence of bytes that forms a valid 80x87 instruction.  The
    keyword float must precede fpinst so that special fixups are applied to
    the 80x87 instruction.

seg
    specifies the segment of the symbol id.

offset
    specifies the offset of the symbol id.

reloff
    specifies the relative offset of the symbol id for near control
    transfers.

asm
    is an assembly language instruction or directive.

In the following example, Watcom C/C++ will generate a far call to the
function myrtn.


     #pragma aux myrtn far;

Note that this overrides the calling sequence that would normally be
generated for a particular memory model.  In other words, a far call will be
generated even if you are compiling for a memory model with a small code
model.

In the following example, Watcom C/C++ will generate a near call to the
function myrtn.


     #pragma aux myrtn near;

Note that this overrides the calling sequence that would normally be
generated for a particular memory model.  In other words, a near call will
be generated even if you are compiling for a memory model with a big code
model.

In the following DOS example, Watcom C/C++ will generate the sequence of
bytes following the "=" character in the auxiliary pragma whenever a call to
mode4 is encountered.  mode4 is called an in-line function.


     void mode4(void);
     #pragma aux mode4 =                \
         0xb4 0x00       /* mov AH,0 */ \
         0xb0 0x04       /* mov AL,4 */ \
         0xcd 0x10       /* int 10H  */ \
         modify [ AH AL ];

The sequence in the above DOS example represents the following lines of
assembly language instructions.


     mov   AH,0       ; select function "set mode"
     mov   AL,4       ; specify mode (mode 4)
     int   10H        ; BIOS video call

The above example demonstrates how to generate BIOS function calls in-line
without writing an assembly language function and calling it from your C/C++
program.  The C prototype for the function mode4 is not necessary but is
included so that we can take advantage of the argument type checking
provided by Watcom C/C++.

The following DOS example is equivalent to the above example but mnemonics
for the assembly language instructions are used instead of the binary
encoding of the assembly language instructions.


     void mode4(void);
     #pragma aux mode4 =     \
         "mov AH,0",         \
         "mov AL,4",         \
         "int 10H"           \
         modify [ AH AL ];

If a sequence of in-line assembly language instructions contains 80x87
floating-point instructions, each floating-point instruction must be
preceded by "float".  Note that this is only required if you have specified
the "fpi" compiler option; otherwise it will be ignored.

The following example generates the 80x87 "square root" instruction.


     double mysqrt(double);
     #pragma aux mysqrt parm [8087] = \
         float 0xd9 0xfa /* fsqrt */;

A sequence of in-line assembly language instructions may contain symbolic
references.  In the following example, a near call to the function myalias
is made whenever myrtn is called.


     extern void myalias(void);
     void myrtn(void);
     #pragma aux myrtn =                     \
         0xe8 offset myalias /* near call */;

In the following example, a far call to the function myalias is made
whenever myrtn is called.


     extern void myalias(void);
     void myrtn(void);
     #pragma aux myrtn =                                \
         0x9a offset myalias seg myalias /* far call */;