Chapter 6. Macro Processing Language

The Macro Processing Language (MPL) is a string replacement facility. The macro processing language is enabled with the assembler control MPL and fully compatible to the Intel ASM-51 macro processing language. It permits you to write repeatedly used sections of code once and then insert that code at several places in your program. Perhaps MPL’s most valuable capability is conditional assembly-with all microprocessors, compact configuration dependent code is very important to good program design. Conditional assembly of sections of code can help to achieve the most compact code possible.

Overview

The MPL processor views the source file in different terms than the assembler: to the assembler, the source file is a series of lines – control lines, and directive lines. To the MPL processor, the source file is a long string of characters.

All MPL processing of the source file is performed before your code is assembled. Because of this independent processing of the MPL macros and assembly of code, we must differentiate between macro-time and assembly-time. At macro-time, assembly language symbols and labels are unknown. SET and EQU symbols, and the location counter are also not known. Similarly, at assembly-time, no information about the MPL is known.

user-defined macro by some replacement text.

Creating and Calling MPL Macros

The MPL processor is a character string replacement facility. It searches the source file for a macro call, and then replaces the call with the macro's return value. A % character signals a macro call.

The MPL processor function DEFINE creates macros. MPL processor functions are a predefined part of the macro language, and can be called without definition. The syntax for DEFINE is:

%[*]DEFINE (macro name) [parameter-list] (macro-body)

DEFINE is the most important macro processor function. Each of the symbols in the syntax above (macro name, parameter-list, and macro-body) are described in the following.

Creating Parameterless Macros

When you create a parameterless macro, there are two parts to a DEFINE call:

macro name

The macro name defines the name used when the macro is called.

macro body

The macro-body defines the return value of the call.

6

The syntax of a parameterless macro definition is shown below:

%*DEFINE (macro name) (macro-body)

The ‘ %’ is the metacharacter that signals a macro call. The ‘*’ is the literal character. The use of the literal character is described later in this part.

Macro names have the following conventions:

Maximum of 31 characters long

First character: ‘A’ - ‘Z’, ‘a’ - ‘z’, ‘_’, or ‘?’

Other characters: ‘A’ - ‘Z’, ‘a’ - ‘z’, ‘_’, ‘?’, ‘0’ - ‘9’

The macro-body is usually the replacement text of the macro call. However, the macro-body may contain calls to other macros. If so, the replacement text is actually the fully expanded macro-body, including the calls to other macros. When you define a macro using the syntax shown above, macro calls contained in the body of the macro are not expanded, until you call the macro.

The syntax of DEFINE requires that left and right parentheses surround the macro-body. For this reason, you must have balanced parentheses within the macro-body (each left parenthesis must have a succeeding right parenthesis, and each right parenthesis must have a preceding left parenthesis). We call character strings that meet these requirements balanced-text.

To call a macro, use the metacharacter followed by the macro name for the MPL

macro. (The literal character is not needed when you call a user-defined macro.) 6 The MPL processor will remove the call and insert the replacement text of the

call. If the macrobody contains any call to other macros, they will be replaced with their replacement text.

Once a macro has been created, it may be redefined by a second DEFINE.

MPL Macros with Parameters

Parameters in a macro body allow you to fill in values when you call the MPL macro. This permits you to design a generic macro that produces code for many operations.

The term parameter refers to both the formal parameters that are specified when the macro is defined, and the actual parameters or arguments that are replaced when the macro is called.

The syntax for defining MPL macros with parameters is:

%*DEFINE (macro-name(parameter-list)) (macro-body)

The parameter-list is a list of identifiers separated by macro delimiters. The identifier for each parameter must be unique.

Typically, the macro delimiters are parentheses and commas. When using these delimiters, you would enclose the parameter-list in parentheses and separate each formal parameter with a comma. When you define a macro using parentheses and commas as delimiters, you must use those same delimiters, when you call that macro.

The macro-body must be a balanced-text string. To indicate the locations of parameter replacement, place the parameter's name preceded by the metacharacter in the macro-body. The parameters may be used any number of times and in any order within the macro-body. If a macro has the same name as

6 one of the parameters, the macro cannot be called within the macro-body since this would lead to infinite recursion.

The example below shows the definition of a macro with three dummy parameters - SOURCE, DESTINATION, and COUNT. The macro will produce code to copy any number of bytes from one part of memory to another.

%*DEFINE (BMOVE (src, dst, cnt)) LOCAL lab (

DJNZ R2, %lab

)

To call the above macro, you must use the metacharacter followed by the macro's name similar to simple macros without parameters. However, a list of the actual parameters must follow. The actual parameters must be surrounded in the macro definition. The actual parameters must be balanced-text and may optionally contain calls to other macros. A simple program example with the macro defined above might be:

Assembler source text

%*DEFINE (BMOVE (src, dst, cnt)) LOCAL lab (

; move memory block %BMOVE (arr1,arr2,ALEN)

END

6

The following listing shows the assembler listing of the above source code.

The example lists an assembled file that contains a macro definition in lines

1 to 9. The macro definition is listed with semicolons at start of each line. These semicolons are added by the assembler to prevent assembly of the definition text which is meaningful to the MPL preprocessor, but not to the remaining assembler phases. The listing only includes macro definitions or macro calls, if the control GEN is given.