6.1 Using Macros

Programs often contain routines that are executed several times. Instead of repeating the source statements for a routine, you can define the routine as a macro, then call the macro in the places where you would normally repeat the routine. This simplifies and shortens your source program.

If you want to call a macro several times but with different data each time, you can assign parameters within a macro. This enables you to pass different information to the macro each time you call it. The macro language supports a special symbol called a substitution symbol, which is used for macro parameters. See Section 6.3 for more information.

Using a macro is a 3-step process.

1. Define the macro. You must define macros before you can use them in your program. There are two methods for defining macros:
   1. Macros can be defined at the beginning of a source file or in a copy/include file. See Section 6.2, Defining Macros, for more information.
   2. Macros can also be defined in a macro library. A macro library is a collection of files in archive format created by the archiver. Each member of the archive file (macro library) may contain one macro definition corresponding to the member name. You can access a macro library by using the .mlib directive. For more information, see Section 6.4.
2. Call the macro. After you have defined a macro, call it by using the macro name as a mnemonic in the source program. This is referred to as a macro call.
3. Expand the macro. The assembler expands your macros when the source program calls them. During expansion, the assembler passes arguments by variable to the macro parameters, replaces the macro call statement with the macro definition, then assembles the source code. By default, the macro expansions are printed in the listing file. You can turn off expansion listing by using the .mnolist directive. For more information, see Section 6.8.

When the assembler encounters a macro definition, it places the macro name in the opcode table. This redefines any previously defined macro, library entry, directive, or instruction mnemonic that has the same name as the macro. This allows you to expand the functions of directives and instructions, as well as to add new instructions.