Defining a macro

You define a macro with the statement:

name MACRO [argument] [,argument] …

Here name is the name you are going to use for the macro, and argument is an argument for values that you want to pass to the macro when it is expanded.

For example, you could define a macro errMacro as follows:

            name    errMacro
errMac      macro   text
            extern  abort
            call    abort
            dc8     text,0
            endm

This macro uses a parameter text to set up an error message for a routine abort. You would call the macro with a statement such as:

            errMac  'Disk not ready'

The assembler expands this to:

            call   abort
            dc8    'Disk not ready', 0

If you omit a list of one or more arguments, the arguments you supply when calling the macro are called \1 to \9 and \A to \Z.

The previous example could therefore be written as follows:

            name    errMacro
errMac      macro   text
            extern  abort
            call    abort
            dc8     \1,0
            endm

Use the EXITM directive to generate a premature exit from a macro.

EXITM is not allowed inside REPT...ENDR, REPTC...ENDR, or REPTI...ENDR blocks.

Use LOCAL to create symbols local to a macro. The LOCAL directive must be used before the symbol is used.

Each time that a macro is expanded, new instances of local symbols are created by the LOCAL directive. Therefore, it is legal to use local symbols in recursive macros.

Passing special characters

Macro arguments that include commas or white space can be forced to be interpreted as one argument by using the matching quote characters < and > in the macro call.

For example:

            name    macroUser
ldaMac      macro   op
            mov     op
            endm

The macro can be called using the macro quote characters:

            ldaMac  <A, #1>

You can redefine the macro quote characters with the -M command line option, see -M.

Predefined macro symbols

The symbol _args is set to the number of arguments passed to the macro. This example shows how _args can be used:

fill        macro
            if      _args == 2
            rept    \2
            dc8     \1
            endr
            else
            dc8     \1
            endif
            endm

            module  filler
            section .text:CODE(2)
            fill    3
            fill    4, 3
            end

Repeating statements

Use the REPT...ENDR structure to assemble the same block of instructions several times. If expr evaluates to 0 nothing is generated.

Use REPTC to assemble a block of instructions once for each character in a string. If the string contains a comma it should be enclosed in quotation marks.

Double quotes have a special meaning—their only use is to enclose the characters to iterate over. Single quotes have no special meaning and are treated as ordinary characters.

Use REPTI to assemble a block of instructions once for each string in a series of strings. Strings containing commas should be enclosed in quotation marks.

This example assembles a series of calls to a subroutine plotc to plot each character in a string:

         name    reptc
         extern  plotc
         section CODE:CODE
         code
banner   reptc   chr,"Welcome"
         mov     A,#'chr'
         call    plotc 
         endr
         ret
         end

This example uses REPTI to clear several memory locations:

         name    repti
         extern  base,count,init
         section CODE:CODE(0)
         mov     A, #0
banner   repti   adds,base,count,init
         mov     adds, A
         endr
         end

Coding inline for efficiency

In time-critical code it is often desirable to code routines inline to avoid the overhead of a subroutine call and return. Macros provide a convenient way of doing this.

This example outputs bytes from a buffer to a port:

        name    play
P0      define  0xFF00

        section DATA:DATA(0)
buffer  ds8     25
watch   dc8     0xFF
        section CODE:CODE(0)
play    movw    AX,#buffer
        movw    HL,AX
        mov     b,#0
        mov     A,[HL+B]
loop    inc     B
        mov     P0, A
        mov     A,[HL+B]
        cmp     A,watch
        bnz     loop
        ret
        end

The main program calls this routine as follows:

doplay      call    play

For efficiency we can recode this using a macro:

        name    play
play    macro
        local   loop
        movw    AX,#buffer
        movw    HL,AX
        mov     B,#0
        mov     A,[HL+B]
loop    inc     B
        mov     P0, A
        mov     A,[HL+B]
        cmp     A,watch
        bnz     loop
        endm

P0      define  0xFF00
        section DATA:DATA(0)
buffer  ds8     25
watch   dc8     0xFF
        section CODE:CODE(0)
main    play
        play
        ret
        end

Notice the use of the LOCAL directive to make the label loop local to the macro—otherwise an error is generated if the macro is used twice, as the loop label already exists.