The macro facilities provided by the IBM Macro Assembler/2 include
MACRO, REPT, IRP, and IRPC. The ENDM pseudo-op ends each of these four macro operations.
Terms Used
These terms are used with the MACRO, REPT, IRP, and IRPC pseudo-ops:
• A dummy represents a dummy parameter. All dummy parame-ters are valid symbols that appear in the body of a macro expan-sion.
• A dummylist is a list of dummies separated by commas.
• An
<
operandlist> is a list of operands separated by commas.The <operandlist> must be delimited by angle brackets. Two angle brackets with no intervening character entries « » or two commas with no intervening character entries become a null operand in the list. An operand is a character or series of char-acters ended by a comma or the end angle bracket (». With angle brackets that are nested inside an <operandlist> , one level of brackets is removed each time the bracketed operand is used in an <operandlist>. A quoted string is an acceptable operand.
• A parmlist is used to represent a list of actual parameters sepa-rated by commas. No delimiters are required (the list is ended by the end of line or a comment).
• A macro is a set of assembler statements that you can use several times in a program, with some optional changes each time.
various parts of a MACRO definition:
• The beginning of a macro definition is the MACRO pseudo-op.
• The end of a macro definition is the ENDM pseudo-op.
• The body of a macro is all the lines of assembler statements between MACRO and ENDM.
• The name of the macro (the pseudo-op that is used to call it) is defined in the name field of the MACRO pseudo-op.
• The parameters (optional) are a series of one or more dummy symbol names listed as operands on the MACRO pseudo-op. If more than one parameter is used, the dummy symbols must be separated by commas or blanks. In some cases, there are no parameters. The number of parameters is limited to the number you can define on a 128-character MACRO pseudo-op statement.
This example shows the naming of the macro and the dummy param-eter list. In this example, the string VAL 1 is put wherever the dummy ARG1 appears in the macro, and VAL2 for ARG2.
;; Macro invocation statement
;; MASM expands the macro here at
" assemble time with VALl &VAL2
;; as the actual parameters
Macro Parts: The body of the macro can have several parts:
• LOCAL - The local pseudo-op creates unique labels for use in macros. Normally, if a macro containing a label is used more than once, the assembler displays an error message indicating that the file contains a label or symbol with multiple definitions, because the same label appears in both expansions.
2-8
If this pseudo-op is used, it must be the next statement following the MACRO pseudo-op. No comment, not even a blank line, may appear between MACRO and LOCAL. The assembler substitutes a unique label for the label you used, so each time the macro is called, a different label is produced; this avoids duplication. MUl-tiple, consecutive LOCAL statements are allowed.
Macro example for LOCAL pseudo-op:
LOOPZERO MACRO ARGI LOCAL LOOPLABEL
MOV AX,ARGI LOOPLABEL:
DEC AX JNZ LOOPLABEL ENDM
• Remarks or Comments - They are indicated either by the
COMMENT pseudo-op or by a semicolon. They are listed in a macro expansion only if they are under the .LALL mode. A
comment beginning with double semicolons is not listed when the macro is called.
• Pseudo-ops and Instructions - These statements become effec-tive only when the MACRO containing them is called. For example, a MACRO definition can be contained within the body of another macro. The inner macro is not defined until the outer macro is called, as shown in the following example:
.LALL ;set print mode
so (;) comments print CALLSUB MACRO
JMP SHORT SKIP
;;Produce the subroutine,
;; one time only
CALLSUB ;produce subrt, then call it
repeating block. Using the double semicolon to suppress comments in the macro expansion is also illustrated in this example. Only com-ments preceded by a single semicolon show up when the Macro Assembler expands the macro. The IRPC is used in a similar fashion, but repeats once for each character in a string instead of once for each parameter in the parameter list.
2-10
:XAM MACRO AI,A2,A3 stack. The comment with the single semicolon was listed three times because it is in the repeating part, which had three parameters, and, therefore, repeated three times.
The example below illustrates the REPT pseudo-op, which repeats by
CNT = 0
The INCLUDE pseudo-op provides an excellent way of implementing macro libraries. You should create a source or include file that con-tains the macro definitions. Place the INCLUDE statement at the begin-ning of your source program. It specifies the include file, for
instance, MACLlB.INC. Thus, MACLlB.INC is a separate text file that con-tains all macro definitions.
You can speed up assembly and print time if you run INCLUDE only on
The macro definitions are not listed (because printing the listing is a pass 2 operation). Also, on pass 2, this file is not opened and read again, which is an unnecessary operation. This use of IF1 before the
INCLUDE is not allowed if:
• The library contains source statements that actually produce code.
• MACRO redefined itself on the first call, as shown in the preceding example.
However, IF1 is useful if the library has macro definitions only. (The library can also have the definitions of structures and records but no expansions of these.)
The parameters are defined on the MACRO pseudo-op and are sepa-rated by commas. These parameters are position dependent.
Faa MACRO Pl,P2,P3
P1 is the first parameter, P2 is the second, and P3 is the third.
These symbols, defined as parameters, can appear anywhere in the body of the macro.
An example of instructions using these parameters within a macro is:
MOV AX,Pl P2 P3
When this macro is called (expanded), the macro call statement is whatever has been defined in the name field of a previously defined
MACRO pseudo-op. The call statement can specify parameters that correspond by relative position to the dummy parameters defined in the macro definition. For example:
Faa WORDVAR,INC,AX
showing the above substitutions, and become:
MOV AX.WORDVAR INC AX
One parameter is used as a variable name, another as an opcode, and the last as a register name.
A dummy parameter within the body of a macro must be separated by commas, or it is not recognized as a dummy parameter and is not substituted. If the body has this statement:
JMP TAPI
TAPl: ;TAPI is a label
the symbol TAP1 is considered a label. The P1 portion is not replaced by the first parameter taken from the call statement. However, a dummy parameter can be recognized within a string by prefixing it with the ampersand (&) sign. For example:
JMP TA&Pl
This time the operand is substituted, producing:
JMP TAWORDVAR
An instruction op-code can be built by joining together several pieces in this manner using the ampersand. For example:
LEAP MACRO COND.LAB
The equal sign (=) pseudo-op is also helpful within a macro because it can be used to redefine the value of a counter. For example:
BUMP MACRO
CNTR CNTR+l
ENDM
Note: Initialize CNTR before calling BUMP.
2-14
This counter has a value that you can get by using the special prefix,
% , before the parameter in a macro call statement:
ERRMSG MACRO TEXT
CNTR CNTR+l
MSG %CNTR,TEXT ENDM
MSG MACRO COUNT,STRING MSG&COUNT DB STRING
ENDM
Note: In the above example, one macro calls another.
Call the fi rst macro by:
ERRMSG 'SYNTAX ERROR'
Which produces:
MSGI DB 'SYNTAX ERROR'
Call it again with:
ERRMSG 'INVALID OPERAND'
Which produces:
MSG2 DB 'INVALID OPERAND'
The % prefix causes a different kind of substitution, a substitution of the value of a parameter, not the character string of the name of that parameter.
On closer examination of your results, you may wonder what hap-pened to the CNTR
=
CNTR+
1 statement, because the macro expan-sion does not show anything for this line. Apparently, the CNTRvariable is being increased, as shown by the two variable names,
MSG1 and MSG2. For a solution, try putting .LALL at the top of the
The mode facilities provided by the IBM Macro Assembler/2 include the /R and /E options and the .186, .286C, .286P, .287, .8086, and .8087 pseudo-ops. The Mode pseudo-ops, the IR option, and the IE option allow the IBM Macro Assembler/2 to be used with various machine setups and microprocessors.
Note: See Chapter 3, "Pseudo Operations," in this book for details on each of the mode pseudo-ops, and see the discussion of the /R and IE options in the IBN Macro Assemblerl2 Assemble, Link, and Runbook .
. ~ .
The IBM Macro Assembler/2 can assemble instructions for various machine setups and microprocessors.
For example:
• 8086/8088-based IBM Personal Computers and IBM Personal System/2 Computers
• 8086/8088-based IBM Personal Computers and IBM Personal System/2 Computers with the 8087 Math Coprocessor feature
• 80286/80386-based IBM Personal Computers and IBM Personal System/2 Computers
• 80286/80386-based IBM Personal Computers and IBM Personal System/2 Computers with the 80287 Math Coprocessor feature.
The instructions are considered upwardly compatible at the source-code level and generally upwardly compatible at the object-source-code level. This means that the instructions that are only for the 80286 are not compatible with the instructions for the 8088. However, the 8088 type instructions are compatible with the 80286 instructions. The IBM
Macro Assembler/2 can recognize the different types of instructions.
The mode pseudo-ops tell the Macro Assembler what type of instructions to accept.
The default mode is 8088/8086. In this mode, the 8087, 80287, and 80286 instructions cause a syntax error during assembly.
2-16
The functions of each mode pseudo-op are described below:
• A .186 mode pseudo-op allows the Macro Assembler to recognize 8086 instructions and instructions for the 80186 microprocessor.
• A .286C mode pseudo-op is required for the Macro Assembler to recognize 80286 nonprotected instructions in addition to 8088 or 8086 instructions.
• A .286P mode pseudo-op is required for the Macro Assembler to recognize 80286 protected instructions, in addition to 8088,8086, and 80286 nonprotected instructions.
• A .287 mode pseudo-op is required for the assembly of 80287 floating-point coprocessor instructions. You can use the IE or IR options for the Macro Assembler to generate 80287-type
instructions. If you specify .287 and IE, all 80287 instructions will be generated with an FWAIT instruction.
• The .8087 mode pseudo-op lets you assemble 8087 instructions.
You can use the IE or IR assembly options to produce 8087-type instructions, but these options are not required.
• The .8086 mode pseudo-op lets you assemble 8086 instructions and the identical 8088 instructions. This is the default mode.