Macro definition directive

    Format

      .MACRO  macro-name [formal-argument-list]
         .

         .

         .

      range
         .

         .

         .

      .ENDM  [macro-name]

1  –  Parameters

 macro-name

    The name of the macro to be defined; this name can be any legal
    symbol up to 31 characters long.

 formal-argument-list

    The symbols, separated by commas, to be replaced by the actual
    arguments in the macro call.

 range

    The source text to be included in the macro expansion.

2  –  Description

    .MACRO begins the definition of a macro. It gives the macro name
    and a list of formal arguments. The .MACRO directive is followed
    by the source text to be included in the macro expansion. The
    .ENDM directive specifies the end of the range.

    Macro names do not conflict with user-defined symbols. Both a
    macro and a user-defined symbol can have the same name.

    When the assembler encounters a .MACRO directive, it adds the
    macro name to its macro name table and stores the source text
    of the macro (up to the matching .ENDM directive). No other
    processing occurs until the macro is expanded.

    The symbols in the formal argument list are associated with the
    macro name and are limited to the scope of the definition of that
    macro. For this reason, the symbols that appear in the formal
    argument list can also appear elsewhere in the program.

3  –  Notes

    o  If a macro has the same name as an Alpha opcode, the macro
       is used instead of the instruction. This feature allows you to
       temporarily redefine an opcode.

    o  You can redefine a macro by using a .MACRO directive with the
       same name as in a previous macro definition. Therefore, the
       previous macro definition is implicitly deleted and the new
       macro definition supersedes the previous definition. See the
       .MDELETE directive for more information on macro deletion.

    o  You can nest a macro definition within another macro
       definition. The inner macro is not defined until the outer
       macro is invoked.

    o  You can nest a macro invocation so that one macro can invoke
       another. The assembler supports nested macro invocations to a
       depth of 1000. If a macro invokes itself, either directly or
       indirectly, it is recursive. Recursive macros must specify a
       basis-step in order to avoid infinite recursion. A basis-step
       is a macro exit condition that will eventually cause the macro
       to exit, which ends the recursion (see Example 3).

4  –  Examples

      Example 1
      This example shows how macro definitions and invocations may
      be nested. It also shows examples of the various forms of
      parameter passing.

        .MACRO OP1 A,B=R4,?C
        C:      ADDL R2, B, R3
        .MACRO OP'B
                TRAPB
        .ENDM OP'B
                ADDL A, R2, R3
                OP'B
                .MDELETE OP'B
        .ENDM OP1

      When OP1 is invoked "OP1 R0", the text expands to:

        33000$: ADDL R2, R4, R3
        .MACRO OPR4
                TRAPB
        .ENDM
                ADDL R0, R2, R3
                OPR4
                .MDELETE OPR4

      Processing this text will cause OPR4 to be expanded to TRAPB;
      the final text will be:

        33000$: ADDL R2, R4 R3
                ADDL R0, R2, R3
                TRAPB

      Example 2
      The following example shows macro redefinition:

        .MACRO INITIALIZE
           .MACRO INITIALIZE   ;Redefine to nothing
           .ENDM INITIALIZE
           X=0
           Y=1
           Z=-1
        .ENDM INITIALIZE

      Note that while the redefined version of the macro immediately
      supersedes the previous definition in any subsequent
      invocation, the invocation of the original definition expands
      to completion.
      Example 3
      This example shows a recursive macro:

        .MACRO FACTORIAL N
           .IF EQUAL <N>,0      ;Basis step; stop at zero
              F=1
           .ELSE
              FACTORIAL <N-1>
              F = F * <N>
           .ENDC
        .ENDM FACTORIAL