9.2.4 Defining Local Symbols in Macros

You can make a symbol local to a macro by declaring it at the start of the macro with the LOCAL directive. Any identifier may be declared local.

You can choose whether you want numeric equates and text macros to be local or global. If a symbol will be used only inside a particular macro, you can declare it local so that the name will be available for other declarations inside other macros or at the global level. On the other hand, it is sometimes convenient to define text macros and equates that are not local, so that their values can be shared between macros.

If you need to use a label inside a macro, you must declare it local, since a label can occur only once in the source. The LOCAL directive makes a special instance of the label each time the macro is called. This prevents redefinition of the label.

All local symbols must be declared immediately following the MACRO statement (although blank lines and comments may precede the local symbol). Separate each symbol with a comma. Comments are allowed on the LOCAL statement. Multiple LOCAL statements are also permitted. Here is an example macro that declares local labels:

power MACRO factor:REQ, exponent:REQ

LOCAL again, gotzero ;; Local symbols

sub dx, dx ;; Clear top

mov ax, 1 ;; Multiply by one on first loop

mov cx, exponent ;; Load count

jcxz gotzero ;; Done if zero exponent

mov bx, factor ;; Load factor

again:

mul bx ;; Multiply factor times exponent

loop again ;; Result in AX

gotzero:

ENDM

If the labels again and gotzero were not declared local, the macro would work the first time it is called, but it would generate redefinition errors on subsequent calls. MASM implements local labels by generating different names for them each time the macro is called. You can see this in listing files. The labels in the power macro might be expanded to ??0000 and ??0001 on the first call and to ??0002 and ??0003 on the second.