III.11.2 Macro Parameters

Callable macros may have parameters, to allow more flexible use. The names of the formal parameters are specified in the macro definition behind the keyword MACRO, separated by commas. All parameter names of a macro must be different, valid symbols. Keywords cannot be used as parameter names. Macros may have any number of parameters, as long as they fit on one line. Parameter names are local symbols, which are known within the macro only. Outside the macro they have no meaning! 

  <macro name> MACRO <parameter 1>, <parameter 2>, ... ,<parameter n>
  <body line 1>
  <body line 2>
      .
      .
  <body line m>
  ENDM

When called, actual arguments can be passed to the macro. The arguments must be separated by commas. Valid macro arguments are

  1. arbitrary sequences of printable characters, not containing blanks, tabs, commas, or semicolons

  2. quoted strings (in single or double quotes)

  3. single printable characters, preceded by '!' as an escape character

  4. character sequences, enclosed in literal brackets < ... >, which may be arbitrary sequences of valid macro arguments (types 1. - 4.), blanks, commas and semicolons

  5. arbitrary sequences of valid macro arguments (types 1. - 4.)

  6. expressions preceded by a '%' character

Note: The keywords MACRO, EQU, SET, CODE, DATA, IDATA, XDATA, BIT, and the ':' character cannot be passed as the first macro argument, because they always start a symbol definition!
Therefore they must be enclosed in literal brackets < ... >.

During macro expansion, these actual arguments replace the symbols of the corresponding formal parameters, wherever they are recognized in the macro body. The first argument replaces the symbol of the first parameter, the second argument replaces the symbol of the second parameter, and so forth. This is called substitution.
Without special assistance, the assembler will not recognize a parameter symbol if it

  • is part of another symbol
  • is contained in a quoted string
  • appears in commentary


Example 1: 

        MY_SECOND MACRO CONSTANT, REGISTER
        MOV A,#CONSTANT
        ADD A,REGISTER
        ENDM

        MY_SECOND 42, R5
After calling the macro MY_SECOND, the body lines 
        MOV A,#42
        ADD A,R5
are inserted into the program, and assembled. The parameter names CONSTANT and REGISTER have been replaced by the macro arguments "42" and "R5".

The number of arguments, passed to a macro, can be less (but not greater) than the number of its formal parameters. If an argument is omitted, the corresponding formal parameter is replaced by an empty string.
If other arguments than the last ones are to be omitted, they can be represented by commas.


Example 2:

The macro OPTIONAL has eight formal parameters: 
        OPTIONAL MACRO P1,P2,P3,P4,P5,P6,P7,P8
          .
          .
        <macro body>
          .
          .
        ENDM
If it is called as follows, 
        OPTIONAL 1,2,,,5,6
the formal parameters P1, P2, P5 and P6 are replaced by the arguments 1, 2, 5 and 6 during substitution. The parameters P3, P4, P7 and P8 are replaced by a zero length string.

For more flexible macro design, there must be a possibility to recognize empty macro arguments, and to branch the macro expansion accordingly. This can be performed with conditional assembly, using the IFB and IFNB meta instructions.
(See chapter "III.10.2 IFxx and ELSEIFxx Instructions".)



[contents] [up] [back] [next]