The structure of a macro definition consists of a name, some optional arguments, the body of the macro, and a termination keyword. The syntax to define a macro is:


{name} MACRO arg 1 , arg 2 ,, arg n

The name of the macro has the same requirements as a label name (in particular, it must start in the first column). The arguments are a comma-separated list of identifiers. The body of the macro can have arbitrary assembly-language text, including other macro definitions and invocations, and conditional and file-inclusion directives. A macro is instantiated by using its name together with optional, actual argument values. A macro instantiation has to occur on its own line—it cannot be used within an expression or as an argument to an assembly-code mnemonic or directive. The syntax to invoke a macro is:


name actual 1, actual 2, …, actual n // comment

When a macro is instantiated, the macro body is inserted into the assembly text with actual values replacing the arguments that were in the body of the macro definition.

Labels in macros

When labels are used in macros, they must be unique for each instantiation to avoid duplicate-label-definition errors. The assembler provides a label-generation mechanism, for situations where the label name isn't significant, and a mechanism for constructing specific label names.

If a macro definition contains a jump to other instructions in the macro definition, it is likely that the actual name of the label isn't important. To facilitate this, a label of the form name? can be used.

In some instances, invoking a macro should result in the definition of a label. In the simplest case, the label can be passed as an argument to the macro; however, there are cases when the label name should be constructed from other tokens. The macro definition facility provides two constructs to enable this:


If multiple definitions are required, a loop structure can be used. This can be achieved either by recursive macro definitions or by the use of the LOOP directive.


        IF      N
        P2TAB   N-1
        DW      1<<N


This creates a table of ten powers of 2—that is: 1, 2, 4, 8, and so on, up to 1024.

If the loop counter is a large number, a recursive macro may consume considerable machine resources. Use the LOOP directive to avoid this, because it is an iterative rather than recursive solution.


LOOP expression

The loop-control expression must be a compile-time constant. The loop body can contain any assembly text (including further loop constructs) except macro definitions (because that would result in multiple definitions of the same macro). The above recursive definition can be recast in an iterative style:


x       SET     0
        LOOP    x <= 10
            DC.W    1<<x
x       SET     x+1

Note that the label-naming capabilities using ?, $$, and ## are not available within the body of a loop. If the loop body is to declare labels, a recursive macro definition should be used; or use a combination of macro invocation to define the labels and use the loops to define the text of the label.