MACRO CALLS

Once a macro has been defined, it can be called any number of times in the program. The call consists of the macro name and any actual parameters that are to replace dummy parameters during macro expansion. During assembly, each macro call is replaced by the macro definition code; dummy parameters are replaced by actual parameters.

Macro Call Format

Label optional:

Opcode macro name

Operand optional actual parameter(s)

Chapter 5. Macros

The assembler must encounter the macro definition before the first call for that macro. Otherwise, the macro call is assumed to be an illegal opcode. The assembler inserts the macro body identified by the macro name each time it encounters a call to a previously defined macro in your program.

The positioning of actual parameters in a macro call is critical since the substitution of parameters is based solely on position. The first-listed actual parameter replaces each occurrence of the first-listed dummy param-eter; the second actual parameter replaces the second dummy parameter, and so on. When coding a macro call, you must be certain to list actual parameters in the appropriate sequence for the macro.

Notice that blanks are usually treated as delimiters. Therefore, when an actual parameter contains blanks (passing the instruction MOV A,M, for example) the parameter must be enclosed in angle brackets. This is also true for any other delimiter that is to be passed as part of an actual parameter. Carriage returns cannot be passed as actual parameters.

If a macro call specifies more actual parameters than are listed in the macro definition, the extra parameters are ignored. If fewer parameters appear in the call than in the definition, a null replaces each missing parameter.

Example:

The following example shows two calls for the macro LOAD. LOAD is defined as follows:

LOAD MACRO Gl,G2,G3

LOCAL MOVES

MOVES: LHLD Gl

MOV A,M

LHLD G2

MOV B,M

LHLD G3

MOV C,M

ENDM

LOAD simply loads the accumulator with a byte of data from the location specified by the first actual parameter, the B register with a byte from the second parameter, and the C register with a byte from the third parameter.

The first time LOAD is called, it is used as part of a routine that inverts the order of three bytes in memory.

The second time LOAD is called, it is part of a routine that adds the contents of the B register to the accumu-lator and then compares the result with the contents of the C register.

MAIN PROGRAM SUBSTITUTION recursive macro exp~nsions can be terminated eventually. This operation can be controlled using the conditional assembly directives described in Chapter 4 (I F, ELSE, ENOl F).

Chapter 5. Macros

Macro Expansion

When a macro is called, the actual parameters to be substituted into the prototype code can be passed in one of two modes. Normally, the substitution of actual parameters for dummy parameters is simply a text substitution.

The parameters are not evaluated until the macro is expanded.

If a percent sign (%) precedes the actual parameter in the macro call, however, the parameter is evaluated immediately, before expansion occurs, and is passed as a decimal number representing the value of the param-eter. In the case of I RPC, a '%' preceding the actual parameter causes the entire text string to be treated as a single parameter. One I RPC iteration occurs for each digit in the decimal string passed as the result of immediate evaluation of the text string.

The normal mechanism for passing actual parameters is adequate for most applications. Using the percent sign to pre-evaluate parameters is necessary only when the value of the parameter is different within the local con-text of the macro definition as compared to its global value outside the macro definition.

Example:

The macro shown in this example generates a number of rotate instructions. The parameters passed in the macro call determine the number of positions the accumulator is to be rotated and whether rotate right or rotate left instructions are to be generated. Some typical calls for "this macro are as follows:

SHIFTR SHIFTR

'R',3

L,%COUNT -1

The second call shows an expression used as a parameter. This expression is to be evaluated immediately rather than passed simply as text.

The definition of the SHIFTR macro is shown below. This macro uses the conditional IF directive to test the validity of the first parameter. Also, the REPT macro directive is nested within the SHIFTR macro.

SHIFTR MACRO X,Y

IF X EO 'R' REPT Y

RAR ENDM ENDIF IF X NE 'L'

EXITM ELSE

REPT Y RAL ENDM ENDIF ENDM

The indentation shown in the definition of the SHIFTR macro graphically illustrates the relationships of the IF, ELSE, END I F directives and the REPT, ENDM directives. Such indentation is not required in your program, but

The SHI FTR macro generates nothing if the first parameter is neither R nor L. Therefore, the following calls produce'no code. The result in the object program is as though the SHIFTR macro does not appear in the source program.

SHIFTR 5

SHIFTR '6',2

The following call to the SHIFTR macro generates three RAR instructions:

SHIFTR 'R',3

Assume that a SET directive elsewhere in the source program has given COUNT the value 6. The following call generates five RAL instructions:

SHIFTR 'L',%COUNT -1

The following is a redefinition of the SHIFTR macro. In this definition, notice that concatenation is used to form the RAR or RAL operation code. If a call to the SHIFTR macro specifies a character other than R or L, illegal operation codes are generated. The assembler flags all illegal operation codes as errors.

SHIFTR MACRO

REPT RA&X ENDM ENDM

X,Y Y