.MA MAcro definition
Syntax:
macroname .MA [comment]
.MA macroname [comment]
See also:
Function:
The .MA directive starts the definition of a Macro.
Boundary Sync:
In Version 3 of the SB-Assembler this directive will perform a boundary sync.
Explanation:
The syntax of the .MA directive has 2 appearances.
The first one above has the more usual notation with the macroname in the label field, followed by the .MA directive in the instruction field.
The .MA directive may be followed by comments.
The second notation puts the macroname in the operand field, behind the .MA directive.
This notation is not recommended and is only available for compatibility reasons with the Apple ][ version of the SB-Assembler.
The macroname may also be followed by comments in this notation.
There is a special reason why I explicitly say that comments are allowed behind the .MA directive.
Most directives may be followed by comments, so that's not so special by itself.
But here it is particularly useful to add comments to indicate what parameters are expected by the Macro that you're going to define.
Please note that the real parameters are given at the instances where you want the Macro to expand.
Here, after the .MA directive they serve only a documentary purpose.
The same rules apply to macroname as for Global label names, with the only exception that a macroname is only remembered up to 31 characters (Version 3 of the SB-Assembler has no length limit).
The macroname must start with a character from A to Z, and may contain other characters from A to Z, digits from 0 to 9, the underscore _ and a dot .
As of Version 3.01 macroname may also start with an underscore.
The macroname must be a unique Macro name.
However it is allowed to give a Macro the same name as a label.
Macro names are stored in a separate symbol table.
The following directives are not allowed during the definition of a Macro (from the opening .MA directive until the closing .EM directive):
.MA, .IN, .CH, .BI, .EN, .CO and .EC
In Version 3 of the SB-Assembler the .EN directive is allowed inside a macro definition. When the .EN directive is encountered inside an expanding macro it will end all currently expanding macros and the current include file, all at the same time.
With Version 2 of the SB-Assembler new Local label definitions are not allowed after a Macro definition until at least one new Global label is declared.
With Version 2 of the SB-Assembler a fatal error will be reported if the end of a source file is reached while in the middle of defining a Macro with the .MA directive.
Version 3 of the SB-Assembler will automatically insert an .EM directive if the source file ends during a macro definition, which avoids causing an error.
A detailed description of the Macro capabilities of the SB-Assembler can be found in a separate chapter.
Examples:
Let's define a Macro that exchanges 2 bytes in memory without altering any of the processor's registers on a 6502.
XCHNG .MA memory1,memory2
PHP ; Save flags register
PHA ; Save Accu
LDA ]1 ; Get the 1st byte from memory
PHA ; and put it on the stack
LDA ]2 ; Copy the 2nd byte to the
STA ]1 ; 1st memory location
PLA ; Save the 1st byte to
STA ]2 ; the 2nd memory location
PLA ; Restore Accu
PLP ; Restore the flags register
.EM ; Done
All parameters in the Macro definition have the notation ]x , where x is the parameter number. This parameter number is determined by the location in the operand field of the Macro call. In the example above the parameter ]1 will be replaced by the first parameter memory1. The parameter ]2 will be replaced by the second parameter memory2.
Here are two examples showing you how you would use the above declared macro.
>XCHG BYTE1,BYTE2 Swap BYTE1 and BYTE2
>XCHG VALUE1,VALUE2 Swap VALUE1 and VALUE2
