.MACRO Directive

Discussion

Normal Assembler syntax is observed within macro definitions, except that text substitution is assumed for formal parameters. The following line is an example of a macro declaration:

        DECR    .MACRO LAB,VAL

LAB and VAL are formal parameters. Their actual values are determined by the first and second parameters on any invocation of the macro DECR. On the macro invocation, the parameters are delimited by commas. Successive commas indicate a null parameter, causing the expanded macro to substitute null for one of its formal parameters. When the number of formal parameters exceeds the number of actual parameters, null parameters are inserted for the excess parameter positions. When the number of actual parameters exceeds the number of formal parameters, a warning is issued and the excess parameters are ignored.

	NOTE: Although there is no upper limit on the number of parameters or arguments in a macro definition, no single macro parameter may exceed 200 characters.

Macro definitions may appear wherever and as often as necessary within source code. Macro definitions may occur inside or outside of spaces, subspaces, and procedures.

Because the Assembler always uses the most recently encountered definition, macros may be redefined as often as desired.

	NOTE: A macro cannot be defined within the body of another macro definition.

Although nested macro definitions are not allowed, nested macro calls are. A nested macro call occurs when one macro is invoked within the definition of another macro. A macro may not be invoked within its own definition. Macros can only be invoked after being defined.

Examples

The macro definition defines a simple counter or timer called DECR.

DECR    .MACRO    LAB,VAL
SETP    ADDIL     L'VAL-$global$,%dp
        LDW       R'VAL-$global$(%r1),%r20
LAB
        ADDIBF,=  -1,%r20,LAB
        NOP
        .ENDM

The following is an invocation of DECR:

        DECR LOOP,COUNT

LOOP and COUNT are the actual parameters that are specific to this particular invocation of the macro DECR.

During macro expansion, textual substitution for positional parameters is performed in the body of the macro definition. Substitution is performed on strings of characters that are delimited by blanks, tabs, commas, or semicolons. If the string matches one of the formal parameters, it is replaced with the corresponding actual parameter.

When a macro definition contains a label, the expanded form of the macro adds a unique suffix to the label for each instance the macro is invoked. This unique suffix prevents duplicate symbols from occurring and prevents the label from being referenced from outside the body of the macro definition. This suffix also contains a number that is used as a counter by the Assembler.

The following example defines the macro PRINT, which calls the printf() function (see printf(3S) in HP-UX Reference). The macro parameter DATA_ADDR is used to set up the argument to be passed to printf().

PRINT   .MACRO   DATA_ADDR
        ADDIL    L'DATA_ADDR,%dp
        .CALL
        BL       printf,%rp
        LDO      R'DATA_ADDR(%r1),%arg0
        .ENDM

The next example defines the macro STORE. STORE places the contents of the register REG, the first macro parameter, into the memory address LOC, the second parameter.

STORE   .MACRO   REG,LOC
        LDIL     L'LOC-$global$,%r1
        STW      REG,R'LOC-$global$(%r1)
        .ENDM