The definition of a macro consists of three parts: the header, which assigns a name to the macro and defines the dummy arguments; the body, which consists of prototype or skeleton source statements; and the terminator. The header is the MACRO directive, its label, and the dummy argument list. The body contains the pattern of standard source statements. The terminator is the ENDM directive.
The header of a macro definition has the form:
label MACRO [ dummy argument list][ comment]
The required label is the symbol by which the macro is called. The dummy argument list has the form:
[ dumarg[ ,dumarg,...,dumarg]]
The dummy arguments are symbolic names that the macro processor replaces with arguments when the macro is expanded (called). Each dummy argument must obey the same rules as global symbol names. Dummy argument names that are preceded by an underscore are not allowed. Dummy arguments are separated by commas. For example, consider the macro definition in the following listing.
N_R_MUL MACRO NMUL,AVEC,BVEC,RESULT header ;RESULT(I) = AVEC(I) * BVEC(I) I=1..NMUL ;where ; NMUL = number of multiplications ; AVEC = base address of array AVEC(I) ; BVEC = base address of array BVEC(I) ; RESULT = base address of array RESULT(I) ; MOVE #AVEC,R0 body MOVE #BVEC,R4 MOVE #RESULT,R1 MOVE X:(R0)+,D4.S Y:(R4)+,D7.S DO #NMUL,_ENDLOOP FMPY.S D4,D7,D0 X:(R0)+,D4.SY:(R4)+,D7.S MOVE D0.S,X:(R1)+ _ENDLOOP ENDM ;terminator
When a macro call is executed, the dummy arguments within the macro definition ( NMUL, AVEC, BVEC, RESULT in the above listing) are replaced with the corresponding argument as defined by the macro call.
All local labels within a macro are considered distinct for the currently active level of macro expansion (unless the macro local label override is used, see below). These local labels are valid for the entire macro expansion and are not considered bounded by non-local labels. Therefore, all local labels within a macro must be unique. This mechanism allows the programmer to freely use local labels within a macro definition without regard to the number of times that the macro is expanded. Non-local labels within a macro expansion are considered to be normal labels and thus cannot occur more than once unless used with the SET directive.
When specifying a local label within the body of a macro, the programmer must be aware that the label symbol is valid for the entire body of the current level of macro expansion. It is not valid for any nested macros within the current level of expansion. The example above shows why the local label feature is useful. If the macro N_R_MUL were called several times, there would be several _ENDLOOP labels resulting from the macro expansions. This is acceptable because each _ENDLOOP label is considered private to a particular instance of macro expansion.
It is sometimes desirable to pass local labels as macro arguments to be used within the macro as address references (e.g. MOVE #_LABEL,R0). The Assembler effectively disallows this, however, since underscore label references within a macro invocation are regarded as labels local to that expansion of the macro. A macro local label override is provided which causes local symbol lookup to have normal scope rather than macro call scope. If a circumflex (^) precedes an expression containing an underscore label, then at expansion the associated term is evaluated using the normal local label list rather than the macro local label list. The operator has no effect on normal labels or outside a macro expansion.