III.11.4 Local Symbols

Local symbols are symbols, which are only known within a macro body, but not outside the macro. Symbols that are defined for the whole program, will subsequently be called "global symbols" for better understanding. We are already familiar with a special case of local symbols: formal macro parameters. They appear in the macro definition only. Since they are substituted during macro expansion, we don't have further problems with them. But what happens with symbols that are defined in a macro body?

Example 1:

The following simple macro is intended to read a character from the 8051 UART, and to return it in A:

        RECEIVE MACRO
UARTIN: JNB RI,UARTIN
        MOV A,SBUF
        CLR RI
        ENDM

This will work only once! If the macro RECEIVE is called multiple times, the label UARTIN will be multiply defined.

This can be solved by simply declaring the symbol UARTIN local. For this, the LOCAL statement has been introduced. After the keyword LOCAL, a list of local symbols can be specified, separated by commas. These symbols will only be valid inside the macro that contains the LOCAL statement. LOCAL statements may only be placed directly after the MACRO or REPT statement, preceding the first body line. They may contain any number of local symbols. The macro body may be preceded by an arbitrary number of LOCAL statements.
Local symbols must be valid symbols, unique within the macro, and different from the formal parameters (if any). Keywords cannot be used as local symbol names. If a local symbol has the same name as a global symbol, the local scope takes precedance during substitution.
When a macro is expanded, its local symbols are always substituted: the formal parameters are replaced by the macro arguments, and the local symbols that have been declared in a LOCAL statement are replaced by unique, global symbol names, which the assembler generates during every expansion. These have always the format ??xxxx, where xxxx is a unique symbol number.

Example 2:

After a redesign of our previous macro RECEIVE using local symbols, it is looking as follows:

        RECEIVE MACRO
        LOCAL UARTIN
UARTIN: JNB RI,UARTIN
        MOV A,SBUF
        CLR RI
        ENDM

Enhanced as shown above, the macro will work correctly, as often as desired. When RECEIVE is called for the first time, the local symbol UARTIN will be replaced by ??0000,

??0000: JNB RI,??0000
        MOV A,SBUF
        CLR RI

when it is called for the second time, UARTIN will be replaced by ??0001, and so on:

??0001: JNB RI,??0001
        MOV A,SBUF
        CLR RI

However, it is recommended not to define global symbols in the format ??xxxx, to avoid name conflicts with substituted local symbols from expanded macros.