13

Macros

Overview In previous chapters we have shown how programming may be sim-

plified by using procedures. In this chapter. we discuss a program structure
called-a n111Cro, which Is similar to a procedur..:.
·As ~Ith procedures, a macro name represents a group of instructions.
Whenever the .instructions are needed In the program, the name Is used.
However, the way procedures and macros operate Is different. A procedure
. is· called at execution time; control transfers to the procedure and returns
after. ·e.xecutlng Its statements. A macro Is invoked at assembly time. The
assembler copies the macro's statements into the program at the position of
the invocation. When the program executes, there is no transfer of control.
· ·: ' Macros a·re csp'edally useful for carryini; out tasks that occur fre-
quently. for example, we can write macros to initialize the OS and ES regis-
ters, print a character string, terminate a program, and so on. We can also
write macros to eliminate restrictions in existing instructions; for example,
the operand of MUL can't be a constant, but we can write a multiplication
macro that doesn't have this restriction.

13.1
Macro Definition A macro Is a block of text that has bcCn given a name. When MASM
and Invocation encounters the name during assembly, it inserts the block Into the pr<)gram.
The text may consist of Instructions, pseudo-ops, comments, or references
to other macros. • '
The syntax of mac·ro definition is
macro_name MACRO dl,d2,: . .'dn
.stat~ment~
ENDM
· JSI 13. I Macro Definition and Invocation

Here macro_name is the user-supplied name for the macro. The

pseudo-ops MACRO and ENDM indicate the beginning and "nd of the macro
definition; dl, d2, ... dn is an optional list of dummy arguments used by
the macro.
One use of macros is to create new instructions. For example, we
know that the operands of MOV can't both be word variables, but we can
get around this restriction by defining a macro to move a wonHn~<> a.~ord.

Exam11lc 13.1 Define a macro to move a word into a word.

Solution:
MOVW MACRO WORDl, WORD2
PUSH WORD2
POP WORDl
ENDM
I!ere the name of the macro is MOVW. WORD I and WORD2 are the <lummy
arguments.
To use a nwcro in a program, .we invoke it. The syntax is
macro name al, a2, . . . an

where al, a2, ... an is a list of actual arguments. When MASM encounters
the macro name, it expands the macro; that is, It copies the macro state-
ments into the program at the position of the invocation, just as if the user
had typed them in. As it copies the statements, MASM replaces each dummy
argument di by the corresponding actual argument ai and creates the ma-
chine code for any instructions. '
A macro definition must come before its invocation in a program
listing. To ensure this sequence, macro definitions are usually placed at the
beginning of a program. It is also possible to create a library of macros to be
used by any program, and we do this later in the chapter.

Example 13.2 Invoke the macro MOVW to move B to A, where A and

B are word variables.

Solution: MOVW A, B

To expand this macro, MASM would copy the macro statements Into'
the program at the position of the call, replacing each pccurren~ 9f,WORJ;>l
by A, and WORD2 by B. 'Ille tesult is ·
PUSH B
POP A
•"l ''.
In expanding a macro, the assembler simply substitute.s the character
strings 'defining the actual arguments for the corresponding dummy ones.
F~r example, the following calls to the MOVW macro ·'

MOVW A,DX and MOVW A+2,B

cause the assembler to insert this code into the program: .
PUSH DX and PUSH B
POP A POP A+2
 u1apcer IJ Macro~ 259

Illegal Macro Invocations

There are often restrictions on the arguments for a macro. For ex-
ample, the arguments In the MOVW macro must be m<.>mory words or 16-bit
registers. Thl' mauo invocation
MOVW AX, lABCh
generates the code
PUSH lADCh
POP AX
and because an immediate data push is illegal (for the 8086/8088), this results
in an assembly error. One way to guard against this situation is tu put a
comment in the macro; for example,
MOVW MACRO WORD1,WORD2
;arguments must be memory words or !(·-bit t<=<JLSL··•1:;
PUSH WORD2
POP WORUl
ENDM

Restoring Registers
G~d programming practice requires that· a proct.'Clure should restore
the registers it uses, unless they contain output values. The same is u~ually
true for macros. As an example, the following macro exchanges two memory
words. Because It uses AX to perform the exchange; this register is restored.
,,.'CH MACRO WORD1,WORD2
PUSH AX
MOV AX,WORDl
XCHG AX,WORD2
MOV WORDl,AX
POP AX
ENDM

Mc. cro Expansion in the .LST File

T~l .LST file is one of the files that can be generated when a prugrdm
is assemblld ·.:ee Appendix D). It )hows a)scmbly cock and the corresponding
machine C('l1c .. addresse) of variable), and other information about the pro-
gram. The· LS'I file also shows how macro~ are expanded. To demomtrate
this, the fol11wi.1g program contains the MOVW macro and two invocations:

Program Listing PGM13_1.ASM

TITLE PGM13_1: MACRO DEMO
. MODEL SMALL
MOVW MACRO wpRDl, WORD2
PUSH WOR02
POP WOF.01
ENUM
.:;TACK 10011
.DATA
A ow 1, 2
B ow 3
.<::ODE
260 13. 1 Macro Definition and Invocation

MAIN PROC
MOV AX,(!DATA
MOV DS,AX
MOVW A,DX
MOVW A+2,D
;dos exit
MOV AH, 4CH
INT 21H
MAIN ENDP
!::ND MAIN

. Figure 13.1 shows file PGM13_1.1Sf. In this file, MASM prints the
macro invocations, followed by their expansions (shown In boldface). The
digit 1 that appears on each line or the expansions means these macros were
invoked at the "top level"; that is, by the program itself. We wlll show later
that a macro may invoke another macro.

------·------
Figure 1~.1 PGM 13_1.LST Microsoft (R) Macro Assembler Version 5. 10
1/18/!).2 00:03:08
PGM13_1: MACRO DEMO Page 1-1
TITLE PGM13 l: MACRO DEMO
.MODEL SMALL
MOVW MACRO WORDl,WORD2
PUSH WORD2
POP WORDl
ENDM
.STl\CK 10011
.Dl\TA
0000 0001 0002· A DW 1,2
0004 0003 B DW 3
.CODE
0000 MAIN PROC
oobo BS - R MOV AX,@DATA
0003 SE DS MOV DS,AX
MOVW A,DX
0005 52 1 PUSH DX
0006 8F 06 0000 R 1 POP A
t«>VW A+2,B
OOOA FF 36 0004 R l PUSH B
OOOE ··aF 06 0002 R l POP A+2
;dos exit
0012 B4 4C MOV AH,4CH
0014 CD 21 INT 21H
0016· MAIN ENDP
END MAlN

Microsoft (R) Macro Assembler Version 5. 10

1/18/92 00:03:0S
PGM13_1: MACRO DEMO Symbols-1
Macros:
 Chapter 13 Macros 261

Figure 13.1 PGM13_1.LST

N _a .. m e Lines
(Continued)
MOVW . 2

Segments and Groups:

N a m e Length Align Combine Class

DGROUP GROUP
_DATA 0006 WORD PUBLIC 'DAT.!\'
STACK 0100 PARA STACK 'STACK'
TEXT 0016 WORD PUBLIC 'CODE'

Symbols:
N a m e Type Value At tr
/

A L WORD 0000 DATA "'

B L WORD 0004 DATA

MAIN N PROC 0000 TEXT

Length 0016

@CODE . TEXT TEXT

@CODESIZE TEXT 0
<!CPU . . TSXT OlOlh
f'[l/\'r/\::< T 7.F 1'!'.XT 0
@FILENAMI:: TEXT l'GMl.l
@VERSION . TEXT ~10

21 ScJUrce Lines
25 Total Lines
21 Symbols

47930 + 4220033 Bytes symbol npace f rec

.> ';•·

0 Warning- Errors ,
0 Severe .Errors ..;

.LST File Options

Tlm:c assembler directives govcri1 how macro cxpa1i~iom appear in the
.I.ST file. Th1.>se directives pertain to the macros that follow them in the program.
1. After .SALL (suppress all), the assembly code in-a macro cxpan-
, 'sion is noi listed. You might want to use this option for large
· ·macros, or ,if there ·are a lot of mal'ro invocations.
2., Alter .XAl.L, only those sourn• lirll'~ tll~ll ~cm:ratc l"nde <ll" d<rl<I
;ire listed. For example, comment line' arc not lbtcd. This i\ till'
ddault option ..
3. After .LALL (list all), all source lines ;ire li;ll'U, except those
hq;i1111i11_, with a duul~c scmicolo11 (;;).
262 13.2 Loe.al Labels

These directives do not affect the machine code generated in the macrc
invocations; only the way the macro expansion appear in thl.' .LST file.

Example 13.3 Suppose the MOVW macro is rewritten as follows:

MOVW MACRO WORD1,WORD2

;moves source to destination
; ; uses the stack
PUSH WORD2
POP WORDl
·ENDM

Show how the following macro Invocations would appear in a .I.ST file
.XALL
MOVW OS,CS
.LALL
MOVW P,Q
.SALL
MOVW AX, [SI]

Solution:
.XALL
MOVW DS,CS
PUSH cs
POP OS
.LALL
MOVW P,Q
;moves source to destination
PUSH Q
POP P
.SALL
MOVW AX, [Sl)

Finding Assembly Errors

If MASM finds an error during macro expansion, It Indicates an error
at the point of the macro Invocation; however, It's more likely that the
problem ls within the macro itself. To find where the mistake really ls, you
need to insp,ect the macro expansion In the .LST file. The ,LST file is especially
helpful if you have a macro that Invokes other macros (see discussion later).

13.2
Local Labels A ·macro with a loop or decision structure contains one' or more
a
labels. If such a macro Is Invoked more than once In program, a duplicate
label appears, resulting In an assembly error: This problem can be avoided
by using local labels In the macro. To declare them, we use. the LOCAL
pseudo-op, whose syntax Is
LOCAL list_of __ labels
 Chapter 13 Macros 26i

where list_of_labels is a list of labels, separated by commas. Every time the

macro is expanded, MASM assigns different symbols to the lab('!s in the list.
The LOCAL directive must appear on the next line after the MACRO ~tate-
ment; not even a comment can precede it. ·

Example 13.4 Write a macro to place the largest of two words in AX.

Solution: '
GET BIG MACRO WORD1,WORD2
LOCAL EXIT
MOV AX, WOIUH
CMP AX,WORD2
JG EXIT
. MOV AX,WORD2
EXIT:
ENDM
Now suppose that FIRST, SECOND, and THIRD are word variables. ,\ macro
invocation of the form
GET BIG FIR~T,SECOND

expands as follows:
MOV AX, FIRST .
CMP AX,SECOND
JG ??0000
MOV AX,SECOND
??0000:
A later call of the form
GET BIG SECOND,THIRD
expands to this code:
MOV AX, SECOND
'CMP AX, THIRD
JG ??0001
. MOV AX, TllIRD
??0001:
Subsequent invocations of this inacio or to other macros with local labels caw.cs
MASM to insert labels ??0002, ??0003, and so on into the program. These labels
are lmique and not likely to conflict with ones the user would choose.

1~~3·
Macros that Invoke·
•. • • .;. f ( • •

A macro may invol:c another macro. Suppose, for exampll', we have

Other Macros two macros that savl' am! rl·storc thrl'l' n·ghlt•rs:
SAVE REGS MACRO Rl, R2, R3 RESTORE - REGS MACRO !:il,~:L,53
- PUSH Rl POP
......
!.Jl
,
FUSJI H2 1'01'
PtJSll H3 PC'l' ~~ -~

ENDM ~OM

These_mac~os. arc_invoked by the macro in the following example.

264 13.4 A fvi.icro Library

... Example 13.5 Write a macro to copy a string. Use the SAVE_REGS and
RESTORE_REGS macros.

Solution:
COPY MACRO SOURCE, DESTINATION, LENGTH
SAVE_REGS CX,SI,DI
LEA SI, SOURCE
LEA DI, DESTINATION
CLO
MOV CX,LENGTH
REP MOVSB
RESTORE REGS DI,SI,CX
ENDM
If MASM encounters the macro invocation
COPY STRING1,$TRING2,15
it will copy the following code into the program:
PUSH ex
PUSH Sl
PUSH DI
LEA SI, STRINGl
LEA DI,STRING2
CLO
MOV CX,15
REP MOVSB
POP DI
POP SI
POP ex
Note: A macro may invoke itself; such macros are called recursive macros.
They are not discussed in this book.

13.4
A Macro Library The macros that a program invokes may be contained in a separat~
file. This makes it possible to create a library file of useful macros. For ex-
ample, suppose the file's name Is MACROS, on a disk In drive A. When
MASM encounters the pseudo-op
INCLUDE A:MACROS
in a program, it copies all the macro definitions from th~ file MACROS Into
the program at the position of the ·INCLUDE statement (note: the INCLUDE
directive was discussed In section 9.5). The INCLUDE' statement may appear
anywhere in the program, as long as it precedes the invocations of its macros.

The IF1 Conditional

If a macro library is Included in a program, all its macro definitions
will appear in the .LST 'mc;cVen If they're not invoked In the program. To.
prevent this, we can insert the following:
 Chapter 13 Macros 265

1Fl
INCLUDE MACROS
J::NDIF

Here, 11'1 arid ENDIF are pseudo-ops. The If! directive causes the assembler
to access the MACROS file during the first assembly pass, when macros arc
expanded, but not during the second pas~. when the .LST file is nealcd.
· Note: Other conditional pseudo-ops are dlscuscd in section 13.6.

Examples of Useful Macros

The following are examples of macros that are useful to have in a
macro library file.

Example 13.6 Write a macro to return to DOS .

.- ... -
Solution:
. DOS_RTN MACRO
MOV AH,4CH
INT 21H . --
ENDM

The macro invocation is

DOS_RTN

Example 13;7 Write a macro to execute a carriage return and line feed .

.Solution:
NEW LINE MACRO
MOV AH, 2
MOV DL,ODH
INT 21H
MOV DL, OAH.
INT 21H
ENDM .•

The macro Invocation is

NEW LINE

The next example is one of the more interesting macros.

Example 13.8 •Write a macro to display a character string. The string is

the macro parameter.

Solution:
DlSP_STRMACRO STRING
LOCAL START,MSG
; save registers
PUSH AX
PUSH DX
PUSH DS
.JMP • S'IART
266 13.4 A Macro Library

MSG DB STRING,'$'
START:
MOV AX,CS
MOV OS, AX ; set OS to c:>de seg ·.~ ,:;
MOV AH,9
LEA OX, MSG
INT 21H
;restore registers
POP OS
POP DX
POP AX
ENDM
Sample invocation:
DISP STR 'this is ..• string'
When this macro is invok~-:1. the string parameter replaces the dummy pa-
rameter STRING. Becaus~ •11c strin~ Is being stored ln the code segment, CS
must be moved to D'l; U1h takr ~ two Instructions, because a direct move
between segment registc!rS Is fo1bidden.

Including i'J Macro Library

The p•c1..eding macros have been placed in file MACROS on the stu-
dent disk. They are used in the following program, which displays a message,
goes to a new ~· ., and displays another message.

Progr•m Listing PGM13_2.ASM

7ITLE PGM13 2: MACRO DEMO
. MODEL SMALL
.STAC:I' lOOH
T:C 1
INCLUDE MACROS
ENDif
.CODE
MAIN PROC
DISP STR 'this is the first line'
NEW_LINE
DISP_STR 'and this is the second line•
DOS_RTN
MAIN ENDP
END MAIN

Sample exemtion: .

C>PGM13_2
this is the first line
and this is the second line

The macro expansions are shown In file PGM13_2.LST (Figure 13.2).

To save space, the machine code has been edited out.