MACRO, ENDM

One of the best features of an assembler is the ability to write macros for it. Macros also provide a method of passing arguments to them and they can then react to the input using IF-constructs.

MyMacro:  MACRO
          ld   a,80
          call MyFunc
          ENDM

The above example is a very simple macro. You execute the macro by typing its name.

          add  a,b
          ld   sp,hl
          MyMacro        ;This will be expanded
          sub  a,87

When the assembler meets MyMacro it will insert the macrodefinition (the text enclosed in MACRO/ENDM).

Suppose your macro contains a loop.

LoopyMacro:    MACRO
               xor  a,a
.loop          ld   [hl+],a
               dec  c
               jr   nz,.loop
               ENDM

This is fine. That is, if you only use the macro once per scope. To get around this problem there is a special label string equate called \@ that you can append to your labels and it will then expand to a unique string.

\@ also works in REPT-blocks should you have any loops there.

LoopyMacro:    MACRO
               xor  a,a
.loop\@        ld   [hl+],a
               dec  c
               jr   nz,.loop\@
               ENDM

Arguments

I’d like LoopyMacro a lot better if I didn’t have to pre-load the registers with values and then call it. What I’d like is the ability to pass it arguments and it then loaded the registers itself.

And I can do that. In macros you can get the arguments by using the special macro string equates \1 through \9, \1 being the first argument specified on the calling of the macro.

LoopyMacro:    MACRO
               ld   hl,\1
               ld   c,\2
               xor  a,a
.loop\@        ld   [hl+],a
               dec  c
               jr   nz,.loop\@
               ENDM

Now I can call the macro specifying two arguments. The first being the address and the second being a bytecount. The macro will then reset all bytes in this range.

               LoopyMacro     MyVars,54

You can specify up to nine arguments when calling a macro. Arguments are passed as string equates. There’s no need to enclose them in quotes. Parameter passing has changed a bit since v1.03 in that an expression will not be evaluated first but passed directly. This means that it’s probably a very good idea to use brackets around \1–\9 if you perform further calculations on them. For instance if you pass 1+2 as the first argument and then do PRINTV \1*2 you will get the value 5 on screen and not 6 as you might have expected.

Note that a colon (:) following the macro-name is required. Macros can't be exported or imported. It's valid to call a macro from a macro (yes, even the same one).

MACRO, ENDM

Arguments

See also: