Macros

Usage

Macros are useful when a group of instructions and/or directives is frequently needed. armasm will replace the macro name with its definition. Macros may contain calls to other macros, nested up to 255 levels.

Defining a macro

Two directives are used to define a macro. The syntax is:

MACRO
{$label} macroname {$parameter1}{,$parameter2}{,$parameter3}..
    ...code...
    MEND
The directive MACRO must be followed by a macro prototype statement on the next line. This tells the assembler the name of the macro and its parameters. A label is optional, but useful if calls of the macro may be labelled. Any number of parameters can be used; each must begin with `$' to distinguish them from ordinary program symbols.

Within the macro body, $label, $parameter, etc., can be used in the same way as any other variables (seeLocal and global variables - GBL, LCL and SET, and section Variable substitution - $). They will be given new values each time the macro is called.

Sometimes a macro parameter or label needs to be appended by a value. The appended value should be separated by a dot, which the assembler will ignore once it has used it to recognise the end of the parameter and label. For example:

$label.$count
The end of the macro definition is signified by the MEND directive.There must be no un-closed WHILE/WEND loops or conditional assembly when the MEND directive is reached. Macro expansion terminates at MEND. However it can also be terminated with the MEXIT directive, which can be used in conjunction with WHILE/WEND or conditional assembly.

Setting default parameter values

Default values can be set for parameters by following them with an equals sign and the default value. If the default has a leading or trailing space, the whole value should appear in quotes, as shown below:

...{$parameter="default value"}

Macro invocation

A macro defined with a pattern such as:

$lab    xxxx $arg1,$arg2=5,$arg3
can be invoked as:

Label    xxxx val1,val2,val3
An omitted actual argument is given a null (empty string) value. To force use of the default value, use `|' as the actual argument.