Macro Operators

III.11.5 Macro Operators

There are some special control characters, which are very useful for macro definition, call and expansion:

;; Macro commentary Normally, comments in body lines are also contained in the expanded lines. If a commentary begins with ';;' however, it is not stored during macro definition. Therefore, it doesn't consume memory space, and appears in the list file in the macro definition only, but not in the expanded lines.
! Literal operator If the escape character '!' precedes another printable character in a macro argument, the assembler is forced to treat that character literally. This means it will be passed to the macro, even if it is a control character, while the literal operator itself is removed.
< > Literal brackets If a macro argument is intended to contain separation or control characters, it must be enclosed in literal brackets < ... > to pass it to the macro as one argument string, while the outermost pair of brackets is removed. Literal brackets can be nested to any depth.
% Evaluation If a macro argument is preceded by the evaluation operator '%', it is interpreted as an expression, which will be evaluated before it is passed to the macro. The actual argument string will not be the expression itself, but a decimal ASCII representation of its value. The expression must be known on pass 1.
& Substitution The '&' character separates parameter names (local symbols) from surrounding text. Outside quoted strings and commentary it serves only as a general separation character. This applies always when a local symbol directly precedes or follows another alphanumeric string. Inside quoted strings and commentary, a local symbol must be preceded by '&' if it is to be substituted there.
During every macro expansion, the assembler removes exactly one '&' from every sequence of '&' characters. This allows for example, to define a nested macro inside a macro body, which also uses the substitution operator '&': one writes simply '&&'!

Example 1:

The commentary should only be visible in the definition of the macro LICENSE:
 LICENSE MACRO
	DB	'Copyright'  ;;legal stuff
 ENDM
When called, the expanded macro body is looking like this in the list file:
        DB	'Copyright'

Example 2:

	SPECIAL !;
passes a semicolon to the macro SPECIAL as a literal argument. This could also be done with
	SPECIAL <;>

Example 3:

The macro CONST defines a 16-bit constant in ROM:
 CONST MACRO NUMB
	DW	NUMB
 ENDM
If it is called as shown below,
	CONST	0815H+4711-42
the parameter NUMB would be substituted as follows:
	DW	0815H+4711-42
If the same macro argument is preceded by a '%' however,
	CONST	%0815H+4711-42
the substitution will result in:
	DW	6738

Example 4:

During substitution, both arguments of the macro CONCAT should form a seamless symbol name:
 CONCAT MACRO NAM, NUM
	MOV R3,#0
NAM&NUM:DJNZ R3,NAM&NUM
 ENDM
When CONCAT is called as follows,
	CONCAT LABEL, 08
the parameters NAM and NUM are substituted during macro expansion as shown below:
	MOV R3,#0
LABEL08:DJNZ R3,LABEL08

;;	Macro commentary	Normally, comments in body lines are also contained in the expanded lines. If a commentary begins with ';;' however, it is not stored during macro definition. Therefore, it doesn't consume memory space, and appears in the list file in the macro definition only, but not in the expanded lines.
!	Literal operator	If the escape character '!' precedes another printable character in a macro argument, the assembler is forced to treat that character literally. This means it will be passed to the macro, even if it is a control character, while the literal operator itself is removed.
< >	Literal brackets	If a macro argument is intended to contain separation or control characters, it must be enclosed in literal brackets < ... > to pass it to the macro as one argument string, while the outermost pair of brackets is removed. Literal brackets can be nested to any depth.
%	Evaluation	If a macro argument is preceded by the evaluation operator '%', it is interpreted as an expression, which will be evaluated before it is passed to the macro. The actual argument string will not be the expression itself, but a decimal ASCII representation of its value. The expression must be known on pass 1.
&	Substitution	The '&' character separates parameter names (local symbols) from surrounding text. Outside quoted strings and commentary it serves only as a general separation character. This applies always when a local symbol directly precedes or follows another alphanumeric string. Inside quoted strings and commentary, a local symbol must be preceded by '&' if it is to be substituted there. During every macro expansion, the assembler removes exactly one '&' from every sequence of '&' characters. This allows for example, to define a nested macro inside a macro body, which also uses the substitution operator '&': one writes simply '&&'!