Microsoft®

40 Macro Assembler
Reference Manual

for the MST,,,-DOS Operating System

0
Mirrosnft Cornoration
Information in this document is subject to change without notice and
does not represent a commitment on the part of Microsoft Corpora-
tion . The software described in this document is furnished under a
license agreement or nondisclosure agreement . The software may be
used or copied only in accordance with the terms of the agreement . It
is against the law to copy this software on magnetic tape, disk, or any
other medium for any purpose other than the purchaser's personal
use .

® Copyright Microsoft Corporation, 1984

Microsoft and the Microsoft logo are registered trademarks, and MS is

a trademark of Microsoft Corporation .

Document Number : 8451-300-00

0


Contents
0
Chapter 1 Introduction
1 .1 Overview 1-1
1 .2 What You Need 1-2
1 .3 Notational Conventions 1-3

Chapter 2 Elements of the Assembler

2 .1 Introduction 2-1
2 .2 Character Set 2-1
2 .3 Integers 2-1
2 .4 Real Numbers 2-2
2 .5 Encoded Real Number 2-3
2 .6 Packed Decimal Numbers 2-3
2 .7 Character and String Constants 2-4
• 2 .8 Names 2-5
2 .9 Reserved Names 2-5
2 .10 Statements 2-7
2 .11 Comments 2-7
2 .12 COMMENT Directive 2-8
Chapter 3 Program Structure
3 .1 Introduction 3-1
3 .2 Source Files 3-1
3 .3 Instruction Set Directives 3-3
3 .4 SEGMENT and ENDS Directives 3-4
3 .5 END Directive 3-8
3 .6 GROUP Directive 3-9
3 .7 ASSUME Directive 3-10
3 .8 ORG Directive 3-11
3 .9 EVEN Directive 3-12
3 .10 PROC and ENDP Directives 3-12

0 Chapter 4
4 .1
Types and Declarations
Introduction 4-1
4 .2 Label Declarations 4-1
4 .3 Data Declarations 4-2


4.4 Symbol Declarations 4-8

4 .5 Type Declarations 4-11
4.6 Structure and Record Declarations 4-13
Chapter 5 Operands and Expressions

5 .1 Introduction 5-1
5 .2 Operands 5-1
5 .3 Expressions 5-10
5 .4 Forward References 5-23
5 .5 Strong Typing for Memory Operands 5-26
Chapter 6 Global Declarations
6 .1 Introduction 6-1
6 .2 PUBLIC Directive 6-2
6 .3 EXTRN Directive 6-3
6 .4 Program Example 6-4
Chapter 7 Conditional Assembly
7 .1
7 .2
Introduction 7-1
IF and IFE Directives 7-2
0
7 .3 IF1 and IF2I)irectives 7-2
7 .4 IFDEF and IFNDEF Directives 7-3
7 .5 IFB and IFNB Directives 7-3
7 .6 IFIDN and IFDIF Directives 7-4
Chapter 8 Macro Directives
8.1 Introduction 8-1
8 .2 MACRO and ENDM Directives 8-2
8 .3 Macro Calls 8-4
8 .4 LOCAL Directive 8-5
8 .5 PURGE Directive 8-6
8 .6 KEPT and ENDM Directives 8-7
8 .7 IRP and ENDM Directives 8-8
8 .8 IHPC and END -,M Directives 8-10
8 .9 EXITM Directive 8-11
8 .10 Substitute Op erator 8-12
8.11 Literal Text . Operator 8-13
8 .12 Literal Character Operator 8-14
8 .13 Expression Operator 8-14
8 .14 Macro Comment 8-15


Chapter 9 File Control

9 .1 Introduction 9-1
9 .2 INCLUDE Directive 9-1
.RADIX Directive
9 .3 9-2
9 .4 cO1JTDirective 9-3
9 .5 NAME Directive 9-4
9 .6 TITT .E Directive 9-1
9 .7 SUBTITLE Directive 9-5
9 .8 PAGE Directive 0-5
9 .9 LIST and .NLIST Directives 9-6
9 .10 .SF('ONI) .LFCOND,
and TFC(YND Directives 0-7
9 .11 LALL, .XALL, and .SALL Directives 9-8
9 .12 CREF and .X('IZEF Directives 9-9
Appendix A Instruction Summary
A.I Introduction A-1
. A .2 8086 lust :ructions A-2
A.3 8087 Instruction .\Inenionics :1-7
A.4 186 Instruction Mnemonics A-0
A.5 286 Non-Protected
Instruction Mnemonics A-10
A.6 286 Protected Instruction Mnemonics A-10
A.7 287Instruction Mnemonics A-11
Appendix B Directive Summary
B .1 Introduction B-1
Appendix C Segment Names
For Iligh-Level Languages
(" .1 Int rodnct ion ('-I
C .2 Text Segments C-2
C .3 Data Segments--Near C'-4
C .4 Data Segments - Far C-5
• C .5 Bss Segments C'-6
C .6 Constant Segments C-8
S

Chapter 1
• Introduction

1 .1 Overview 1-1

1 .2 W h at You Need 1-2

1 .3 Notational Conventions
S

0
 Introduction

0 1 .1 Overview
This manual describes the usage and input syntax of the Microsoft®
Macro Assembler, MASM . The assembler produces relocatable object
modules from 8086, 186, or 286 assembly language source files . The re-
locatable object modules can be linked, using the Microsoft Linker,
LINK, to create executable programs for the MS-DOS operating sys-
tem .

MASM is an assembler for the 8086/186/286 family of microproces-

sors . It can assemble the instructions of the 8086, 186, and 286 mi-
croprocessors, and the 8087 and 287 floating point coprocessors . It has
a powerful set of assembly language directives that give the program-
mer complete control of the segmented architecture of the 8086, 186,
and 286 microprocessors . MASM instruction syntax allows a wide
variety of operand data types, including integers, strings, packed de-
cimals, floating point numbers, structures, and records .

0 MASM is a macro assembler . It has a full set of macro directives that

let a programmer create and use macros in a source file . The directives
instruct MASM to repeat common blocks of statements, or replace
macro names with the block of statements they represent . MASM also
has conditional directives that let the programmer exclude portions of
a source file from assembly, or include additional program statements
by simply defining a symbol .

MASM carries out strict syntax checking of all instruction statements,

including strong typing for memory operands . Unlike other assem-
blers, MASM detects questionable operand usage that can lead to er-
rors or unwanted results .

MASM produces object modules that are compatible with object

modules created by high-level language compilers . Thus, you can
make complete programs by combining MASNI object, modules with
object modules created by the C compiler or other language compilers .

This manual does not teach assembly language programming, nor does
it give a detailed description of 8086, 186, and 286 instructions . For
information on these topics, you will need other references .
Microsoft Macro Assembler Reference Manual

1 .2 What You Need

This manual is intended to be used with the Microsoft Macro Assem-
bler User's Guide . The guide explains the steps required to create exe-
cutable programs from source files .
0
You also need to know the function and operation of the instructions
in the instruction sets of the 8086/186/286 family of microprocessors .
For an explanation of these instruction sets, you will need to turn to
one of the many books that define these instructions . For your con-
venience, a complete list of the instruction names and syntax for all
processors is given in Appendix A, "Instruction Summary ."

0
 Introduction

1 .3 Notational Conventions
This manual uses the following notational conventions to define the
0 assembly language syntax :

Convention Meaning
Roman Indicates command or parameter
names that must be typed as
shown . In most cases, upper and
lowercase letters can he freely in-
termixed .

Italics Indicates a placeholder, that is, a

name that you must replace with
the value or filename required by
the program .

Ellipses . Indicates that you can

repeat the preceding item any
number of tinies .

Indicates that you can repeat the

preceding item any number of
times as long as you separate the
items with a comma .

H Brackets . Indicate that the en-

closed item is optional . If you do
not use the optional item, the
program selects a default action .

Vertical bar . Indicates that only

one of the separated items can be
used . You must make a choice
between the items .
0
 Chapter 2
Elements of the Assembler

2 .1 Introduction 2-1

2 .2 Character Set 2-1

2 .3 Integers 2-1

2 .4 Real Numbers 2-2

2 .5 Encoded Real Number 2-3

2 .6 Packed Decimal Numbers 2-3

0 2 .7 Character and String Constants 2-4

2 .8 Names 2-5

2 .9 Reserved Names 2-5

2 .10 Statements 2-7

2 .11 Comments 2-7

2 .12 COMMENT Directive 2-8

0
 Elements of the Assembler

0 2 .1 Introduction
All assembly language programs consist of one or more statements and
comments . A statement or comment is a combination of characters,
numbers, and names . Names and numbers are used to identify values
in instruction statements . Characters are used to form the names or
numbers, or to form character constants .

The following sections describe what characters can be used in a pro-

gram and how to form numbers, names, statements, and comments .

2 .2 Character Set
MASM recognizes the following character set :

ABCDEFGHIJKLM-1N0PQRSTUVWXYZ
abcdefghijkImnopgrstuvwxyz
0 0123456789
?@-$ : .f1()<>{}
+-/*&%!'-I\= #' ;,

2 .3 Integers
Syntax

digits
digitsB
digitsQ
digitsO
digitsD
digitsH

An integer represents an integer number . It is a combination of

binary, octal, decimal, or hexadecimal digits and an optional radix .

e The digits are a combination of one or more digits of the specified ra-
dix : B, Q, 0, D, or H . If no radix is given, MASM uses the current de-
fault radix (typically decimal) . The following table lists the digits
that can be used with each radix . (Radix can be either upper or lower-
case .)


Microsoft Macro Assembler Reference Manual

Radix Type Digits

B Binary 01
Q
0
Octal 0123456 0
D Decimal 0123456781)
H I-lexadecimal 0123456789A13CDEF

Hexadecimal numbers must always start with a decimal digit (0-9) .

The hexadecimal digits A through F can be given as either upper or
lower case .

The maximum number of digits in an integer depends on the instruc-

tion or directive in which the integer is used .

You can set the default radix by using the RADIX directive . See the
section, " .RADIX Directive,'' in Chapter 9 .

Examples

01011010B 132Q 5AH 90D 90

01111B 170 OFH 15D 15
0
2 .4 Real Numbers
Syntax

digits .digitsE I +1- ] digits

A real number represents a number having an integer, a fraction,

and an exponent . The digits can be any combination of decimal di-
gits . Digits before the decimal point ( .) represent the integer part,
and those after the point represent the fraction . The digits after the
exponent mark (E) represent the exponent . The exponent is option-
al . If an exponent is given, the plus (+) and minus (-) signs can be
used to indicate its sign .

Real numbers can be used only with the DD, DQ, and DT direc-
tives . The maximum number of digits in the number and the max-
imum range of exponent values depends on the directive .
0


Elements of the Assembler

Examples

e 25 .23 2 .523E1 2523 .0E-2

2 .5 Encoded Real Number

Syntax

digitsR

An encoded real number is an 8, 16, or 20-digit hexadecimal number

that represents a real number in encoded format . An encoded real
number has a sign field, a biased exponent, and a mantissa . These
values are encoded as bit fields within the number . The exact size
and meaning of each bit field depends on the number of bits in the
number . The digits must be hexadecimal digits . The number must
begin with a decimal digit (0-9) .

Encoded real numbers can be used only with the DD, DQ, and DT
0 directives . The maximum number of digits for the encoded numbers
used with DD, DQ, and DT must be 8, 16, and 20 digits, respec-
tively . (If a leading zero is supplied, the number must be 9, 17, or 21
digits .)

Example

3F800000 ; 1 .0 for DD
3FF0000000000000 ; 1 .0 for DQ

2 .6 Packed Decimal Numbers

Syntax

j+ 1-1 digits

A packed decimal number represents a decimal integer that is to be

stored in packed decimal format . Packed decimal storage has a
leading sign byte and 9 value bytes . Each value byte contains two
decimal digits . The high-order bit of the sign byte is 0 for positive
values, and 1 for negative values .


Microsoft Macro Assembler Reference Manual

Packed decimals have the same format as other decimal integers ex-
cept that they can take an optional plus (+) or minus (-) sign and
can be defined only with the DT directive . A packed decimal must
not have more than 18 digits . 0
Examples

1234567890 ;encoded as 00000000001234567890

-1234567890 ;encoded as 80000000001234567890

2 .7 Character and String Constants

Syntax

characters '
characters "

A character constant is a constant composed of a single ASCII char-

acter . A string constant is a constant composed of two or more
ASCII characters . The constant must be enclosed in matching single
quotation or double quotation marks .
0
Single quotation marks must be encoded twice when given in con-
stants that are enclosed by single quotation marks . Similarly, dou-
ble quotation marks must be encoded twice when given in constants
that are enclosed by double quotation marks .

Examples

'a'
'ab'
• a'
• This is a message ."
'Can '' t find the file .'
• Specified '"value"' not found ."

Elements of the Assembler

2 .8 Names
• Syntax

characters . . .

A name is a combination of letters, digits, and special characters

that can be used in instruction statements to labels, variables, and
symbols . Names have the following formatting rules :

1. A name must begin with a letter, an underscore (4, a ques-

tion mark (?), a dollar sign ($), or an at sign (@) .

2. A name can have any combination of upper and lowercase

letters . All lowercase letters are converted to uppercase un-
less the -ML or -MX option is used .

3. A name can have any number of characters, but only the

first 31 characters are used . All other characters are ig-
nored .

0 Examples

subrout3
Array
main

2 .9 Reserved Names
A reserved name is any name that has a special, predefined meaning
to the assembler . Reserved names include instruction and directive
mnemonics, register names, and predefined group and segment
names . These names can be used only as defined and must not be
redefined .

The following is a list of all reserved names except instruction

mnemonics . For a complete list of instruction mnemonics, see Ap-
pendix A, "Instruction Summary ."
is

C) c


Microsoft Macro Assembler Reference Manual

%OUT DQ IFIDN QWORD

.186 DS IFNB RADIX
.286c
.286p
.287
DT
D W
DWORD
IFNDEF
INCLUDE
IRP
RECORD
REPT
SALL
0
.8086 DX IRPC SEG
.8087 ELSE LABEL SEGMENT
END .LALL SFCOND
AH ENDIF LE SHL
AL ENDM LENGTH SHORT
AND ENDP .LFCOND STIR
ASSUME ENDS .LIST SI
AX EQ LOCAL SIZE
BH EQU LOW SP
BL ES LT SS
BP EVEN MACRO STRUC
BX EXITM MASK SUBTTL
BYTE EXTRN MOD TBYTE
CH FAR NAME TFCOND
CL GE NE THIS
COMMENT GROUP NEAR TITLE
.CREF
CS
GT
HIGH
NOT
OFFSET
TYPE
TYPE
Is
CX IF OR WIDTH
DB IF1 ORG WORD
DD IF2 PAGE .XALL
DH IFB PROC .XCREF
DI IFDEF PTR XLIST
DL IFDIF PUBLIC XOR
IFE PURGE

All upper and lowercase combinations of these names are considered

to be the same name . For example, the names "Length" and
"LENGTH" are the same name for the LENGTH operator .

Elements of the Assembler

2 .10 Statements

0 Syntax

[ name] mnemonic ] operands]

A statement is a combination of a name, an instruction or directive

mnemonic, and one or more operands . A statement represents an
action to be taken by the assembler, such as generating a machine
instruction or one or more bytes of data .

Statements have the following formatting rules :

1. A statement can begin in any column .

2. A statement must not be more than 128 characters in length

and must not contain an embedded newline character . This
means continuing a statement on multiple lines is not al-
lowed .

0 3. A statement must be terminated by a newline character .

This includes the last statement in the source file .

Examples

count db 0
mov ax, bx
assume cs : TEXT, ds :DGROUP
main proc far

2 .11 Comments
Syntax

;text

A comment is any combination of characters preceded by a semi-

colon ( ;) and terminated by a newline character . Comments let a
programmer describe the action of a program at the given point .
Comments are otherwise ignored by the assembler and have no ef-
fect on assembly .


Microsoft Macro Assembler Reference Manual

Comments can be placed anywhere in a program, including on the

same line as a statement . The comment must be placed after all
names, mnemonics, and operands have been given . A comment must
not be longer than one line, that is, it must not contain any embed-
0
ded newline characters . For very long comments, the COMMENT
directive can be used .

Examples

This comment is alone on a line .

mov ax, bx ; This comment follows a statement
Comments can contain reserved words like PUBLIC .

2 .12 COMMENT Directive

Syntax

COMMENT delim text delim

The COMMENT directive causes MASM to treat all text between

the given pair of delimiters (delim) as a comment . The delimiter
0
character must be the first non-blank character after the COM-
MENT keyword . The text is all remaining characters up to the next
occurrence of the delimiter . The text must not contain the delimiter .

The COMMENT directive is typically used for multiple line com-

ments . Although text can appear on the same line as the last delim-
iter, any text after the delimiter is ignored .

Example

comment *
This comment continues until the
next asterisk .

comment +
The assembler ignores the
following MOV statement
+ mov ax, 1
0
0Q
Chapter 3
Program Structure

3 .1 Introduction 3-1

3 .2 Source Files 3-1

3 .3 Instruction Set Directives 3-3

3 .4 SEGMENT and ENDS Directives 3-4

3 .5 END Directive 3-8

3 .6 GROUP Directive 3-9

3 .7 ASSUME Directive 3-10

3 .8 ORG Directive 3-11

3 .9 EVEN Directive 3-12

3 .10 PROC and ENDP Directives 3-12

S

Program Structure

3 .1 Introduction
The Program Structure directives let a programmer define the organi-
zation that a program's code and data will have when loaded into
memory .

There are the following Program Structure directives :

SEGMENT Segment Definition

ENDS Segment End
END Source File End
GROUP Segment Groups
ASSUME Segment Registers
ORG Segment Origin
EVEN Segment Alignment
PROC Procedure Definition
ENDP Procedure End

0 The following sections describe these directives in detail . They also

describe the Instruction Set directives that define which instruction
set is to be used during assembly .

3 .2 Source Files
Every assembly language program consists of one or more source files .
A source file is simply a text file that contains statements that define
the program's data and instructions . MASM reads source files and as-
sembles the statements to create "object modules" that can be
prepared for execution by the system linker .

All source files have the same form -- zero or more program "seg-
ments" followed by an END statement . The END statement, re-
quired in every source file, signals the end of the source file . It also pro-
vides a way to define the program entry point or starting address (if
any) . All other statements in a source file are optional .

The following example illustrates the source file format . It is a com-

plete assembly language program that uses MS-DOS system calls to
print the message "Hello .'' on the system display .


Microsoft Macro Assembler Reference Manual

.8086

DATA segment
STRING db
DATA ends
'Hello . •, 13, 10, '$'
; Program Data Segment
0
CODE segment Program Code Segment
assume cs :CODE, ds :DATA
START : Program Entry Point
mov ax, seg DATA
mov ds, ax
mov dx, offset STRING
mov ah, 9
int 21h
mov ah, 4ch
1nt 21h
CODE ends

STACK segment stack Program Stack Segment

assume ss :STACK
dw 64 dup(?)
STACK ends
0
end START

The main features of this source file are :

1. The .8086 directive, enabling the 8086 instruction set for as-
sembly

2. The SEGMENT and ENDS statements, defining segments

named DATA, CODE, and STACK

3. The variable STRING in the DATA segment, defining the

string to be displayed

4. The instruction label START in the CODE segment, mark-

ing the start of the program instructions

5. The DW statement in the STACK segment, defining the

uninitialized data space to be used for the program stack 0


Program Structure

6. The ASSUME statements in the DATA, CODE, and STACK

segments, defining which segment registers will be associat-

0 ed with the labels, variables, and symbols defined within the

segments

7. The END statement, defining START as the program entry

point

3 .3 Instruction Set Directives

Syntax

.8086
.8087
.186
.286c
.286p
.287

The instruction set directives enable/disable the instruction sets for

0 the given microprocessors . When a directive is given, MASM will
recognize and assemble any subsequent instructions belonging to
that microprocessor . The instruction set directives, if used, should
be placed at the beginning of the program source file . This ensures
that all instructions in the file are assembled using the same set .

The .8086 directive enables assembly of instructions for the 8086 mi-
croprocessor . It also disables assembly of 186 and 286 instructions .
Similarly, the .8087 directive enables assembly of instructions for
the 8087 floating point coprocessor and disables assembly of 287 in-
structions . Since MASM assembles 8086 and 8087 instructions by
default, the .8086 and .8087 directives are not required if the source
files contain 8086 and 8087 instructions only .

The .186 directive enables assembly of instructions for the 186 mi-
croprocessor . This directive should be used for programs that will
be executed by an 186 microprocessor .

The .286c directive enables assembly of non-protected instructions

for the 286 microprocessor . (These are identical to the 186 instruc-
tions) . The .286p directive enables assembly of the protected in-
structions of the 286 . The .286c directive should be used with pro-
grams that will be executed by a 286 microprocessor but do not ac-
Microsoft Macro Assembler Reference Manual

cess the 286's protected instructions . The .286p directive can be

used with programs that will be executed by a 286 .

The .287 directive enables assembly of instructions for the 287 float-
ing point coprocessor . This directive should be used with programs
0
that have floating point instructions and will be executed by a 286
microprocessor .

Even though a source file may contain the .8087 or .287 directive,
MASM also requires the /r or /e option in the MASM command line
to define how to assemble floating point instructions . The /r option
directs the assembler to generate the actual instruction code for the
floating point instruction . The /e option directs it to generate a
software interrupt code to a floating point emulator routine .

3 .4 SEGMENT and ENDS Directives

Syntax

name SEGMENT align combine 'class'

name ENDS 0
The SEGMENT and ENDS directives mark the beginning and end of
a program segment . A program segment is a collection of instruc-
tions and/or data whose addresses are all relative to the same seg-
ment register .

The name defines the name of the segment . This name can be
unique or be the same name given to other segments in the program .
Segments with identical names are treated as the same segment .

The optional align, combine, and class define program loading in-
structions that are to be used by the linker when forming the exe-
cutable program . These options are described later .

Segments can be nested . When MASM encounters a nested segment,

it temporarily suspends assembly of the enclosing segment, and be-
gins assembly of the nested segment . When the nested segment has
been assembled, MASM continues assembly of the enclosing seg-
ment . Overlapping segments are not permitted . 0
3-4


Program Structure

Example

0 SAMPLE_ TEXT segment word public 'CODE'

main proc far

CONST segment word public 'CONST' ; nested segment

segi dw ARRAY DATA
CONST ends ; end nesting

mov es, segl

push es
mov ax, es :pointer
push ax
call _printf
add sp, 4

0 rot
_ main endp
SAMPLE TEXT ends

This example contains two segments : "SAMPLE TEXT" and

"CONST" . The "CONST" segment is nested within the
"SAMPLE TEXT" segment .

Note

Although a given segment name can be used more than once in a

source file, each segment definition using that name must have
either exactly the same attributes, or attributes that do not con-
flict .
Microsoft Macro Assembler Reference Manual

Program Loading Options

The optional align defines the alignment of the given segment . The
alignment defines the range of memory addresses from which a
starting address for the segment can be selected . It can be any one
0
of the following :

BYTE use any byte address

WORD use any word address (2 bytes/word)
PARA use paragraph addresses (16 bytes/paragraph)
PAGE use page addresses (1024 bytes/page)

If no align is given, PARA is used by default . The actual start ad-

dress is computed when the program is loaded, and the linker
guarantees that the address will be on the given boundary .

The optional combine defines how to combine segments having the

same name . It can be any one of the following :

PUBLIC
Concatenates all segments having the same name
and forms a single, contiguous segment . All in-
struction and data addresses in the new segment
0
are relative to a single segment register, and all
offsets are adjusted to represent the distance
from the beginning of the new segment .

STACK
Concatenates all segments having the same name
and forms a single, contiguous segment . All ad-
dresses in the new segment are relative to the SS
segment register . The Stack Pointer (SP) regis-
ter is set to an address in the segment .

COMMON
Creates overlapping segments by placing the
start of all segments having the same name at
the same address . The length of the resulting
area is the length of the longest segment . All ad-
dresses in the segments are relative to the same
base address . 0
 Program Structure

MEMORY
Places all segments having the same name in the

0 highest physical segment in memory . If more

than one MEMORY segment is given, the seg-
ments are overlapped as with COMMON seg-
ments .

AT address
Causes all label and variable addresses defined in
the segment to be relative to the given address .
The address can be any valid expression, but
must not contain a forward reference, that is, a
reference to a symbol defined later in the source
f ile . A T segments typically contain no code or
initialized data . Instead, they represent address
templates that can be placed over code or data
already in memory, such as code and data found
in ROM devices . The labels and variables in the
AT segments can then be used to access the fixed
instructions and data .

0 If no combine is given, the segment is not combined . Instead, it re-

ceives its own physical segment when loaded into memory .

Note

The linker requires at least one stack segment in a program .

The optional class defines which segments are to be loaded in con-

tiguous memory . Segments having the same class name are loaded
into memory one after another . All segments of a given class are
loaded before segments of any other class . The class name must be
enclosed in single quotation marks .


Microsoft Macro Assembler Reference Manual

Example

_TEXT
assume cs : TEXT
segment word public 'CODE' 0
TEXT ends

This example illustrates the general form of a text segment for a

small module program . The segment name is "TEXT" . The seg-
ment alignment and combine type are "word" and "public," respec-
tively . The class is "CODE ."

3.5 END Directive

Syntax

END expression

The END directive marks the end of the module . The assembler ig-
nores any statements following this directive .
0
The optional expression defines the program entry point . The entry
point defines the address at which program execution is to start . If
the program has more than one module, only one of these modules
can define an entry point . The module with the entry point is called
the "main module ." If no entry point is given, none is assumed .

Examples

end
end main

0
_~L A
 Program Structure

3 .6 GROUP Directive

0 Syntax

name GROUP seg-name,,,

The GROUP directive associates a group name with one or more seg-
ments, and causes all labels and variables defined in the given seg-
ments to have addresses that are relative to the beginning of the
group instead of to the beginning of the segments in which they are
defined . The seg-name must be the name of a segment defined using
the SEGMENT directive, or a SEG expression . The name must be
unique .

The GROUP directive does not affect the order in which segments of
a group are loaded . Loading order depends on each segment's class,
or on the order the object modules are given to the linker .

Segments in a group do not have to be contiguous . This means that

segments that do not belong to the group can be loaded between seg-
ments that do . The only restriction is that the distance (in bytes)
0 between the first byte in the first segment of the group and the last
byte in the last segment must not exceed 65,535 . If the segments of
a group are contiguous, the group can occupy up to 64 Kbytes of
memory .

Group names can be used with the ASSUME directive and as an

operand prefix with the segment override operator ( :) .

Note

A group name must not be used in more than one GROUP direc-
tive in any source file . If several segments within the source file
belong to the same group, all segment names must be given in
the same GROUP directive .

q- 0


Microsoft Macro Assembler Reference Manual

Example

DGROUF group
assume
_DATA, _BSS
ds :DGROUP 0
DATA segment word public 'DATA'

_DATA ends
_BSS segment word public 'BSS'

BSS ends
end

3 .7 ASSUME Directive
Syntax 0
ASSUME seg-reg : seg-name ,,,
ASSUME NOTHING

The ASSUME directive selects the given segment register seg-reg to

be the default segment register for all labels and variables defined in
the segment or group given by seg-name . Subsequent references to
the label or variable will automatically assume the selected register
when the effective address is computed .

The ASSUME dire,tive can define up to 4 selections : one selection

for each of the four segment registers . The seg-reg can be any one of
the segment register names : CS, DS, ES, or SS . The seg-name must
be one of the following :

The name of a segment previously defined with the SEG-

MENT directive .

The name of a group previously defined with the GROUP

directive .
0
The keyword NOTHING .


Program Structure

The keyword NOTHING cancels the current segment selection . The

5 directive "ASSUME NOTHING" cancels all register selections made

by a previous ASSUME statement .

Note
The segment override operator ( :) can be used to override the
current segment register selected by the ASSUME directive .

Examples

assume cs :code
assume cs :cgroup,ds :dgroup,ss :nothing,es :nothing
assume nothing

• 3 .8 ORG Directive
Syntax

ORG expression

The ORG directive sets the location counter to expression . Subse-

quent instruction and data addresses begin at the new value .

The expression must resolve to an absolute number, i .e ., all symbols

used in the expression must be known on the first pass of the assem-
bler . The location counter symbol ($) can also be used .

Examples

org 120H
org $+ 2


Microsoft Macro Assembler Reference Manual

3 .9 EVEN Directive
Syntax

EVEN
0
The EVEN directive aligns the next data or instruction byte on a
word boundary . If the current value of the location counter is odd,
the directive increments the location counter to an even value and
generates one NOP instruction (90h) . If the location counter is al-
ready even, the directive is ignored .

The EVEN directive must not be used in byte-aligned segments .

Example

org 0
testl db 1
even
test2 dw 513

In this example, EVEN increments the location counter and gen-

erates a NOP instruction (90h) . This means the offset of "test2'' is
2, not 1 .

3 .10 PROC and ENDP Directives

Syntax

name PROC type

statements
name ENDP

The PROC and ENDP directives mark the beginning and end of a
procedure . A procedure is a block of instructions that form a pro-
gram subroutine . Every procedure has a name with which it can be
called .

The name must be a unique name, not previously defined in the pro-
gram . The optional type can be either NEAR or FAR . NEAR is as-
sumed if no type is given . The name has the same attributes as a la-
0
bel and can be used as an operand in a jump, call, or loop instruc-
tion .


Program Structure

Any number of statements can appear between the PROC and

ENDP statements . The procedure should contain at least one ret
statement to return control to the point of call . Nested procedures
are allowed .

Example

main proc near

push by
mov bp, sp
push si
push di
mov ax, offset string
push ax
call _printf
add sp, 2
pop di
pop si
mov sp, by
pop by
• - ret
main endp

9 19
S

Chapter 4
Types and Declarations

4 .1 Introduction 4-1

4 .2 Label Declarations 4-1

4 .2 .1 Near Label Declarations 4-1
4 .2 .2 Procedure Labels 4-2

4 .3 Data Declarations 4-2

4 .3 .1 DB Directive 4-3
4 .3 .2 DW Directive 4-3
4 .3 .3 DD Directive 4-4
4 .3 .4 DQ Directive 4-5
0 4 .3 .5
4 .3 .6
DT Directive 4-6
DUP Operator 4-7

4 .4 Symbol Declarations 4-8

4 .4 .1 = Directive 4-8
4 .4 .2 EQU Directive 4-9
4 .4 .3 LABEL Directive 4-10

4 .5 Type Declarations 4-11

4 .5 .1 STRUC and ENDS Directives 4-11
4 .5 .2 RECORD Directive 4-12

4 .6 Structure and Record Declarations 4-13

4 .6 .1 Structure Declarations 4-14
4 .6 .2 Record Declarations 4-15
S

Types and Declarations

0 4 .1 Introduction
This chapter explains how to generate data for a program, how to de-
clare labels, variables, and other symbols that refer to instruction and
data locations, and how to define types that can be used to generate
data blocks that contain multiple fields, such as structures and
records .

4 .2 Label Declarations
Label declarations create ''labels ." A label is simply a name that
represents the address of a given instruction . Labels can be used in
JMP, CALL, and other execution control instructions to direct pro-
gram execution to the associated instruction .

4 .2 .1 Near Label Declarations

0 name :

A near label declaration creates an instruction label that has NEAR

type . The label can be used in subsequent instructions in the same seg-
ment to pass execution control to the corresponding instruction .

The name must be unique and not previously defined . Furthermore,

the segment containing the declaration must be associated with the
CS segment register (see the ASSUME directive) . The assembler sets
the name to the current value of the location counter .

A near label declaration can appear on a line by itself or on a line with

an instruction as long as it immediately precedes the instruction .

Examples

start :
loop : inc 4 [bp]


Microsoft Macro Assembler Reference Manual

4 .2 .2 Procedure Labels

Syntax

name PROC [NEAR FAR I

The PROC directive creates a label name and sets its type to NEAR
or FAR . The label then represents the address of the following in-
struction and can be used in JMP, CALL, or LOOP instruction to
direct execution control to the given instruction .

When the PROC label definition is encountered, the assembler sets

the label's value to the value of the current location counter and sets
its type to NEAR or FAR. If the label has FAR type, the assembler
also sets its segment value to that of the enclosing segment .

NEAR labels can be used with JMP, CALL, and LOOP instruction
in the enclosing segment only . FAR labels can be used in any seg-
ment of the program .

4 .3 Data Declarations

The Data Declaration directives let a programmer generate data for

0
a program . The directives translate numbers, strings, and expres-
sions into individual bytes, words, or other units of data . The encod-
ed data is copied to the program object file .

There are the following data declaration directives :

DB Data Byte
DW Data Word
DD Data Doubleword
DQ Data Quadword
DT Data Ten-byte Word

The following sections describe these directives in detail .

0
 Types and Declarations

4 .3 .1 DB Directive

0 Syntax

(name DB initial-value

The DB directive allocates and initializes a byte (8 bits) of storage

for each given initial-value . The initial-value can be an integer, a
character string constant, a DUP operator, a constant expression, or
question mark (?) . The question mark (?) represents an undefined
initial value . If two or more initial values are given, they must be
separated by commas (,) .

The name is optional . If a name is given, the directive creates a

variable of type BYTE whose offset value is the current location
counter value .

A string constant can have any number of characters as long as it

fits on a single line . When the string is encoded, the characters are
stored in the order given, with the first character in the constant at
the lowest address and the last at the highest .
0 Examples

integer db 16
string db 'ab'
message db "Enter your name : "
constantexp db 4 * 3
empty db ?
multiple db 1, 2, 3,
duplicate db 10 dup(?)
high byte db 255

4 .3 .2 DW Directive

Syntax

[name DW initial-value,,,

The DW directive allocates and initializes a word (2 bytes) of

storage for each given initial-value . An initial-value can be an in-
teger, a string constant, a DUP operator, a constant expression, an
Microsoft Macro Assembler Reference Manual

address expression, or a question mark (?) . The question mark (?)

represents an undefined initial value . If two or more expressions are
given, they must be separated by commas (,) .

The name is optional . If a name is given, the directive creates a

variable of type WORD whose offset value is the current location
counter value .

String constants must not exceed two characters in length . The last
(or only) character in the string is placed in the low-order byte, and
either zero or the first character is placed in the high-order byte .

Examples

integer dw 16728
character dw 'a'
string dw 'bc'
constantexp dw 4 * 3
addressexp dw string
empty dw ?
multiple dw 1, 2, 3, '$'
duplicate
high_word
arrayptr
dw
dw
dw
10 dup(?)
65535
array
0
arrayptr2 dw offset DGROUP :array

4 .3 .3 DD Directive

Syntax

[name] DD initial-value

The DD directive allocates and initializes a doubleword (4 bytes) of

storage for each given initial-value . An initial-value can be an in-
teger, a real number, a 1- or 2-character string constant, an encoded
real number, a DUP operation, a constant expression, an address ex-
pression, or a question mark (?) . The question mark (?) represents
an undefined initial value . If two or more expressions are given,
they must be separated by commas (,) .
The name is optional . If a name is given, the directive creates a
0
variable of type DWORD whose offset value is the current location
counter value .
 Types and Declarations

String constants must not exceed two characters in length . The last
(or only) character in the string is placed in the low-order byte, and
the first character (if there are two in the string) is placed in the
0 next byte . Zeroes are placed in all remaining bytes .

Examples

integer dd 16728
character dd a'
string dd 'bc'
real dd 1 .5
encodedreal dd 3f000000R
constantexp dd 4 * 3
addsegexp dd real
empty dd ?
multiple dd 1, 2, 3,
duplicate dd 10 dup(?)
high_dcuble dd 4294967295

4 .3 .4 DQ Directive

Syntax

[name] DQ initial-value

The DQ directive allocates and initializes a quadword (8 bytes) of

storage for each given initial-value . An initial-value can be an in-
teger, a real number, a 1- or 2-character string constant, an encoded
real number, a DUP operator, a constant expression, or a question
mark (?) . The question mark (?) represents an undefined initial
value . If two or more expressions are given, they must be separated
by commas (,) .

The name is optional . If a name is given, the directive creates a

variable of type QWORD whose offset value is the current location
counter value .
String constants must not exceed two characters in length . The last
(or only) character in the string is placed in the low-order byte, and
the first character (if there are two in the string) is placed in the
next byte . Zeroes are placed in all remaining bytes .
Microsoft Macro Assembler Reference Manual

Examples

integer
character
string
dq
dq
dq
16728
a'
'bc'
0
real dq 1 .5
encodedreal dq 3f00000000000000R
constantexp dq 4 * 3
empty dq ?
multiple dq 1, 2, 3, '$'
duplicate dq 10 dup(?)
high_ quad dq 18446744073709551615

4 .3 .5 DT Directive

Syntax

[name] DT initial-value

The DT directive allocates and initializes 10 bytes of storage for

each given initial-value . An initial-value can be an integer expres-
sion, a packed decimal, a 1- or 2-character string constant, an encod-
0
ed real number, a DU[ operator, or a question mark (?) . The ques-
tion mark (?) represents an undefined initial value . If two or more
expressions are given, they must be separated by commas (,) .

The name is optional . If a name is given, the directive creates a

variable of type TBYTE whose offset value is the current location
counter value .

String constants must not exceed two characters in length . The last
(or only) character in the string is placed in the low-order byte, and
the first character (if there are two in the string) is placed in the
next byte . Zeroes are placed in all remaining bytes .

Note

The DT directive assumes that constants with decimal digits are

packed decimals, not integers .
0


Types and Declarations

Examples

0 packeddecimaldt
integer
character
dt
dt
1234567890
16728D
'a'
string dt 'bc'
real dt 1 .5
encodedreal dt 3f00000000000000000OR
empty dt v

multiple dt 1 2 3 $.
duplicate dt 10 dup(?)
high_tbyte dt 1208925819614629174706175D

4 .3 .8 DUP Operator

Syntax

count DUP( initial-value,,, )

0 The Dt'P operator is a special operator that can be used with the
Data Declaration and other directives to specify multiple oc-
currences of one or more initial values . The count defines the
number of times to repeat the initial-value . An initial value can be
any expression that evalutes to an integer value, a character con-
stant, or another DUP operator . If more than one initial value is
given, the values must be separated by commas () . DUP operators
can be nested up to 17 levels .

Examples

DB 100 DUP (1)

This example generates 100 bytes with value 1 .

DW 20 DUP( 1,2,3,4 )

This example generates 80 words of data . The first four words have
the values 1, 2, 3, and 4, respectively . This pattern is duplicated for
the remaining words .


Microsoft Macro Assembler Reference Manual

DB 5 DUP( 5 DUP( 5 DUP (1)))

This example generates 125 bytes of data, each byte having the
value 1 . 0
DD 14 DUP (? )

This example generates 14 doublewords of uninitialized data .

4 .4 Symbol Declarations
The Symbol Declaration directives let a programmer create and use
symbols . A symbol is a descriptive name that represents a number,
text, an instruction, or an address . Symbols make programs easier to
read and maintain by letting descriptive names represent values . A
symbol can be used anywhere its corresponding value is allowed .

There are the following Symbol Declaration directives :

Assign Absolutes
EQU Equate Absolutes, Aliases, or Text Symbols
LABEL Instruction or Data Labels

The following sections describe the directives in detail .

4 .4 .1 = Directive

Syntax

name = expression

The = directive creates an absolute symbol by assigning the numer-

ic value of expression to name . An absolute symbol is simply a name
that represents a 16-bit value . No storage is allocated for the
number . Instead, the assembler replaces each subsequent occurrence
of the name with the value of the given expression .

The expression can be an integer, a 1- or 2-character string constant,

a constant expression, or an address expression . Its value must not
exceed 65,535 . The name must be either a unique name, or a name
that was previously defined using the = directive .
40
 Types and Declarations

Absolute symbols can be redefined at any time .

Examples
0
integer 16728
'ab'
string
constantexp 3 * 4
addressexp string

4 .4 .2 EQU Directive

Syntax

name EQU expression

The EQU directive creates absolute symbols, aliases, or text symbols

by assigning the expression to the given name . An absolute symbol
is a name that represents a 16-bit value, an alias is a name that
represents another symbol, and a text symbol is a name that
represents a character string or other combination of characters .
0 The assembler replaces each subsequent occurrence of the name with
either the text or the value of the expression, depending on the type
of expression given .

The name must be a unique name, not previously defined . The ex-
pression can be an integer, a string constant, a real number, an en-
coded real number, an instruction mnemonic, a constant expression,
or an address expression . Expressions that evaluate to integer
values in the range 0 to 65,535 create absolute symbols and cause
the assembler to replace the name with a value . All other expres-
sions cause the assembler to replace the name with text .

The EQU directive is sometimes used to create simple macros . Note

that the assembler replaces a name with text before attempting to
assemble the statement containing the name .

Symbols defined using EQU directive cannot be redefined .



Microsoft Macro Assembler Reference Manual

Examples

integer
real
constantexp
equ
equ
equ
16728
3 .14159
3 * 4
;
;
;
replaced with value
replaced with text
replaced with value
0
memoryop equ [bpl ;replaced with text
mnemonic equ mov ; replaced with text
addressexp equ real replaced with text
string equ 'Type Enter' replaced with text

4 .4 .3 LABEL Directive

Syntax

name LABEL type

The LABEL directive creates a new variable or label by assigning

the current location counter value and the given type to name .

The name must be unique and not previously defined . The type can
be any one of the following :

BYTE
WORD
DWORD
QWORD
TBYTE
NEAR
FAR

The type can also be the name of a valid structure type .

Examples

subroutine label far

barray label byte


Types and Declarations

4 .5 Type Declarations

0 The Type Declaration directives let a programmer define data types

that can be used to create program variables that consist of multiple
elements or fields . The directives associate one or more named fields
with a given type name . The type name can then be used in a data
declaration to create a variable of the given type .

There are the following Type Declaration directives

STRUC and ENDS Structure Types

RECORD Record Types

The following sections describe the directives in detail .

4 .5 .1 STRUC and ENDS Directives

Syntax

name STRUC

0 field-definitions
name ENDS

The STRUC and ENDS directives mark the beginning and end of a
type definition for a structure . Structure type definitions define the
name of a structure type and the number, type, and default value of
the fields contained in the type . Once defined, structure types may
be used to declare structure variables .

The name defines the new name of the structure type . It must be
unique . The field-definitions define the structure's fields . Any
number of field definitions can be given . The definitions must have
the form

[name] DB default-value,,,
[name] DW default-value,,,
[name] DD default-value,,,
[name] DQ default-value,,,
[name] DT default-value,,,

The optional name defines the field name, the DB, DW, DD, DQ,
and DT directives define the size of each field, and default-value de-
Microsoft Macro Assembler Reference Manual

fines the value to be given to the field if no initial value is given

when the structure variable is declared . The name must be unique,
and once defined, represents the offset from the beginning of the
structure to the corresponding field . The default-value can define a
number, character or string constant, or symbol . It may also con-
0
tain the DUP operator to define multiple values for the field . If the
default-value is a string constant, the field has the same number of
bytes as characters in the string . If multiple default values are
given, they must be separated by commas .

A structure type definition can contain field definitions and com-

ments only . It must not contain any other statements . This means
structures cannot be nested .

Example

table strut
count db 10
value dw 10 DUP(?)
name db 'font3'
table ends

In this example, the fields are ''count", "value", and ''name'' . The
"count" field is a single byte value initialized to 10 ; "value" is an
is
array of 10 uninitialized word values ; and "name" is a character ar-
ray of 5 bytes initialized to ''font3 ." The field names ''count,"
"value," and "name" have the offset values 0, 1, and 21, respective-
ly .

4 .5 .2 RECORD Directive

Syntax

recordname RECORD fieldname :width(=expl ,,,

The RECORD directive defines a record type for an 8- or 16-bit

record that contains one or more fields . The recordname is the name
of the record type to be used when creating the record, fieldname is
the name of a field in the record, width is the number of bits in the
field, and exp is the initial (or default) value for the field . Any
number of field: width= ezp combinations can be given with the
record as long as each is separated from the preceding with a comma
(,) . The sum of the widths for all fields must not exceed 16 .


Types and Declarations

The width must be a constant in the range 1 to 16 . If the total width

of all declared fields is larger than 8 bits, then the assembler uses 2

0 bytes . Otherwise, only 1 byte is used .

If =exp is given, it defines the initial value for the field . If the field
is at least 7 bits wide, you can use an ASCII character for exp . The
exp must not contain a forward reference to any symbol .

In all cases, the first field you declare goes into the most significant
bits of the record . Successively declared fields are placed in the
succeeding bits to the right . If the fields you declare do not total ex-
actly 8 bits or exactly 16 bits, the entire record is shifted right so
that the last bit of the last field is the lowest bit of the record .
Unused bits will be in the high end of the record .

Examples

encode RECORD h1gh :4, mid :3, low :3

This example creates a record type "encode'' having three fields :

''high," "mid," and "low ." The record occupies 16 bits of memory .
The "high" field is in bits 6 to 9, ''mid" in bits 3 to 5, and "low'' in
bits 0 to 2 . The remaining high-order bits are unused .

Item RECORD char :7='Q', weight :4=2

This example creates a record type "item" having two fields : "char"
and "weight ." These values are initialized to the letter Q and the
number 2, respectively .

4.6 Structure and Record Declarations

Structure and record declarations let a programmer generate a block
of data bytes that have many elements or fields . A structure or
record declaration consists of a previously-defined structure or
record type name and a set of initial values .

The following sections describe these declarations in detail .



Microsoft Macro Assembler Reference Manual

4 .6 .1 Structure Declarations

Syntax

[name[ struename < [initial-value] .,, >

0
A structure variable is a variable that has one or more fields of dif-
ferent sizes . The name is the name of the variable, struename is the
name of a structure type that has been created using the STRUC
directive, and initial-value is one or more values defining the initial
value of the structure . One initial-value can be given for each field
in the structure .
The name is optional . If not given, MASM allocates space for the
structure, but does not create a name that you can use to access the
structure .
The initial-value can be an integer, string constant, or expression
that evaluates to a value having the same type as the corresponding
field . The angle brackets (< >) are required even if no initial value
is given . If more than one initial value is given, the values must be
separated with commas . If the DUP operator is used, only the values
within the parentheses need to be enclosed in angle brackets . You
do not have to initialize all fields in a structure . If an initial value is
0
left blank, MASM automatically uses the default initial value of the
field . This is defined by the structure type . If there is no default
value, the field is uninitialized .

Note
You cannot initialize any structure field that has multiple
values if this field was given a default initial value when the
structure was defined .

Examples

structi table <>

This example creates a structure variable named "structi" whose

type is given by the structure type "table .'' The initial values of the
fields in the structure are set to the default values for the structure
type, if any .


Types and Declarations

struct2 table <0,,>

0 T his example creates a structure variable named "struct2 ." Its type
is also "table .'' The initial value for the first field is set to zero . The
default values defined by the structure type are used for the remain-
ing two fields .

struct3 table 10 DUP(<0,, >)

This example creates a variable "struct3" containing 10 structures

of the type "table ." The first field in each structure is set to the ini-
tial value zero . All remaining fields receive the default values .

4 .8 .2 Record Declarations

Syntax

[name] recordname < [initial-value,,, >

A record variable is an 8- or 16-bit value whose bits are divided into

0 one or more fields . The name is the name of the variable, record-
name is the name of a record type that has been created using the
RECORD directive, and initial-value is one or more values defining
the initial value of the record . One initial-value can be given for
each field in the record .

The name is optional . If not given, MASM allocates space for the
record, but does not create a variable that you can use to access the
record .

The initial-value can be an integer, string constant, or any expres-

sion that evaluates to a value that is no larger than can be
represented in the specified field width . Angle brackets (< >) are
required even if no initial value is given . If more than one initial
value is given, the values must be separated with commas . If the
DUP operator is used, only the values within the parentheses need
to be enclosed in angle brackets . You do not have to initialize all
fields in a record . If an initial value is left blank, MASM automati-
cally uses the default initial value of the field . This is defined by the
record type . If there is no default value, the field is uninitialized .


Microsoft Macro Assembler Reference Manual

Examples

reel encode <>

This example creates a record variable named "red" whose type is

0
given by the record type "encode ." The initial values of the fields in
the record are set to the default values for the record type, if any .

table item 10 DUP(<'A',2>)

This example creates a variable ''table'' containing 10 records of the

record type "item ." The fields in these records are all set to the ini-
tial values A and 2 .

passkey encode <,,7>

This example creates a record variable named "passkey ." Its type is
"encode .'' The initial values for the first two fields are the default
values defined by the record type . The initial value for the third
field is 7 .

0
 Chapter 5
Operands and Expressions

5 .1 Introduction 5-1

5 .2 Operands 5-1
5 .2 .1 Constant Operands 5-2
5 .2 .2 Direct Memory Operands 5-2
5 .2 .3 Relocatable Operands 5-3
5 .2 .4 Location Counter 5-3
5 .2 .5 Register Operands 5-4
5 .2 .6 Based Operands 5-5
5 .2 .7 Indexed Operands 5-6
5 .2 .8 Based Indexed Operands 5-7
0 5 .2 .9 Structure Operands 5-8
5 .2 .10 Record Operands 5-9
5 .2 .11 Record Field Operands 5-9

5.3 Expressions 5-10

5 .3.1 Arithmetic Operators 5-10
5 .3.2 SHR and SILL Operators 5-11
5 .3.3 Relational Operators 5-12
5 .3.4 Bitwise Operators 5-13
5 .3.5 Index Operator 5-13
5 .3 .6 PTR Operator 5-14
5 .3.7 Segment Override Operator 5-15
5 .3.8 SHORT Operator 5-16
5 .3.9 THIS Operator 5-16
5 .3.10 HIGH and LOW Operators 5-17
5 .3.11 SEC Operator 5-17
5 .3 .12 OFFSET Operator 5-18
5 .3 .13 TYPE Operator 5-18
5 .3 .14 TYPE Operator 5-19
5 .3 .15 LENGTH Operator 5-20
 5 .3 .16 SIZE Operator 5-20
5 .3 .17 WIDTH Operator 5-21
5 .3 .18 MASK Operator 5-22
0
5 .3 .19 Expression Evaluation and
Precedence 5-22

5 .4 Forward References 5-23

5 .5 Strong Typing for Memory Operands 5-26

0
 Operands and Expressions

0 5 .1 Introduction
This chapter describes the syntax and meaning of operands and ex-
pressions used in assembly language statements and directives .
Operands represent values, registers, or memory locations to be acted
on by instructions or directives . Expressions are combinations of
operands and arithmetic, logical, bitwise, and attribute operators . An
expression evaluates to a value or memory location to be acted on by
an instruction or directive .

5 .2 Operands
An operand is a constant, label, variable, or other symbol that is used
in an instruction or directive to represent a value, register, or memory
location to be acted on .

0 There are the following operand types :

Constant
Direct Memory
Relocatable
Location Counter
Register
Based
Indexed
Based Indexed
Structure
Record
Record Field


Microsoft Macro Assembler Reference Manual

5 .2 .1 Constant Operands

Syntax

number string expression

I I
0
An constant operand is a number, string constant, symbol, or expres-
sion that evaluates to a fixed value . Constant operands, unlike other
operands, represent values to be acted on rather than memory ad-
dresses .

Examples

mov ax, 9
mov al, 'c'
mov bx, 65535/3
mov cx, count

5 .2 .2 Direct Memory Operands

Syntax is
segment : offset

A direct memory operand is a pair of segment and offset values that

represent the absolute memory address of one or more bytes of
memory . The segment can be a segment register name (CS, DS, SS,
or ES), a segment name, or a group name . The offset must be an in-
teger, absolute symbol, or expression that evaluates to a value
within the range 0 to 65,535 .

Examples

mov dx, ss :0031H

mov bx, DATA :O
mov cx, DGROUP :block

Operands and Expressions

5 .2 .3 Relocatable Operands

• Syntax

symbol

A relocatable operand is any symbol that represents the memory ad-

dress (segment and offset) of an instruction or data to be acted on .
Relocatable operands, unlike direct memory operands, are relative
to the start of the segment or group in which the symbol is defined
and have no explicit value until the program has been linked .

Examples

call main
mov bx, local
mov bx, offset DGROUP :table

5 .2 .4 Location Counter

The location counter is a special operand that, during assembly,

represents the current location within the current segment . The lo-
cation counter has the same attributes as a near label . It represents
an instruction address that is relative to the current segment . Its
offset is equal to the number of bytes that have been generated for
that segment to that point . After each statement in the segment
has been assembled, the assembler increments the offset by the
number of bytes generated .

Example

target equ $
mov ax, 1

imp target


Microsoft Macro Assembler Reference Manual

5 .2 .5 Register Operands

Syntax

reg-name

A register operand is the name of a CPU register . Register operands

direct instructions to carry out actions on the contents of the given
registers . The reg-name can be any one of the following :

ax ah al bx bh bl
ex ch cl dx dh dl
cs ds ss es sp by
di si

Any combination of upper and lower case letters is allowed .

The ax, bx, cx, and dx registers are 16-bit general purpose regis-
ters . They can be used for any data or numeric manipulation . The
ah, bh, ch, dh registers represent the high 8-bits of the correspond-
ing general purpose registers . Similarly, al, bl, cl, and dl represent
the low-order 8-bits of the general purpose registers .

The cs, ds, ss, and es registers are the segment registers . They con-
tain the current segment address of the code, data, stack, and extra
segments, respectively . All instruction and data addresses are rela-
tive to the segment address in one of these registers .

The sp register is the 16-bit stack pointer register . The stack

pointer contains the current top of stack address . This address is
relative to the segment address in the ss register and is automatical-
ly modified by instructions that access the stack .

The bx, bp, di, and si registers are 16-bit base and index registers .
These are general purpose registers that are typically used for
pointers to program data .

The 16-bit flag register contains nine 1-bit flags whose positions and
meaning are defined in the following table :

0
5-4
 Operands and Expressions

Flag Bit Meaning

0 carry flag
0 2
4
5
parity flag
auxiliary flag
trap flag
6 zero flag
7 sign flag
9 interrupt-enable flag
10 direction flag
11 overflow flag

Although no name exists for the 16-bit flag register, the contents of
the register can be accessed using the LAHF, SAHF, PUSHF, and
POPF instructions .

5 .2 .8 Based Operands

Syntax

0 disp(
dispf
by j
bx

A based operand represents a memory address relative to one of the

base registers : by or bx . The disp can be any immediate or direct
memory operand . It must evaluate to an absolute number or
memory address . If no disp is given, zero is assumed .

The effective address of a based operand is the sum of the disp value
and the contents of the given register . If by is used, the operand's
address is relative to the segment pointed to by the ss register . If
bx is used, the address is relative to the segment pointed to by the
ds register .

Based operands have a variety of alternate forms . The following il-

lustrate a few of these forms :

displ lbpl
by + disp]
bp1 . disp
by +disp

In each case, the effective address is the sum of disp and the con-
tents of the given register .


Microsoft Macro Assembler Reference Manual

Examples

mov
mov
mov
ax,
ax,
ax,
[ by ]
[ bx ]
12 [ bx ]
0
mov ax, fred[ by ]

5 .2 .7 Indexed Operands

Syntax

disp[ si ]
disp( di ]

An indexed operand represents a memory address that is relative to

one of the index registers : si or di . The disp can be any immediate
or direct memory operand . It must evaluate to an absolute number
or memory address . If no disp is given, zero is assumed .

The effective address of an indexed operand is the sum of the disp

value and the contents of the given register . The address is always 0
relative to the segment pointed to by the ds register .

Indexed operands have a variety of alternate forms . The following

illustrate a few of these forms :

disp]]di]
di + disp]
d i .disp
di +disp

In each case, the effective address is the sum of disp and the con-
tents of the given register .

Examples

mov ax, [ s1 ]
mov
mov
mov
ax,
ax,
ax,
[ dl ]
12[ dl ]
fred [ si ]
0


Operands and Expressions

5 .2 .8 Based Indexed Operands

0 Syntax

disp by si ]
disp by di ]
disp bx si ]
disp bx di]

A based indexed operand represents a memory address that is rela-

tive to a combination of base and index registers . The disp can be
any immediate or direct memory operand . It must evaluate to an
absolute number or memory address . If no dip is given, zero is as-
sumed .

The effective address of a based indexed operand is the sum of the

disp value and the contents of the given registers . If the by register

is used, the address is relative to the segment pointed to by the as

register . Otherwise, the address is relative to the segment pointed
to by the ds register .

Based indexed operands have a variety of alternate forms . The fol-

lowing illustrate a few of these forms :

disp][bp][di]
by+di+di .•zp]
by+di] . disp
di]+disp+[bp]

In each case, the effective address is the sum of disp and the con-
tents of the given registers .

Examples

mov ax, [ by I [ si ]
mov ax, [ bx + di ]
mov ax, 12[ by + di ]
mov ax, fred[ bx ] [ si ]

5-7


Microsoft Macro Assembler Reference Manual

5 .2 .9 Structure Operands

Syntax

variable . field
0
A structure operand rrlpresents the memory address of one member
of a structure . The variable must be the name of a structure or must
be a memory operand that resolves to the address of a structure, and
field must be the name of a field within that structure .

The effective address of a structure operand is the sum of the offsets

of variable and field . The address is relative to the segment or group
in which the variable is defined .

In the following examples, "current-late" is assumed to be the

structure defined by the following :

date struc
month dw ?
day dw ?

date
year
ends
dw ?

current-date date <'ja','01','84'>

0
Example

mov ax, current _date .day

mov current_date .year, '85'

Structure operands are often used to access values on the stack .

One method is to copy the current stack address into the by regis-
ter, then use "( by ] .member" to access elements on the stack . This
method makes all values on the stack available in any desired for-
mat .

0
5-8


Operands and Expressions

5 .2 .10 Record Operands

0 Syntax

recordname < [value],,, >

A record operand refers to the value of a record type . The operands

can be in expressions . The recordname must be the name of a record
type defined in the source file . The optional value is the value of a
field in the record . If more than one value is given, the values must
be separated by commas . The enclosing angle brackets are required,
even if no value is given . If no value for a field is given, the default
value for that field is used .

Examples

mov ax, encode <1,3,2>

mov cx, key <,7>

0 5 .2 .11 Record Field Operands

Syntax

record-fieldname

The record field operand represents the location of a field in its

corresponding record . The operand evaluates to the bit position of
the low-order bit in the field and can be used as a constant operand .

The record-fieldname must be the name of a previously defined

record field . In the following examples, assume that the record
"reel" is defined as :

rtype RECORDfloldl :3,fleld2 :6,fleld3 :7

reel rtype < >

Example

mov ax, fieldl

This example copies 13, the shift count for field I, to ax .



Microsoft Macro Assembler Reference Manual

mov dx,recl
mov cl,fleld2
shr dx,el

This example copies 7, the shift count for field2, to cl, then uses the
0
address of ''reel,'' copied to dx, in a shift operation . This operation
adjusts reel so that field2 is now at the lowest bit .

5 .3 Expressions
An expression is a combination of operands and operators that
evaluates to a single value . Operands in expressions can be any of
the operands described in this chapter . The result of an expression
can be a value or a memory location, depending on the types of
operands and operators used .

MASM provides a variety of operators . Arithmetic, shift, relational,

and bitwise operators manipulate and compare the values of
operands . Attribute operators manipulate the attributes of
operands, such as their type, address, and size .

The following sections describe the operators in detail . The attri-

bute operators are described individually .

5 .3 .1 Arithmetic Operators

Syntax

expl * exp2
expl / exp2
expl MOD exp2
expl + exp2
expl exp2
+ exp
- exp

Arithmetic operators provide the common mathematical operations .

The operators have the following meanings :
0


Operands and Expressions

Operator Meaning
* Multiplication .

0 MOD
+
Integer division .
Remainder after division (modulus) .
Addition .
Subtraction .
+ Positive (unary) .
Negative (unary) .

For all arithmetic operators except + and -, the expressions expl

and exp2 must be integer numbers . The + operator can be used to
add an integer number to a relocatable memory operand . The -
operator can be used to subtract an integer number from a relocat-
able memory operand . The - operator can also be used to subtract
one relocatable operand from another, but only if the operands refer
to locations within the same segment . The result is an absolute
value .

Examples

0 14 * 4
14 / 4
14 MOD 4
;
;
;
equals 56
equals 3
equals 2
14 + 4 ; equals 18
14 - 4 ; equals 10
14 - +4 : equals 10
14 - -4 ; equals 18
alpha + 5 ; add 5 to alpha's offset
alpha - 5 ; subtract 5 from alpha's offset
alpha - beta ; subtract beta's offset from alpha's

5 .3 .2 SHR and SHL Operators

Syntax

expression SHR count

expression Sill, count

0 The SIIR and Sill, operators shift the given expression right or left
by count number of bits . Bits shifted off the end of the expression
are lost . If count is greater than or equal to 16, the result is 0 .


Microsoft Macro Assembler Reference Manual

Examples

01110111B SHL 3 equals 10111000B

01110111B SHR 3 equals 0000111013

5 .3 .3 Relational Operators

Syntax

expl EQ exp2
expl NE exp2
expl LT exp2
expl LE exp2
expl GT exp2
expl GE exp2

The relational operators compare the expressions expl and exp2 and
return true (OFFFFH) if the given condition is satisfied, or false
(0000H) if it is not . The expressions must resolve to absolute values .
The operators have the following meanings :
0
Operator Condition is satisfied when :
EQ Operands are equal .
NE Operands are not equal .
LT Left operand is less than right .
LE Left operand is less than or equal to right .
GT Left operand is greater than right .
GE Left operand is greater than or equal to right .

Relational operators are typically used with conditional directives

and conditional instructions to direct program control .

Examples

1 EQ 0 ; false
1 NE 0 ; true
1 LT 0 ; false
1 LE 0 ; false
1 GT 0 ; true
1 GE 0 ; true


Operands and Expressions

5 .3 .4 Bitwise Operators

0 Syntax

NOT erp
expl AND exp2
expl OR exp2
expl XOR exp2

The logical operators perform bitwise operations on the given ex-

pressions . In a bitwise operation, the operation is performed on each
bit in an expression rather than on the expression as a whole . The
expressions must resolve to absolute values .

The operators have the following meanings :

Operator Meaning
NOT Inverse .
AND Boolean AND .
OR Boolean OR .

0 Examples
XOR Boolean exclusive OR .

NOT 11110000B ;equals00001111B

01010101B AND 11110000B equals 0101000013
01010101B OR 11110000B equals 11110101B
01010101B XOR 11110000B equals 1010010113

5 .3 .5 Index Operator

Syntax

expression) [ expression2 ]

The index operator, 11, adds the value of expression) to expression2 .

This operator is identical to the + operator, except that erpressionl
is optional .

If expression) is given, the expression must, appear to the left of the

operator . It can be any integer value, absolute symbol, or relocat-
able operand . If no erpressionl is given, the integer value, 0, is as-


Microsoft Macro Assembler Reference Manual

sum .-d . If expression) is a relocatable operand, expression2 must be

an integer value or absolute symbol . Otherwise, expression2 can be
any integer value, absolute symbol, or relocatable operand .

The index operator is typically used to index elements of an array,

0
such as individual characters in a character string .

Examples

mov al, string[3]

mov ax, array[4]
1110V string[LAST], al
mov cx, DGROUP :[1]

Note that the last example is identical to the statement "mov ex,
DGROUP :1 .''

5 .3 .6 PTR Operator

Syntax

type PTR expression 0

The PTR operator forces the variable or label given by the expres-
sion to be treated as a variable or label having the type given by
type . The type must be one of the following names or values :

BYTE 1
WORD 2
DWORD 4
QWORD 8
TBYTE 10
NEAR OFFFFh
FAR OFFFEh

The expression can he any operand . The BYTE, WORD, and

DWORD types can be used with memory operands only . The NEAR
and FAR types can be used with labels only .

The PTR operator is typically used with forward references to expli-

citly define what size or distance a reference has . If not used,
0
MASM assumes a default size or distance for the reference . The PTR
operator is also used to give instructions access to variables in ways


Operands and Expressions

that would otherwise generate errors, for example, accessing the

high-order byte of a WORD size variable .

0 Examples

call far ptr subrout3

mov byte ptr [array] , 1
add al, byte ptr [full word]

5 .3 .7 Segment Override Operator

Syntax

segment-register : expression
segment-name : expression
group-name : expression

The segment override operator () forces the address of a given vari-

able or label to be computed using the beginning of the given

0 segment-register, segment-name, or group-name . If a segment-name

or group-name is given, the name must have been assigned to a seg-
ment register with a previous ASSUME directive and defined using a
SEGMENT or GROUP directive . The expression can be an absolute
symbol or relocatable operand . The segment-register must be one of
CS, DS, SS, or ES .

By default, the effective address of a memory operand is computed

relative to the DS, SS, or ES register, depending on the instruction
and operand type . Similarly, all labels are assumed to be NEAR .
These default types can be overridden using the segment override
operator .

Examples

mov ax, es :[bx][si]

mov _ TEXT :far _ label, ax
mov ax, DGROUP :variable
mov al, cs :0001H

5- 1 5


Microsoft Macro Assembler Reference Manual

5 .3 .8 SHORT Operator

Syntax

SHORT label

The SHORT operator sets the type of the given label to SHORT .
Short labels can be used in ''jump'' instructions whenever the dis-
tance from the label to the instruction is not more than 127 bytes .
Instructions using short labels are one byte smaller than identical
instructions using near labels .

Example

imp short repeat

5 .3 .9 THIS Operator

Syntax

THIS type

The THIS operator creates an operand whose offset and segment

value are equal to the current location counter value and whose type
is given by type . The type can be any one of the following :

NEAR FAR
BYTE WORD
DWORD QWORD
TBYTE

The THIS operator is typically used with the EQU or = directive to

create labels and variables . This is similar to using the LABEL
directive to create labels and variables .

Examples

tag equ this byte

This example is equivalent to the statement "TAG LABEL

0
BYTE" .

5- 1 6


Operands and Expressions

check = this near

• This example is equivalent to the statement "CHECK LABEL

NEAR" .

5 .3 .10 HIGH and LOW Operators

Syntax

11M'11 expression
LOW expression

The HIGH and LOW operators return the high and low 8 bits of the
given expression . The IIIGII operator returns the high 8 bits of the
expression ; the LOW operator returns the low-order 8 bits . The ex-
pression can be any value .

Examples

mov ah, high word value

0 mov al, low OFFFFH

5 .3 .11 SEG Operator

Syntax

SEG expression

The SEG operator returns the segment value of the given expression .
The expression can be any label, variable, segment name, group
name, or other symbol .

Example

mov ax, seg variable name

mov ax, seg label name


Microsoft Macro Assembler Reference Manual

5 .3 .12 OFFSET Operator

Syntax

OFFSET expression
0
The OFFSET operator returns the offset of the given expression.
The expression can be any label, variable, segment name, or other
symbol . The returned value is the number of bytes between the
item and the beginning of the segment in which it is defined . For a
segment name, the return value is the offset from the start of the
segment to the most recent byte generated for that segment .

The segment override operator ( :) can be used to force OFFSET to

return the number of bytes between the item in the expression and
the beginning of a named segment or group . This is the method
used to generate valid offsets for items in a group . See the second
example below .

Examples

mov
mov
bx, offset subrout3
bx, offset DGROUP :array 0
The returned value is always a relative value that is subject to
change by the linker when the program is actually linked .

5 .3 .13 TYPE Operator

Syntax

TYPE expression

The TYPE operator returns a number representing the type of the

given expression . If the expression is a variable, the operator returns
the size of the operand in bytes . If the expression is a label, the
operator returns OFFFFH if the label is NEAR, and OFFFEH if the
label is FAR . Note that the return value can be used to specify the
type for a PTR operator . See the second example below .
0


Operands and Expressions

Examples

• mov ax, type array

imp (type get_loc) ptr destiny

5 .3 .14 TYPE Operator

Syntax

.TYPE expression

The TYPE operator returns a byte that defines the mode and scope
of the given expression . If the expression is not valid, TYPE returns
zero .

The variable's attributes are returned in bits 0, 1, 5, and 7 as fol-

lows :

Bit Position If Bit= 0 If Bit= 1

0 0
1
Absolute
Not Data related
Program related
Data related
5 Not defined Defined
7 Local scope External scope

If both the scope bit and defined bit are zero, the expression is not
valid .
The TYPE operator is typically used with conditional directives,
where an argument may need to be tested to make a decision regard-
ing program flow .

Example

x db 12
z equ .type x

This example sets z to 34 .



Microsoft Macro Assembler Reference Manual

5 .3 .15 LENGTH Operator

Syntax

LENGTH variable
is
The LENGTH operator returns the number of BYTE, WORD,
DWORD, QWORD, or TBYTE elements in the given variable . The
size of each element depends on the variable's defined type .

Only variables that have been defined using the DUP operator re-
turn values greater than one . The return value is always the
number that precedes the first DUP operator .

In the following examples, assume the definitions :

array dw 100 dup(1)

table dw 100 dup(1,10 dup(?))

Examples

mov cx, length array

0
In this example, LENGTH returns 100 .

mov cx, length table

In this example, LENGTH returns 100 . The return value does not
depend on any nested DUP operators .

5 .3 .18 SIZE Operator

Syntax

SIZE variable

The SIZE operator returns the total number of bytes allocated for
the given variable . The return value is equal to the return value of
LENGTH times the return value of TYPE .
0
5-20


Operands and Expressions

In the following example, assume the definition :

9 Example
array dv 100 dup(1)

mov bx, size array

In this example, SIZE returns 200 .

5 .3 .17 WIDTH Operator

Syntax

WIDTH record-fieldname I record

The WIDTH operator returns the width (in bits) of the given record
field or record . The record-fieldname must be the name of a record
defined in a field . The record must be the name of a record .

0 In the following examples, assume that the record "reel" is defined

as :

rtype RECORD fleldl :3,fleld2 :6,fleld3 :7

reel rtype <>

Example

WIDTH fleldl ;equals 3

WIDTH fleld2 ;equals 6
WIDTH fleld3 ;equals 7
WIDTH rtype ;equals 16


Microsoft Macro Assembler Reference Manual

5 .3 .18 MASK Operator

Syntax

MASK record-fieldname I record

0
The MASK operator returns a bit mask for the bit positions in a
record occupied by the given record field . A bit in the mask con-
tains a 1 if that bit corresponds to a record bit . All other bits con-
tain 0 . The record-fieldname must be the name of a record field .

In the following examples, assume that the record "reel" is defined

as :

rtype RECORD fleldl :3,fleld2 :6,field3 :7

reel rtype <>

Example

MASK fleldl ;equals E000H

MASK fleld2 ;equals 1F80H
MASK fleld3 ;equals 003FH
MASK rtype ; equals OFFFFH

5 .3 .19 Expression Evaluation and Precedence

Expressions are evaluated according to the rules of operator pre-

cedence and order . Operations of highest precedence are performed
first . Operations of equal precedence are performed from left to
right . This default order of evaluation can be overridden using en-
closing parentheses . Operations in parentheses are always per-
formed before any adjacent operations . The following table lists the
precedence of all operators . Operators on the same line have equal
precedence .

Operands and Expressions

Precedence Operators
Highest
0 1 LENGTH, SIZE, WIDTH, MASK
2
3
4
r
5 PTR, OFFSET, SEG, TYPE, THIS
6 HIGH, LOW
7 MOD, SHL, SHR
8 +,-
9 EQ, NE, LT, LE, GT, GE
10 NOT
11 AND
12 OR, XOR
13 SHORT, .TYPE
Lowest

Examples

0 8 / 4 * 2
8 /
8 + 4 * 2
(4 * 2)
equals 4
equals 1
equals 16
(8 + 4) * 2 equals 24
8 EQ 4 AND 2 LT 3 equals 000011 (false)
8 EQ 4 OR 2 LT 3 equals OFFFFH (true)

5 .4 Forward References
Although MASM permits forward references to labels, variable
names, segment names, and other symbols, such references can lead
to assembly errors if not used properly . A forward reference is any
use of a name before it has been formally declared . For example, in
the JMP instruction below, the label "target" is a forward reference .

Imp target
may ax, 0
target :

Whenever MASM encounters an undefined name in pass 1, it as-

sumes that the name is a forward reference . If only a name is given,
MASM makes assumptions about that name's type and segment re-


Microsoft Macro Assembler Reference Manual

gister, and uses these assumptions to generate code or data for the
statement . For example, in the JMP instruction above, MASM as-
sumes that "target" is an instruction label having NEAR type . It
generates three bytes of instruction code for the instruction . 0
MASM bases its assumptions on the statement containing the for-
ward reference . Errors can occur when these assumptions are in-
correct . For example, if "target" were really a FAR label and not a
NEAR label, the assumption made by MASM in pass 1 would cause a
phase error . In other words, MASM would generate five bytes of in-
struction code for the JMP instruction in pass 2 but only three in
pass 1 .

To avoid errors with forward references, the segment override (),

PTR, and SHORT operators should be used to override the assump-
tions made by MASM whenever necessary . The following guidelines
list when these operators should be used .

If a forward reference Is a variable that is relative to the ES,

SS, or CS register, then use the segment override operator ( :) to
specify the variable's segment register, segment, or group .

Examples
0
mov ax, ss :stacktop
inc data :tlme[1]
add ax, dgroup :_I

If the segment override operator is not used, MASM assumes that

the variable is DS relative .

If a forward reference is an instruction label in a JMP in-

struction, then use the SHORT operator if the instruction is less
than 128 bytes from the point of reference .

Example

jmp short target

If SHORT is not used, MASM assumes that the instruction is

greater than 128 bytes away . This does not cause an error, but it
does cause MASM to generate an extra NOP instruction that is not
0
needed .

r nA


Operands and Expressions

If a forward reference Is an Instruction label In a CALL or

JMP instruction, then use the PTR operator to specify the label's

0 type .

Examples

call far ptr print

imp near ptr exit

MASM assumes that the label has NEAR type, so PTR need not be
used for NEAR labels . If the label has FAR type, however, and PTR
is not used, a phase error will result .

If the forward reference is a segment name with a segment

override operator, use the GROUP statement to associate the seg-
ment name with a group name, then use the ASSUME statement to
associate the group name with a segment register .

Example

dgroup segment stack

0 assume ss : dgroup

code segment

mov ax, stack :stacktop

If you do not associate a group with the segment name, MASM may
ignore the segment override and use the default segment register for
the variable . This usually results in a phase error in pass 2 .


Microsoft Macro Assembler Reference Manual

5 .5 Strong Typing for Memory Operands

MASM carries out strict syntax checks for all instruction state-
ments, including strong typing for operands that refer to memory
locations . This means that any relocatable operand used in an in-
0
struction that operates on an implied data type must either have
that type, or have an explicit type override (PTR operator) .

For example, in the following program segment, the variable

"string'' is incorrectly used in an move instruction .

string db "A message ."

mov ax, string[l]

This statement will create an ''Operand types must match" error

since ''string'has BYTE type and the instruction expects a variable
having WORD type .

To avoid this error, the PTR operator must be used to override the
variable's type . The statement

mov ax, WORD PTR string[1]

0
will assemble correctly and execute as expected .

0
 Chapter 6
Global Declarations

6 .1 Introduction 6-1

6 .2 PUBLIC Directive 6-2

6 .3 EXTRN Directive 6-3

6 .4 Program Example 6-4

0
S

0
 Global Declarations

0 6 .1 Introduction
The Global Declaration directives let a programmer define labels,
variables, and absolute symbols that can he accessed globally, that is,
from all modules in a program . Global declarations transform "local"
symbols (labels, variables, and other symbols that can be used only in
the source files in which they are defined) into "global" symbols that
are available to all other modules .

There are the following Global Declaration directives :

PUBLIC
EXTRN

The PUBLIC directive is used in public declarations . A public declara-

tion transforms a locally defined symbol into a global symbol, making
it available to other modules . The EXTRN directive is used in exter-
nal declarations . An external declaration makes a global symbol's
0 name and type known in a source file, letting the global symbol be used
in that file . Every global symbol must have a public declaration in ex-
actly one source file of the program . A global symbol can have external
declarations in any number of other source files . The following sec-
tions describe the Global Declaration directives in detail .

6- 1


Microsoft Macro Assembler Reference Manual

6 .2 PUBLIC Directive
Syntax

PUBLIC name,,,

The PUBLIC directive makes the variable, label, or absolute symbol

given by name available to all other modules in the program . The
name must be the name of a variable, label, or absolute symbol defined
within the current source file . Absolute symbols, if given, can only
represent I- or 2-byte integer or string values .

MASM converts all lowercase letters in name to uppercase before

copying the name to the object file . The /ML and /MX options can be
used in the MASM command line to direct MASM to preserve lower-
case letters when copying to the object file . See Chapter 2 in the Micro-
soft Alacro Assembler User's Guide for more information .

Example

public true, test, start

true
test
start
=
db
OFFFFH
1
label far
0

0
6-2


Global Declarations

6 .3 EXTRN Directive
• Syntax

EXTRN name :type,,,

The EXTRN directive defines an external variable, label, or symbol

named name and whose type is type . An external item is any vari-
able, label, or symbol that has been publicly declared in another
module of the program .

The name must be the name of a variable, label, or symbol defined

in another module of the program and listed in a PUBLIC directive
of the corresponding source file . The type must match the type given
to the item in its actual definition . It can be any one of the follow-
ing :

BYTE WORD
DWORD QWORD
TBYTE
NEAR FAR
ABS

The ABS type is reserved for symbols that represent absolute

numbers .

Although the actual address is not determined until link time, the
assembler may assume a default segment for the external item based
on where the EXTRN directive is placed in the module . If the direc-
tive is placed inside a segment, the external item is assumed to be
relative to that segment . In this case, the item's public declaration
(in some other module) must be in a segment having the same name
and attributes . If the directive is outside all segments, no assump-
tion is made about what segment the item is relative to, and the
item's public declaration can be in any segment in any module . In
either case, the segment override operator ( :) can be used to override
an external variable's or label's default segment .

Example

extrn tagn :near

extrn varl :word, var2 :dword


Microsoft Macro Assembler Reference Manual

6 .4 Program Example
The following source files illustrate a program that uses public and
external declarations to access instruction labels . The program con-
sists of two modules, named "startmod" and "printmod ." The
0
"startmod" module is the program's main module . Execution starts
at the instruction labeled "start" in "startmod," and passes to the
instruction labeled ''print" in "printmod" where a DOS system call
is used to print the message "Hello" at the system console . Execu-
tion then returns to the instruction labeled "exit'' in "startmod ."

Startmod Module :

NAME startmod
public start, exit
extrn main :near

stack segment word public 'STACK'

dw 64 dup(?)
stack ends

data
data
segment word public
ends
'DATA'
0
code segment byte public 'CODE'
assume cs :code, ds :data
start :
mov ax, seg DATA
mov ds, ax
jmp print
exit :
mov ah, 4ch
int 21h
code ends
end start

0
6-4


Global Declarations

Printmod M, dale :

0 NAME printmod
public print
extrn exit :near

data segment word public 'DATA'

string db "Hello .', 13, 10, "$"
data ends

code segment byte public 'CODE'

assume cs :code, ds :data
print :
mov dx, offset string
mov ah, 9
int 21h
jmp exit
code ends

end

In this example, "startmod" publicly declares two symbols, "start"

and "exit," making the symbols available to the other source file in
the program . Both of these symbols are locally defined as instruc-
tion labels later in the source file, and therefore can be used as in-
struction labels in the other source file . The ''startmod" file also
contains an external declaration of the symbol "print ." This de-
claration defines "print" to be a near label and is assumed to have
been publicly declared in the other source file . The label is used in a
JMP instruction given later in the file .

The "printmod" file contains a public declaration of the symbol

''print'' and an external declaration of the symbol ''exit ." In this
case, "print'' is locally defined as a near label and matches the
external declaration given to it in "startmod ." The symbol "exit" is
declared to be a near label, matching its definition in "startmod ."

Before this program can be executed, these source files must be as-
sembled individually, then linked together using the system linker .
S

0
 Chapter 7
Conditional Assembly

7 .1 Introduction 7-1

7 .2 IF and IFE Directives 7-2

7 .3 IF1 and IF2 Directives 7-2

7 .4 IFDEF and IFNDEF Directives 7-3

7 .5 IFB and IFNB Directives 7-3

7 .6 IFIDN and IFDIF Directives 7-4

0
S

0
 Conditional Assembly

0 7 .1 Introduction
The Conditional Assembly directives provide conditional assembly of
blocks of statements within a source file . There are the following con-
ditional directives :

IF
IFE
IF1
IF2
IFDEF
IFNDEF
IFB
IF NB
IFIDN
IFDIF
ELSE
ENDIF
0 The IF directives and the ENDIF and ELSE directives can be used to
enclose the statements to be considered for conditional assembly . The
conditional block takes the form :

IF
statements
ELSE
statements
ENDIF

where the statementscan be any valid statements, including other con-

ditional blocks . The ELSE directive is optional .

MASM assembles the statements in the conditional block only if the

condition that satisfies the corresponding IF directive is met . If the
conditional block contains an ELSE directive, however, MASM will as-
semble only the statements up to the ELSE directive . The statements
following the ELSE directive are assembled only if the IF condition is
not met . An ENDIF directive must mark the end of the conditional
block . No more than one ELSE for each IF directive is allowed .
Microsoft Macro Assembler Reference Manual

IF directives can be nested up to 255 levels . To avoid ambiguity, a

nested ELSE directive always belongs to the nearest, preceding IF
directive .
0
7 .2 IF and IFE Directives
Syntax

IF expression
IFE expression

The IF and IFE directives test the value of an expression . The IF direc-
tive grants assembly if expression is non-zero (true) . The IFE directive
grants assembly if expression is 0 (false) . The expression must resolve
to an absolute value and must not contain forward references .

Example

if DEBUG
extrn dump :far

end if
extrn trace :far
extrn breakpoint :far 0
7 .3 IF1 and IF2 Directives
Syntax

IF1
IF2

The IF1 and IF2 directives test the current assembly pass . The IF1
directive grants assembly on pass 1 only . IF2 grants assembly on
pass 2 . The directives take no arguments .

Conditional Assembly

0 %out Pass 1 Starting

7 .4 IFDEF and IFNDEF Directives

Syntax

IFDEF name
IFNDEF name

The IFDEF and IFNDEF directives test whether or not the given
name has been defined . The IFDEF directive grants . assembly if
name is a label, variable, or symbol . The IFNDEF directive grants
assembly if name has not yet been defined .

The name can be any valid name . Note that if name is a forward
0 reference, it is considered undefined on pass 1, but defined on pass 2 .
This is a frequent cause of phase errors .

Example

lfndef BUFFER
BUFFER db 10 dup(?)
endif

7 .5 IFB and IFNB Directives

Syntax

IFB < arg>

IFNB < arg>

0 The IFB and IFNB directives test the given arg . The IFB directive
grants assembly if arg is blank . The IFNB directive grants assembly
if arg is not blank . The arg can be any name, number, or expression .
The angle brackets (< >) are required .
Microsoft Macro Assembler Reference Manual

The IFB and IFNB directives are intended to be used in macro defin-
itions . They can be used to control conditional assembly of state-
ments in the macro based on the parameters passed in the macro
call . In such cases, arg should be one of the dummy parameters list-
ed by the MACRO directive .
0
Examples

IFB <X>

This example tests the argument "<X> ." If this is in a macro de-
finition and no parameter was passed for X, the directive would
grant assembly .

IFNB < EXIT>

This example tests the argument "<&EXIT> ." This is assumed to

be in a macro definition . If no parameter is passed for EXIT, the
directive does not grant assembly .

7 .6 IFIDN and IFDIF Directives

Syntax
0
IFIDN < argl >, < arg2>
IFDIF < argl >, < arg2>

The IFIDN and IFDIF directives test argl and arg2. The IFIDN
directive grants assembly if the arguments are identical . The IFDIF
directive grants assembly if the arguments are different . The argu-
ments can be any names, numbers, or expressions . To be identical,
each character in argl must match the corresponding character in
arg2 . The angle brackets (< >) are required .

The IFIDN and IFDIF directives are intended to be used in macro

definitions . They can be used to control conditional assembly of
statements in the macro based on the parameters passed in the mac-
ro call . In such cases, the arguments should be dummy parameters
listed by the MACRO directive .
0
 Conditional Assembly

Examples

0 IFIDN <X>, <Y>

This example tests the arguments "<X>" and "<Y> ." If this is
in a macro definition and the parameters passed for X and Y are
identical, the directive grants assembly .

IFDIF < EXIT>, <CASE>

This example tests the arguments "<&-EXIT>" and "<CASE> ."

This is assumed to be in a macro definition . If the parameters
passed for EXIT and CASE are identical, the directive does not
grant assembly .
0

0
 Chapter 8
Macro Directives

8 .1 Introduction 8-1

8 .2 MACRO and ENDM Directives 8-2

8 .3 Macro Calls 8-4

8 .4 LOCAL Directive 8-5

8 .5 PURGE Directive 8-6

8 .6 REPT and ENDM Directives 8-7

0 8 .7 IRP and ENDM Directives 8-8

8 .8 III PC and ENDM Directives 8-10

8 .9 EXITM Directive 8-11

8 .10 Substitute Operator 8-12

8 .11 Literal Text Operator 8-13

8 .12 Literal Character Operator 8-1-1

8 .13 Expression Operator 8-14

8 .14 Macro Comment 8-15

S

Macro Directives

0 8 .1 Introduction
This chapter explains how to create and use macros in your source
files . There are the following macro directives :

MACRO
LOCAL
PURGE
REPT
IRP
IRPC
EXITM
ENDM

The MACRO directive lets you write a named block of source state-
ments, then use that name in your source file to represent the state-
ments . MASM automatically replaces each occurrence of a macro
name with the statements given in the macro definition . This means
0 you can place a block of statements any where in your source file any
number of times by simply defining it once, then giving the name
where you need it . The LOCAL directive lets you define unique labels
for a macro, and the PURGE directive lets you control the macros you
define .

The REPT, IRP, and IRPC directives also let you create contiguous
blocks of repeated statements . You control the number of times the
statements are repeated . You can repeat them a given number of
times, once for each parameter in a list, or once for each character in a
string .

The macro directives use a special set of macro operators :

& Ampersand
;; Double semicolon
! Exclamation mark
Percent sign

When used in a macro definition, these operators carry out special

control operations, such as text substitution .
Microsoft Macro Assembler Reference Manual

8 .2 MACRO and ENDM Directives

Syntax

name MACRO dummy-parameter,,,

statements
ENDM

The MACRO and ENDM directives create a macro having the given
name and containing the given statements .

The name must be a valid name and must be unique . It is used in the
source file to invoke the macro . The dummy-parameteris a name that
acts as a placeholder for values to be passed to the macro when it is
called . Any number of dummy parameters can be given, but they must
all fit on one line . If you give more than one, you must separate them
with commas (,) . The statements are any valid MASM statements, in-
cluding other MACRO directives . Any number of statements can be
used . The dummy parameter can be used any number of times in these
statements .

A macro is "called" anytime the macro's name appears in a source file

(macros names in comments are ignored) . MASM copies the state-
ments in the macro definition to the point of call, replacing any dum-
0
my parameters in these statements with values passed in the call .
Dummy parameters are replaced according to their order in the defini-
tion . Thus, the dummy parameter occupying the fourth parameter
position in the macro definition is replaced by the fourth actual
parameter in the macro call .

Macro definitions can be nested . This means a macro can be defined

within another macro . MASM does not process nested definitions un-
til the outer macro has been called, therefore, nested macros cannot be
called until the outer macro has be called at least once . Macro defini-
tions can be nested to any depth . Nesting is limited only by the
amount of memory available when the source file is assembled .

Macro definitions can contain calls to other macros . These nested mac-
ro calls are expanded like any other macro call, but only when the
outer macro is called . A macro definition cannot contain a call to it-
self . 0


Macro Directives

Notes

Remember that MASNI replaces all occurrences of a dummy-

parameter's name, even if you do not intend it to . For example, if
you use a register name such as AX or Bli for a dummy, MASM re-
places all occurrences of that register name when it expands the
macro . If the macro definition contains statements that use the
register, not the dummy, the macro will be incorrectly expanded .

MASN1 assembles the statements in the macro only if the macro is

called, and only at the point they are inserted into the source file .
This means all addresses in the assembled code are relative to the
macro call, not the macro definition . The macro definition itself is
never assembled .

You must be careful when using the word MACRO after the TI-
TLE, StUBTTL, and NAME directives . Since the MACRO direc-
tive overrides these directives, placing the word immediately after
these directives causes MASN1 to begin to create macros named
TITLE, St'BTTL, and NAME . To avoid this problem, you should
alter the word MACRO in some way when using it in a title or
name . For example, add a hyphen to the word, "- MACRO ."

Examples

add MACRO xx,yy,zz

mov ax, xx
add ax, yy
mov zz, ax
ENDM

This example defines a macro named ''add'', that contains three

statements and uses three dummy parameters . The dummy parame-
ters are "xx,'' "yy," and "zz ." These parameters will be replaced
with actual values when the macro is called .


Microsoft Macro Assembler Reference Manual

8 .3 Macro Calls
Syntax

name I actual-parameter,,, I
0
A macro call directs MASM to copy the statements of the macro
name to the point of call and to replace any dummy parameters in
these statements with the corresponding actual-parameters . The
name must be the name of a macro defined earlier in the source file .
The actual-parameter can be any name, number, or other value . Any
number of actual parameters can be given, but they must all fit on
one line . Multiple parameters must be separated with commas,
spaces, or tabs .

MASM replaces the first dummy parameter with the first actual
parameter, the second with the second, and so on . If a macro call
has more actual parameters than dummy parameters, the extra ac-
tual parameters are ignored . If a call has fewer actual parameters,
any remaining dummy parameters are replaced with nothing . This
means MASM removes the dummy parameter name for the macro
statements, but does nothing else .

If you wish to pass a list of values as a single actual parameter, you

0
must place angle brackets (< >) around the list . The items in the
list must be separated by commas .

Examples

ALLOCBLOCK 1,2,3,4,5

This example passes five numeric parameters to the macro ALLOC-

BLOCK .

ALLOCBLOCK <1,2,3,4,5>

This example passes one parameter to ALLOCBLOCK . This param-

eter is a list of five numbers .

add 1, inc, linecount

This example passes three parameters to the macro ''add ." The first
parameter is a number, but the second and third are symbols .
MASM replaces the corresponding dummy parameters with exactly
what is typed here .
 Macro Directives

8 .4 LOCAL Directive

0 Syntax

LOCAL dummy-name,,,

The LOCAL directive creates unique names for use in macros . The
dummy-name is a name for a placeholder that is to be replaced by
the unique name when the macro is expanded . At least one dummy-
name is required . If you give more than one, you must separate the
names with commas . A dummy name can be used in any statement
within the macro .

MASM creates a new name for a dummy each time the macro is ex-
panded . The name has the form

??zzxx

where xxxx is a hexadecimal number in the range 0000 to FFFF .

The LOCAL directive is typically used to create unique labels for

0 macros . Normally, if a macro containing a label is used more than
once, MASM will display a multiply-defined label error message
since the same label will appear in both expansions . To avoid this
problem, all labels can be local dummy names . MASM guarantees
that these names will be replaced with unique names whenever the
macro is expanded, no matter how often the macro is expanded .

Note

The directive can be used only in a macro definition, and it must

precede all other statements in the definition .

Q r
Microsoft Macro Assembler Reference Manual

Example

loop MACRO count, y

LOCAL A 0
mov ax, y
A: mov ex, count
inc ax
jnz A
ENDM

In this example, the LOCAL directive defines a dummy name "A"

that is replaced with a unique name each time the macro is expand-
ed . "A'' is used in two places in the macro : as a statement label, and
as the target of a JNZ instruction .

8 .5 PURGE Directive

Syntax

PURGE macro-name ,,,

The PURGE directive deletes the current definition of the macro

macro-name from memory . Any subsequent call to that macro
causes MASM to generate an error .

The PURGE directive is intended to clear memory space no longer

needed by a macro . If the macro-name is an instruction or directive
mnemonic, the directive restores its previous meaning .

The PURGE directive is often used with a "macro library" to let

you choose those macros from the library you really need in your
source file . A macro library is simply a file containing macro defini-
tions . You add this library to your source file using the INCLUDE
directive, then remove unwanted definitions using the PURGE
directive .

It is not necessary to PURGE a macro before redefining it . Any

redefinition of a macro automatically purges the previous definition .
Also, any macro can purge itself .
0


Macro Directives

Examples

0 PURGE add

This example deletes the macro named ''add'' from the assembler's
memory .

PURGE maci, mac2, mac9

This example deletes the macros named "maci," "mac2," and

` mac9

8 .6 REPT and ENDM Directives

Syntax

REPT expression
statements
ENDM

• The REPT and ENDM directives define a block of statements that

are to be repeated expression number of times . The expression must
evaluate to a 16-bit unsigned number . It must not contain external
or undefined symbols . The statements can be any valid statements .

Example

X = 0
REPT 10
X = X+1
DB X
ENDM

This example repeats the = and DB directives 10 times . The result-

ing statements create 10 bytes of data whose values range from 1 to
10 .
Microsoft Macro Assembler Reference Manual

8 .7 IRP and ENDM Directives

Syntax

IRP dummy, < parameter . . . >

0
statements
ENDM

The IRP and ENDM directives define a block of statements that are
to be repeated once for each parameter in the list enclosed by angle
brackets (< >) . The dummy is a name for a placeholder to be re-
placed by the current parameter . The parameter can be any legal
symbol, string, numeric, or character constant . Any number of
parameters can be given . If you give more than one, you must
separate them with commas . The statements can be any valid as-
sembler statements . The dummy can be used any number of times
in these statements .

When MASM encounters an IRP directive, it makes one copy of the

statements for each parameter in the enclosed list . While copying
the statements, it replaces all occurrences of dummy in these state-
ments with the current parameter . If a null parameter (<>) is
found in the list, the dummy is replaced with a null value . If the
parameter list is empty, the IRP directive is ignored and no state-
0
ments are copied .

Example

IRP X,<1,2,3,4,5,6,7,8,9,10>
DB X
ENDM

This example repeats the DB directive 10 times, once for each

number in the list . The resulting statements create 10 bytes of data
having the values 1 through 10 .

0
 Macro Directives

Notes
0 If an empty parameter is found in the list, MMASM repeats the
statements once, replacing the dummy with no value . If the en-
tire list is empty, MMASMM skips the repeat block .

If an IRP directive is used inside a macro definition and the

parameter list of the IRP directive is also a dummy parameter of
the macro, you must enclose that dummy parameter within an-
gle brackets . For example, in the following macro definition, the
dummy parameter "X" is used as the parameter list for the IRP
directive :

alloc MACRO X
IRP Y,<X>
DB Y
ENDM
ENDM

0 If this macro is called with

allot <1,2,3,4,5,6,7,8,9,10>

the macro expansion becomes

IRP Y,<1,2,3,4,5,6,7,8,9,10>
DB Y
ENDM

That is, the macro removes the brackets from the actual param-
eter before replacing the dummy . This means you must provide
the angle brackets for the parameter list yourself .


Microsoft Macro Assembler Reference Manual

8 .8 IRPC and ENDM Directives

Syntax

IRPC dummy, string

9
statements
ENDM

The IRPC and ENDM directives define a block of statements that

are repeated once for each character in the string . The dummy is a
name for a placeholder to be replaced by the current character in the
string . The string can be any combination of letters, digits, and oth-
er characters . The string should be enclosed with angle brackets (<
> if it contains spaces, commas, or other separating characters .
The statements can be any valid assembler statements . The dummy
can be used any number of times in these statements .

When MASM encounters an IRPC directive, it makes one copy of

the statements for each character in the string . While copying the
statements, it replaces all occurrences of dummy in these state-
ments with the current character .

Example

IRPC X,0123456789
DB X+1
ENDM

This example repeats the DB directive 10 times, once for each char-
acter in the string "0123156789 ." The resulting statements create 10
bytes of data having the values 1 through 10 .

Macro Directives

8 .9 EXITM Directive

0 Syntax

EXITNI

The EXITh1 directive directs NIASM to terminate macro or repeat

block expansion and continue assembly with the next statement
after the macro call or repeat block . The directive is typically used
with IF directives to allow conditional expansion of the last state-
ments in a macro or repeat block .

When an EXITM is encountered, MASM exits the macro or repeat

block immediately . Any remaining statements are not processed . If
EXITM is encountered in a macro or repeat block nested in another,
MASM returns to expanding the outer level block .

Example

alloc MACRO times

x = 0

0 REPT
IFE
times
x-OFFH
EXITM
ELSE
DB x
END IF
x = x+1
ENDM
ENDM

This example defines a macro that creates no more than 255 bytes of
data . The macro contains an IFE directive that checks the expres-
sion "x-OFFh" . When this expression is 0 (x equal to 255), the EX-
ITM directive is processed and expansion of the macro stops .


Microsoft Macro Assembler Reference Manual

8 .10 Substitute Operator

Syntax

&dummy-parameter
0
or
dummy-parameter&

The substitute operator (&) forces MASM to replace the given

dummy-parameter with its corresponding actual parameter value .
The operator is used anywhere a dummy parameter immediately
precedes or follows other characters, or anytime the parameter ap-
pears in a quoted string .

Example

errgen MACRO Y, X
error&X db 'Error .tY - &X'
ENDM

In this example, MASM replaces &X with the value of the actual
parameter passed to the macro "errgen ." If the macro is called with
the statement

errgen 1, wait

the macro is expanded to

errorwait db 'Error 1 - wait'

Note
For complex, nested macros, you can use extra ampersands to
delay the actual replacement of a dummy parameter . In general,
you need to supply as many ampersands as there are levels of
nesting .

For example, in the following macro definition, the substitute

operator is used twice with Z to make sure its replacement oc-
curs while the IRP directive is being processed .
0


Macro Directives

alloc MACRO X
IRP Z,<1,2,3>

0 X&&Z

ENDM
DB
ENDM
Z

In this example, the dummy parameter "X" is replaced immedi-

ately when the macro is called . The dummy parameter "Z,"
however, is not replaced until the IRP directive is processed .
This means the parameter is replaced once for each number in
the IRP parameter list . If the macro is called with

alloc VAR

the expanded macro will be

VAR1 DB 1
VAR2 DB 2
VAR3 DB 3

0
8 .11 Literal Text Operator
Syntax

< text>

The literal text operator directs MASM to treat text as a single

literal . The operator is most often used with macro calls and the
IRP directive to ensure that values in a parameter list are treated as
a single parameter .

The literal text operator can also be used to force MASM to treat
special characters such as ; or & literally . For example, the semi-
colon inside angle brackets < ;> becomes a semicolon, not a com-
ment indicator .

MASM removes one set of angle brackets each time the parameter is
used in a macro . When using nested macros, you will need to supply
as many sets of angle brackets as there are levels of nesting .
Microsoft Macro Assembler Reference Manual

8 .12 Literal Character Operator

Syntax

!character

The literal character operator forces MASM to treat character as a

literal . For example, you can force MASM to treat special charac-
ters such as ; or & literally . Therefore, ! ; is equivalent to < ;> .

8 .13 Expression Operator

Syntax

text

The expression operator (%) causes MASM to treat text as an ex-

pression . MASM computes the expression's value, using numbers of
the current radix, and replaces text with this new value . The text
must represent a valid assembler expression .

The expression operator is typically used in macro calls where the

0
programmer needs to pass the result of an expression to the macro
instead of the actual expression .

Example

printe MACRO msg,n

%OUT * msg,n
ENDM
syml EQU 100
sym2 EQU 200
printe <syml + sym2 _ >,%(symi + sym2)

In this example, the macro call

printe <syml + sym2 = >,%(syml + sym2)

passes the text literal ''syml + sym2 =" to the dummy parameter
"msg .'' It passes the value 300 (the result of the expression "syml +
sym2") to the dummy "n ."
 Macro Directives

8 .14 Macro Comment

0 Syntax

; ;text

The macro comment is any text in a macro definition that does not
need to be copied in the macro expansion . All text following the dou-
ble semicolon ( ; ;) is ignored by the assembler and will appear only in
the macro definition when the source listing is created .

Regular comments, unlike macro comments, can be copied to each

macro expansion by specifying the XALL directive in the source file .

0
S

0
Chapter 9
File Control

9 .1 Introduction 0-1

9 .2 INCLUDE Directive 0-1

9 .3 .RADIX Directive 9-2

9 .4 'oOUT Directive 9-3

9 .5 NAME Directive 9- 1

9 .6 TITLE Directive 9-4

9 .7 SUBTITLE Directive 9-5

9 .8 PAGE Directive 9-5

9 .9 LIST and .XLIST Directives 9-(i

9 .10 .SFC'OND, .LFCOND,

and TFCOND Directives 9-7

9 .11 .1-ALL, .XALL, and SALE Directives 0-8

9 .12 .CHEF and .XCREF Directives 9-9

S

File Control

0 9 .1 Introduction
This chapter describes File Control directives . These directives pro-
vide control of the source, object, and listing files read and created by
MASNI during an assembly .

There are the following File Control directives :

INCLUDE Include a Source File

.RADIX Alter Default Input Radix
¶ OUT Display Message on Console
NAME Copy Name to Object File
TITLE Set Program Listing Title
St 1BTTL Set Program Listing Subtitle
PAGE Set Program Listing Page Size
LIST List Statements in Program Listing
.XLIST Suppress Listing Statements
.LFCOND List False Conditional in Program Listing
0 .SFCOND
.TFCOND
Suppress False Conditional Listing
Toggle False Conditional Listing
List Macro Expansions in Program Listing
.LALL
.SALL Suppress Listing Macro Expansion
.XALL Exclude Comments from Macro Listing
.CREF List Symbols in Cross Reference File
.XCREF Suppress Symbol Listing

The following sections describe the directives in detail .

9 .2 INCLUDE Directive
Syntax

INCLUDE filename

The INCLUDE directive inserts source code from the source file given
by filename into the current source file during assembly . The filename
must name an existing file . A pathname must be given if the file is not
in the current working directory . If the named file is not found,
MASM displays an error message and stops .

0 1


Microsoft Macro Assembler Reference Manual

When NIASM encounters an INCLUDE directive, it opens the named

file and begins to assemble its source statements immediately . When
all statements have been read, MASM resumes with the next state-
ment following the directive . 0
Nested INCLUDE directives are allowed . This means a file named by
an INCLUDE directive can contain its own INCIA'DI ; directives .

When a program listing is created, MASMI marks included statements

with the letter C .

Examples

include entry
include include\record
include \usr\include\as\stdio

9 .3 RADIX Directive
Syntax 0
.RADIX expression

The RADIX directive sets the default input radix for numbers in
the source file . The expression defines whether the numbers are
binary, octal, decimal, hexadecimal, or numbers of some other base .
It must be within the range 2 to 16 . The following lists some com-
mon values :

2 - binary
8 - octal
10 - decimal
16 - hexadecimal

The expression is always considered a decimal number regardless of

the current default radix .

Examples

radix 16
0
radix 2
 File Control

0 Notes
The RADIX directive does not affect the DD, DQ, or DT direc-
tives . Numbers entered in the expression of these directives are
always evaluated as decimal unless a numeric suffix is appended
to the value .

The RADIX directive does not affect the optional radix specif-
iers, B and D, used with integers numbers . When B or D ap-
pears at the end of any integer, it is always considered to be a
radix specifier even if the current input radix is 16 . This means
that numbers such as ''Oabcd'' and "234b'' are illegal even when
the input radix is set to 16 . ( "a," "b," and ''c'' are not legal di-
gits for a decimal number ; similarly, "2," ''3,'' and "4" are not
legal for a binary number .)

0 9 .4 %OUT Directive
Syntax

% OUT text

The %OUT directive directs MASM to display the text at the user's
terminal . The directive is useful for displaying messages during
specific points of a long assembly .

The ¶OUT directive generates output for both assembly passes .

The IF1 and IF2 directives can be used to control when the directive
is processed .

%OUT First Pass -- Okay

Microsoft Macro Assembler Reference Manual

9 .5 NAME Directive
Syntax

NAME module-name

The NAME directive sets the name of the current module to

module-name. A module name is used by the linker when displaying
error messages .

The module-name can be any combination of letters and digits .

Although the name can be any length, only the first six characters
are used . The name must be unique and not be a reserved word .

Example

name main

If the NAME directive is not used, MASM creates a default module

name using the first six characters of a TITLE directive . If no TI-
TLE directive is found, the default name ''A" is used .

9 .6 TITLE Directive
0
Syntax

TITLE text

The TITLE directive defines the program listing title . It directs

MASM to copy text to the first line of each new page in the program
listing . The text can be any combination of characters up to 60 char-
acters in length .

No more than one TITLE directive per module is allowed .

Example

title PROG1 -- 1st Program

Note that the first six non-blank characters of the title will be used
as the module name if the module does not contain a NAME direc-
9
tive .


File Control

9 .7 SUBTITLE Directive
• Syntax

SUBTTL text

The SUBTTL directive defines the listing subtitle . It directs MASM

to copy text to the line immediately after the title on each new page
in the program listing . The text can be any combination of charac-
ters . Only the first 60 characters are used . If no characters are
given, the subtitle line is left blank .

Any number of SUBTTL directives can be given in a program . Each

new directive replaces the current subtitle with the new text .

Examples

subttl SPECIAL I/0 ROUTINE

This example creates the subtitle "SPECIAL I/O ROUTINE ."

0 subttl

This example creates a blank subtitle .

9 .8 PAGE Directive
Syntax

PAGE length, width

PAGE +
PAGE

The PAGE directive sets the line length and character width of the
program listing, increments section page numbering, or generates a
page break in the listing .

If a length and width are given, PAGE sets the maximum number of
lines per page to length, and the maximum number of characters per
line to width . The length must be in the range 10 to 255 . The de-
fault is 50 . The width must be in the range 60 to 132 . The default is
80 . A width can be given without a length as long as the comma (,)
precedes the width .
Microsoft Macro Assembler Reference Manual

If a plus sign (+) is given, PAGE increments the section number and
resets the page number to 1 . Program listing page numbers have the
form :

section-minor
0
By default, page numbers start at 1-1 .

If no argument is given, PAGE starts a new output page in the pro-

gram listing . It copies a form feed character to the file and gen-
erates a title and subtitle line .

Examples

PAGE

This example creates a page break .

PAGE 58,60

This example sets the maximum page length to 58 lines, and the
maximum width to 60 characters .

PAGE ,132
0
This example sets the maximum width to 132 characters . The
current page length remains unchanged .

PAGE +

This example increments the current section number and sets the
page number to 1 .

9 .9 LIST and .XLIST Directives

Syntax

.LIST
.XLIST

The LIST and .XLIST directives control which source program lines
0
are copied to the program listing . The .XLIST directive suppresses
copying of subsequent source lines to the program listing . The LIST
 File Control

directive restores copying . The directives are typically used in pairs

to prevent a section of a given source file from being copied to the

0 program listing .

The .XLIST directive overrides all other listing directives .

Example

.XLIST
;listing suspended here
.LIST
;listing resumes here

9 .10 SFCOND LFCOND,

and .TFCdND Directives
Syntax

.SFCOND
0 .LFCOND
.TFCOND

The SFC'OND and .LFCOND directives determine whether or not

conditional blocks should be listed . The SFC'OND directive
suppresses the listing of any subsequent conditional blocks whose IF
condition is false . The LFC'OND directive restores the listing of
these blocks . The directives can be used like .LIST and .XLIST to
suppress listing of the conditional blocks in sections of a program .

The TFCONI) directive sets the default mode for listing of condi-
tional blocks . This directive works in conjunction with the -X op-
tion of the assembler . If -X is not given in the NASNI command
line, TFC'OND causes false conditional blocks to be listed by de-
fault . If -X is given, .TFCOND causes false conditional blocks to be
suppressed .

0 7
Microsoft Macro Assembler Reference Manual

Examples

.SFCOND
IF 0
;This block will not be listed .
0
ENDIF
.LFCOND
IF 0
;This block will be listed .
END IF

9 .11 LALL, .XALL, and .SALL Directives

Syntax

.LALL
.XALL
.SALL

The LALL, XALL, and SALL directives control the listing of the
statements in macros that have been expanded in the source file .
MASM always lists the full macro definition, but lists macro expan-
0
sions only if the appropriate directive is set .

The .LALL directive causes MASM to list all the source statements
in a macro, including comments preceded by a single semicolon ( ;)
but not those preceded by a double semicolon ( ; ;) . The XALL direc-
tive lists only those source statements that generate code or data, so
comments are ignored .

The SALL directive suppresses listing of all macro expansions .

That is, MASM copies the macro call to the source listing, but does
not copy the source lines that the call generates .

.XALL is in effect when MASM first begins execution .

0
 File Control

;No macros listed here .

;Macros listed in full .

;Macros listed by generated code or data only .

9 .12 CREF and .XCREF Directives

Syntax

.CREF
.XCREF name,,,

The CREF and XCREF directives control the generation of cross

references for the macro assembler's cross-reference file . The
.XCREF directive suppresses the generation of label, variable, and
0 symbol cross references . The CREF function restores this genera-
tion .

If a name is given with XCREF, only that label, variable, or symbol

will be suppressed . All other names will be cross referenced . The
named label, variable, or symbol will also be omitted from the sym-
bol table of the program listing . If two or more names are be given,
they must be separated with commas .

Example

.XCREF one, two, three

0
 Appendix A
Instruction Summary

A .1 Introduction A-1

A .2 8086 Instructions A-2

A .3 8087 Instruction Mnemonics A-7

A .4 186 Instruct ion Mnemonics A-t)

A .5 286 Non-Prot ect ed

Instruction Mnemonics A-10

A .6 286 Protected Instruction Mnemonics A-10

0 A .7 287 Instruct Ion Mnemonics A-I1
S

Instruction Summary

0 A .1 Introduction
MASM is an assembler for the 8086/186/286 family of microproces-
sors, capable of assembling instructions for the 8086, 186, and 286 mi-
croprocessors and the 8087 and 287 floating point coprocessors .
MASM will assemble any program written for an 8086, 186, or 286 mi-
croprocessor environment as long as the program uses the instruction
syntax described in this chapter .

By default, MASM recognizes 8086 and 8087 instructions only . If a

source program contains 186, 286, or 287 instructions, one or more In-
struction Set directives must be used in the source file to enable assem-
bly of the instructions . The following sections list the syntax of all in-
structions recognized by MASM and the Instruction Set directives .

Abbreviations used in the syntax descriptions are :

Symbol Meaning
accum accumulator : AX or AL
reg byte or word register
byte : AL, AH, BL, BH, CL, CH, DL, DH
word : AX, BX, CX, DX, SI, DI, BP, SP
segreg segment register : CS, DS, SS, ES
r/m general operand : register, memory address, indexed
operand, based operand, or based indexed operand
immed 8- or 16-bit immediate value : constant or symbol
mem memory operand : label, variable, or symbol
label instruction label
Microsoft Macro Assembler Reference Manual

A .2 8086 Instructions
The following is a complete list of the 8086 instructions . MASM as-
sembles all 8086 instructions by default . 0
Syntax Action
AAA ASCII adjust for addition
AAD ASCII adjust for division
AAM ASCII adjust for multiplication
AAS ASCII adjust for subtraction
ADC accum, immed Add immediate with carry to accumulator
ADC r/m, immed Add immediate with carry to operand
ADC r/m, reg Add register with carry to operand
ADC reg, r/m Add operand with carry to register
ADD accum, immed Add immediate to accumulator
ADD r/m, immed Add immediate to operand
ADD r/m, reg Add register to operand
ADD reg, r/m Add operand to register
AND accum, immed Bitwise And immediate with accumulator
AND r/m, immed Bitwise And immediate with operand
AND r/m, reg Bitwise And register with operand
AND reg, r/m
CALL label
Bitwise And operand with register
Call instruction at label
0
CALL r/m Call instruction indirect
CBW Convert byte to word
CLC Clear carry flag
CLD Clear direction flag
CLI Clear interrupt flag
CMC Complement carry flag
CMP accum, immed Compare immediate with accumulator
CMP r/m, immed Compare immediate with operand
CMP r/m, reg Compare register with operand
CMP reg, r/m Compare operand with register
CMPS src, dent Compare strings
CMPSB Compare strings byte for byte
CMPSW Compare strings word for word
CWD Convert word to double word
DAA Decimal adjust for addition
DAS Decimal adjust for subtraction
DEC r/m
DEC reg
D IV r/m
Decrement operand
Decrement 16-bit register
Divide accumulator by operand
0
ESC immed, r/m Escape with 6-bit immediate and operand
HLT Halt
 Instruction Summary

IDLY r/m Integer divide accumulator by operand

IMUL r/m Integer multiply accumulator by operand
IN accum, immed Input from port (8-bit immediate)
IN accum,DX Input from port given by DX
INC r/m Increment operand
INC reg Increment 16-bit register
INT 3 Software interrupt 3 (encoded as one byte)
INT immed Software Interrupt 0 through 255
INTO Interrupt on overflow
IRET Return from interrupt
JA label Jump on above
JAE label Jump on above or equal
JB label Jump on below
JBE label Jump on below or equal
JC label Jump on carry
JCXZ label Jump on CA zero
JE label Jump on equal
JG label Jump on greater
JGE label Jump on greater or equal
JL label Jump on less than
JLE label Jump on less than or equal

0 JMP label
JMP r/m
JNA label
Jump to instruction at label
Jump to instruction indirect
Jump on not above
JNAE label Jump on not above or equal
JNB label Jump on not below
JNBE label Jump on not below or equal
JNC label Jump on no carry
JNE label Jump on not equal
JNG label Jump on not greater
JNGE label Jump on not greater or equal
JNL label Jump on not less than
JNLE label Jump on not less than or equal
JNO label Jump on not overflow
JNP label Jump on not parity
JNS label Jump on not sign
JNZ label Jump on not zero
JO label Jump on overflow
JP label Jump on parity
JPE label Jump on parity even
JPO label Jump on parity odd
JS lahrl Jump on sign
JZ lahrl Jump on zero
LAHF Load AH with flags
Microsoft Macro Assembler Reference Manual

LDS r/m Load operand into DS

LEA r/m Load effective address of operand
LES r/m
LOCK
LODS src
Load operand into ES
Lock bus
Load string
0
LODSB Load byte from string into AL
LODSW Load word from string into AX
LOOP label Loop
LOOPE label Loop while equal
LOOPNE label Loop while not equal
LOOPNZ label Loop while not zero
LOOPZ label Loop while zero
MOV accurn, mem Move memory to accumulator
MOV mem, accum Move accumulator to memory
MOV r/m, immed Move immediate to operand
MOV r/m, reg Move register to operand
MOV r/m, segreg Move segment register to operand
MOV reg, immed Move immediate to register
MOV reg, r/m Move operand to register
MOV segreg, r/rn Move operand to segment register
MOVS dent, src Move string
MOVSB
MOVSW
MUL r/m
Move string byte by byte
Move string word by word
Multiply accumulator by operand
9
NEG r/m Negate operand
NOP No operation
NOT r/m Invert operand bits
OR accurn, imined Bitwise Or immediate with accumulator
OR r/m, immed Bitwise Or immediate with operand
OR r/m, reg Bitwise Or register with operand
OR reg, r/rn Bitwise Or operand with register
OUT DX, accum Output to port given by DX
OUT immed, accum Output to port (8-bit immediate)
POP r/m Pop 16-bit operand
POP rep Pop 16-bit register from stack
POP segreg Pop segment register
POPF Pop flags
PUSH r/m Push 16-bit operand
PUSH rep Push 16-bit register onto stack
PUSH segreg
PUSHF
RCL r/m, 1
Push segment register
Push flags
Rotate left through carry by I bit
0
RCL r/m, CL Rotate left through carry by CL
RCR r/m,1 Rotate right through carry by 1 bit

A 4
 Instruction Summary

RCR r/m, CL Rotate right through carry by CL

REPE Repeat if equal

0 REP NE
REPNZ
REPZ
Repeat if not equal
Repeat if not zero
Repeat if zero
RET [ roamed] Return after popping bytes from stack
ROL r/m, 1 Rotate left by 1 bit
ROL r/m, CL Rotate left by CL
ROR r/m, 1 Rotate right by 1 hit
ROR r/m, CL Rotate right by CL
SAHF Store All into flags
SAL r/m, 1 Shift arithmetic left by 1 bit
SAL r/n, CL Shift arithemetic left by CL
SAR r/m, 1 Shift arithmetic right by I bit
SAR r/m, CL Shift arithmetic right by CL
SBB accum, immed Subtract immediate and carry flag
SBB r/m, immed Subtract immediate and carry flag
SBB r/m, reg Subtract register and carry flag
SBB reg, r/m Subtract operand and carry flag
SCAS deet Scan string
SCASB Scan string for byte in AL
0 SCASW
SHL r/m, 1
SHL r/m, CL
Scan string for word in AX
Shift left by 1 bit
Shift left by CL
S H R r/m, 1 Shift right by 1 bit
S H R r/in, C L Shift right by CL
STC Set carry flag
STD Set direction flag
STI Set interrupt flag
STOS de ,, t Store string
STOSB Store byte in AL at st ring
STOSW Store word in AX at string
SUB accum, immrd Subtract imeediate from accumulator
SUB r/m, immed Subtract immediate from operand
SUB r/m, reg Subtract register from operand
SUB reg, r/m Subtract operand from register
TEST aceum, immed Compare immediate bits with accumulator
TEST r/m, immed Compare immediate bits with operand
TEST r/m, reg Compare register bits with operand
TEST reg, r/m Compare operand bits with register
WAIT Wait
XCHG accum, reg Exchange accumulator with register
XCHG r/m, reg Exchange operand with register
XCHG reg, accum Exchange register with accumulator


Microsoft Macro Assembler Reference Manual

XCHG reg, r/m Exchange register with operand

XLAT mcm Translate
XOR accum, immed
XOR r/m, immed
XOR r/m, reg
Bitwise Xor immediate with accumulator
Bitwise Xor immediate with operand
Bitwise Xor register with operand
0
XOR reg, r/m Bitwise Xor operand with register

The String instructions (CMPS, LODS, MOVS, SCAS, and STOS) use
the DS, SI, ES, and DI registers to compute operand locations . Source
operands are assumed to be at DS :[SI] ; destination operands at
ES :[DI] . The operand type (BYTE or WORD) is defined by the in-
struction mnemonic . For example, CMPSB specifies BYTE operands
and CMPSW specifies WORD operands . For the CMPS, LODS,
MOVS, SCAS, and STOS instructions, the src and dest operands are
dummy operands that define the operand type only . The offsets asso-
ciated with these operands are not used . The src operand can also be
used to specify a segment override . The ES register for the destination
operand cannot be overridden .

Examples

Imps
lods
mov
word ptr string, word ptr es :0
byte ptr string
byte ptr es :O, byte ptr string
0
The REP, REPE, REPNE, REPNZ, or REPZ instructions provide a
way to repeatedly execute a String instruction for a given count or
while a given condition is true . If a Repeat instruction immediately
precedes a String instruction (both instructions must be on the same
line), the instructions are repeated until the specified repeat condi-
tion is false, or the CA register is equal to zero . The Repeat instruc-
tion decrements CX by one for each execution .

Example

mov cx, 10
rep scasb

In this example, SCASB is repeated ten times .

0
 Instruction Summary

A .3 8087 Instruction Mnemonics

0 The following is a list of the 8087 instructions . MASH assembles all

8087 instructions by default .

Syntax Action
F2XM1 Calculate 2x-1
FABS Take absolute value of top of stack
FADD Add real
FADD fn rm Add real from memory
FADD ST, ST(t) Add real from stack
FADD ST(), ST Add real to stack
FADDP ST i), ST Add real and pop stack
FBLD in r»t Load 10-byte packed decimal on stack
FBSTP ntem Store 10-byte packed decimal and pop
FCHS Change sign on the top stack element
FCLEX Clear exceptions after WAIT
FCOM Compare real
FCOM ST Compare real with top of stack
FCOM ST(,) Compare real with stack
FCOMP Compare real and pop stack
0 FCOMP ST
FCOMP ST()
FCOMPP
Compare real with top of stack and pop
Compare real with stack and pop stack
Compare real and pop stack twice
FDECSTP Decrement stack pointer
FDISI Disable interrupts after AWAIT
FDIV Divide real
FDIV nu in Divide real from memory
FDIV ST, ST(i) Divide real from stack
FDIV ST(i), ST Divide real in stack
FDIVP ST(i), ST Divide real and pop stack
FDIVR Reversed real divide
FDIVR nrr m Reverse real divide from memory
FDIVR ST, ST(i) Reverse real divide from stack
FDIVR ST(i), ST Reverse real divide in stack
FDIVRP ST(i), ST Reversed real divide and pop stack twice
FENI Enable interrupts after AWAIT
FFREE Free stack element
FFREEST Free top of stack element
FFREE ST() Free ith stack element
FIADD m c tit Add 2 or 4-byte integer
FICOM inrm 2 or 4-byte integer compare
FICOMP mem 2 or 4-byte integer compare and pop stack
FIDIV mem 2 or 4-byte integer divide
Microsoft Macro Assembler Reference Manual

FIDIVR mem Reversed 2 or 4-byte integer divide

FILD lnem Load 2, 4, or 8-byte integer on stack
FIMUL mem
FINCSTP
FINIT
2 or 4-byte integer multiply
Increment stack pointer
Initialize processor after WAIT
is
FIST mem Store 2 or 4-byte integer
FISTP mem Store 2, 4, or 8-byte integer and pop stack
FISUB inem 2 or 4-byte integer subtract
FISUBR mem Reversed 2 or 4-byte integer subtract
FLD mem Load 4, 8, or 10-byte real on stack
FLD1 Load +1 .0 onto top of stack
FLDCW mem Load control word
FLDENV mem Load 8087 environment (14-bytes)
FLDL2E Load loge onto top of stack
FLDL2T Load log,10 onto top of stack
FLDLG2 Load logl 2 onto top of stack
FLDLN2 Load log e 4 onto top of stack
FLDPI Load pi onto top of stack
FLDZ Load +0 .0 onto top of stack
FMUL Multiply real
MUL morn Multiply real from memory
FMUL ST, ST(i)
FMUL ST(), ST
FMULP ST(i), ST
Multiply real from stack
Multiply real to stack
Multiply real and pop stack
0
FNCLEX Clear exceptions with no WAIT
FNDISI Disable interrupts with no WAIT
FNENI Enable interrupts with no WAIT
FNINIT Initialize processor, with no WAIT
FNOP No operation
FNSAVE mem Save 8087 state (94 bytes) with no WAIT
FNSTCW mem Store control word with no WAIT
FNSTENV mem Store 8087 environment with no WAIT
FNSTSW mem Store 8087 status word with no WAIT
FPATAN Partial arctangent function
FPREM Partial remainder
FPTAN Partial tangent function
FRNDINT Round to integer
FRSTOR mem Restore 8087 state (94 bytes)
FSAVE mini Save 8087 state (91 bytes) after WAIT
FSCALE
FSQRT
FST
Scale
Square root
Store real
0
FST ST Store real from top of stack
FST ST(i) Store real from stack
 Instruction Summary

FSTCW mum Store control word with WAIT

FSTENV mem Store 8087 environment after WAIT

0 FSTP mem
FSTSW mem
FSUB
Store 4, 8, or 10-byte real and pop stack
Store 8087 status word after WAIT
Subtract real
FSUB mem Subtract real from memory
FSUB ST, ST(,) Subtract real from stack
FSUB ST(i), ST Subtract real to stack
FSUBP ST(i), ST Subtract real and pop stack
FSUBR Reversed real subtract
FSUBR mum Reversed real subtract from memory
FSUBR ST, ST(i) Reversed real subtract from stack
FSUBR ST(,), ST Reversed real subtract in stack
FSUBRP ST(i), ST Reversed real subtract and pop stack
FTST Test top of stack
FWAIT Wait for last 8087 operation to complete
FXAM Examine top of stack element
FXCH Exchange contents of stack elements
FFREE ST Exchange top of stack element
FFREE ST(i) Exchange top of stack and ith element
FXTRACT Extract exponent and significand

0 FYL2X
FYL2PI
Calculate Y log,,x
Calculate Y log,`(x+1)

A .4 186 Instruction Mnemonics

The 186 instruction set consists of all 8086 instructions plus the fol-
lowing instructions . The .186 directive can be used to enable these
instructions for assembly .

Syntax Action
BOUND reg, mem Detect value out of range
ENTER immedl6, immedS Enter procedure
INS mum, DX Input string from port DX
INSB mum, DX Input byte string from port DX
IN SW in( tit, DX Input word string from port I)X
LEAVE Leave procedure
OUTS DX, m e m Output byte/word/string to port DX
OUTSB DX, mun Output byte string to port DX
OUTSW DX, mrm Output word string to port DX
PUSHA Push all registers
POPA Pop all registers

n 0


Microsoft Macro Assembler Reference Manual

A .5 286 Non-Protected Instruction Mnemonics

The 286 non-protected instruction set consists of all 8086 instruc-
tions plus the following instructions . The .286c directive can be
used to enable these instructions for assembly .
0
Syntax Action
BOUND reg, mem Detect value out of range
ENTER immedl6, immedS Enter procedure
INS mint, DX Input string from port DX
INSB mcin, DX Input byte string from port DX
INSW m(m, DX Input word string from port DX
LEAVE Leave procedure
OUTS DX, mrm Output byte/word/string to port DX
OUTSB DX, mem Output byte string to port DX
OUTSW DX, mem Output word string to port DX
PUSHA Push all registers
POPA Pop all registers

A .6 286 Protected Instruction Mnemonics

The 286 protected instruction set consists of all 8086 and 286 non-
protected instructions plus the following instructions . The .286p
directive can be used to enable these instructions for assembly .
0
Syntax Action
ARPL mem, reg Adjust requested privilege level
CLTS Clear task switched flag
LAR reg, mem Load access rights
LGDT mem Load global descriptor table (8 bytes)
LIDT mem Load interrupt descriptor table
LLDT nit m Load local descriptor table
LMSW mem Load machine status word
LSL reg, mem Load segment limit
LTR mem Load task register
SGDT mem Store global descriptor table (8 bytes)
SIDT mcm Store interrupt descriptor table (8 bytes)
SLDT mem Store local descriptor table
SMSW mem Store machine status word
STR hum
VERR mem
VERW mem
Store task register
Verify read access
Verify write access
0


Instruction Summary

A .7 287 Instruction Mnemonics

0 The 287 instruction set consists of all 8087 instructions plus the fol-
lowing additional instructions . The .287 directive can be used to en-
able these instructions for assembly .

Syntax Action
FSETPM Set Protected Mode
FSTSW AX Store Status Word in AX (wait)
FNSTSW AX Store Status Word in AX (no-wait)

0
0

0
 Appendix B
Directive Summary

B.1 Introduction B-1

0
S

Directive Summary

B .1 Introduction
Directives give the assembler directions and information about input
and output, memory organization, conditional assembly, listing and
cross-reference control, and definitions . There are the following direc-
tives :

.186 ELSE IFDIF PROC

.286c END IFE PUBLIC
.286p ENDIF IFIDN RADIX
.287 ENDP IFNB RECORD
.8086 ENDS IFNDEF SALL
.8087 EQU INCLUDE SEGMENT
EVEN LABEL SFCOND
ASSUME EXTRN .LALL STRUC
COMMENT GROUP .LFCOND SUBTTL
.CREF IF .LIST TFCOND
DB IF1 NAME TITLE
0 DD
DQ
IF2
IFB
ORG
OUT
XALL
XCREF
DT IFDEF PAGE XLIST
DW

Any combination of upper and lowercase letters can be used when giv-
ing directive names in a source file .

The following is a complete list of directive syntax and function .

.186 Enables assembly of 186 instructions .

.288c Enables assembly of 286 unprotected instruc-

tions .

• 286p Enables assembly of 286 protected instruc-

tions .

• 287 Enables assembly of 287 instructions .

.8088 Enables assembly of 8086 instructions while

disabling assembly of 186 and 286 instruc-
tions .


Microsoft Macro Assembler Reference Manual

.8087 Enables assembly of 8087 instructions while

disabling assembly of 287 instructions .

name = expression
Assigns the numeric value of expression to
0
name .

ASSUME seg-reg : seg-name,,,

Selects the given segment register seg-reg to
be the default segment register for all symbols
in the named segment or group . If seg-name is
NOTHING, no register is selected .

COMMENT delim text delim

Treats all text between the given pair of delim-
iters delim as a comment .

.CREF Restores listing of symbols in the cross-

reference listing file .

( name] DB initial-value,,,
Allocates and initializes a byte (8 bits) of
storage for each initial- value .
0
[name] DW initial-value,,,
Allocates and initializes a word (2 bytes) of
storage for each given initial-value.

[name] DD initial-value,,,
Allocates and initializes a doubleword (4
bytes) of storage for each given initial-value .

[name] DQ initial-value,,,
Allocates and initializes a quadword (8 bytes)
of storage for each given initial-value .

[ name] DT initial-value,,,
Allocates and initializes 10 bytes of storage
for each given initial-value .

ELSE Marks the beginning of an alternate block

within a conditional block .
0


Directive Summary

END ( expression]
Marks the end of the module and optionally
0 ENDIF
sets the program entry point to expression .

Terminates aeon ditional block .

name EQU expression

Assigns the expressionto thegiven name .

name ENDP Marks the end of a procedure definition .

name ENDS Marks the end of a segment or structure type

definition .

EVEN If necessary, increments the location counter

to an even value and generates one NOP in-
struction (90h)

EXTRN name : type,,,

Defines an external variable, label, or symbol

0 named name and whose type is type .

name GROUP seg-name,,,

Associates a group name name with one or
more segments .

IF expression Grants assembly if the expression is non-zero

(true) .

IF 1 Grants assembly on pass 1 only .

IF2 Grants assembly on pass 2 only .

IFB < arg > Grants assembly if the arg is blank .

IFDEF name Grants assembly if name is a previously de-

fined label, variable, or symbol .

IFDIF < argl >, < arg2 >

s Grants assembly if the arguments are dif-

ferent .

IFE expression Grants assembly if the expression is 0 (false) .

Microsoft Macro Assembler Reference Manual

IF1DN < ' Ygl >, < arg2 >

Grants assembly if the arguments are identi-
cal .

IFNB < arg > Grants assembly if the argis not blank .
0
IFNDEF name
Grants assembly if name has not yet been de-
fined .

INCLUDE filename
Inserts source code from the source file given
by filename into the current source file during
assembly .

name LABEL type

Creates a new variable or label by assigning
the current location counter value and the
given type to name .

.LALL Lists all statements in a macro .

.LFCOND Restores the listing of conditional blocks .

0
.LIST Restores listing of statements in the program
listing .

NAME module-name
Sets the name of the current module to
module-name .

ORG expression
Sets the location counter to expression .

%OUT text Displays text at the user's terminal .

name PROC type

Marks the beginning of a procedure defini-
tion .

PUBLIC name,,,
Makes the variable, label, or absolute symbol
0
given by name available to all other modules
in the program .


Directive Summary

.RADIK expression
Sets the input radix for numbers in the source

s file to expression .

reeordnarne RECORD fieldname : width [= exP1999

Defines an record type for a 8- or 16-bit record
that contains one or more fields .

.SALL Suppresses listing of all macro expansions .

name SEGMEN' align combine ' class'

Marks the beginning of a program segment
named name and having segment attributes
align, combine, and class .

.SFCOND Suppresses listing of any subsequent condi-

tional blocks whose IF condition is false .

name STRUC Marks the beginning of a type definition for a

structure .

0 PAGE length, width

Sets the line length and character width of the
program listing .

PAGE + Increments section page numbering .

PAGE Generates a page break in the listing .

SUBTTL text Defines the listing subtitle .

.TFCOND Sets the default mode for listing of conditional

blocks .

TITLE text Defines the program listing title .

Microsoft Macro Assembler Reference Manual

.XALL Lists only those macro statements that gen-

erate code or data .

.XCREF name,,,
Suppresses the listing of symbols in the cross-
0
reference listing file .
.XLIST Suppresses listing of subsequent source lines
to the program listing .

0
 Appendix C
Segment Names
For High-Level Languages

C .1 Introduction C-1

C.2 Text Segments C-2

C .3 Data Segments -Near C-4

C .4 Data Segments -Far C-5

C .5 Bss Segments C-6

C .6 Constant Segments
0 C-8
S

Segment Names For High-Level Languages

0 C .1 Introduction
This appendix describes the naming conventions used to form assem-
bly language source files that are compatible with object modules pro-
duced by the Microsoft C, Pascal, and Fortran language compilers
(version 3 .0 or later) .

High-level language modules have the following four predefined seg-

ment types :

TEXT for program code

DATA for program data
BSS for uninitialized space
CONST for constant data

Any assembly language source file that is to be assembled and linked

to a high-level language module must use these segments as described

0 in the following sections .

high-level language modules also have three different memory models :

Small for single code and data segments

Middle for multiple code segment but a single data segment
Large for multiple code and data segments

Assembly language source files to be assembled for a given memory

model must use the naming conventions given in the following sec-
tions .


Microsoft Macro Assembler Reference Manual

C .2 Text Segments
Syntax

nameTEXT SEGMENT BYTE PUBLIC 'CODE'

0
statements
nameTEXT ENDS

A text segment defines a module's program code . It contains state-

ments that define instructions and data within the segment . A text
segment must have the name nameTEXT, where name can be any
valid name . For middle and large module programs, the module's own
name is recommended . For small model programs, only "TEXT" is
allowed .

A segment can contain any combination of instructions and data

statements . These statements must appear in an order that creates a
valid program . All instructions and data addresses in a text segment
are relative to the CS segment register . Therefore, the statement

assumecs : nameTEXT

must appear at the beginning of the segment . This statement ensures

0
that each label and variable declared in the segment will be associated
with the C'S segment register (see the section, ''ASSUME Directive" in
Chapter 3) .

Text segments should have "BYTE" alignment and "PUBLIC" com-

bination type, and must have the class name 'CODE .'' These define
loading instructions that are passed to the linker . Although other seg-
ment attributes are available, they should not be used . For a complete
description of the attributes, see the section, ''SEGMENT and ENDS
Directives,'' in Chapter 3 .

Small Model Programs . Only one text segment is allowed . The seg-
mentt must not exceed 64 Kbytes . If the segment's complete definition
is distributed among several modules, the statement

IGROUP group TEXT

should be used at the beginning of each module to ensure that the seg-
ment is placed in a single 64 Kbyte physical segment . All procedure
0
and statement labels should have the NEAR type .


Segment Names For High-Level Languages

Example

0 IGROUP group _TEXT

assume cs :IGROUP

_TEXT segment byte public 'CODE'

main proc near

_main endp
TEXT ends

Middle and Large Model Programs . Multiple text segments are al-
lowed, however, no segment can be greater than 64 Kbytes . To dis-
tinguish one segment from another, each should have its own name .
Since most modules contain only one text segment, the module's
name is often used as part of the text segment's name . All pro-
cedure and statement labels should have the FAR type, unless they
will only be accessed from within the same segment
0 Example

SAMPLE- TEXT segment byte public 'CODE'

assume cs :SAMPLE _ TEXT
_main proc far

main endp
SAMPLE TEXT ends


Microsoft Macro Assembler Reference Manual

C .3 Data Segments -Near

Syntax
40
-DATA SEGMENT WORD PUBLIC 'DATA'
statements
-DATA ENDS

A near data segment defines initialized data that is in the segment

pointed to by the DS segment register when the program starts exe-
cution . The segment is "near" because all data in the segment is ac-
cessible without giving an explicit segment value . All programs have
exactly one near data segment . Only large model programs can have
additional data segments .

A near data segment's name must be "-DATA ." The segment can
contain any combination of data statements defining variables to be
used by the program . The segment must not exceed 64 Kbytes of
data . All data addresses in the segment are relative to the prede-
fined group ''DGROUP" . Therefore, the statements

DGROUP group J)ATA

0
assume ds : DGROUP

must appear at the beginning of the segment . These statements en-

sure that each variable declared in the data segment will be associat-
ed with the DS segment register and DGROUP (see the sections,
"ASSUME Directive'' and "GROUP Directive" in Chapter 3) .

Near data segments must be "WORD" aligned, must have "PUB-

LIC'' combination type, and must have the class name "DATA ."
These define loading instructions that are passed to the linker .
Although other segment attributes are available, they must not be
used . For a complete description of the attributes, see the section,
"SEGMENT and ENDS Directives,'' in Chapter 3 .


Segment Names For High-Level Languages

Example

0 DGROUP group _DATA

assume ds : DGROUP

DATA segment word public DATA'

count dw 0
array dw 10 dup(1)
string db "Type CANCEL then press RETURN", Oah, 0
DATA ends

C .4 Data Segments - Far

Syntax

name -D ATA SEGMENT WORD PUBLIC 'FARJ)ATA'

statements
nameJ)ATA ENDS

0 A far data segment defines data or data space that can be accessed
only by specifying an explicit segment value . Only large model pro-
grams can have far data segments .

A far data segment's name must be namei)ATA, where name can be

any valid name . The name of the first variable declared in the seg-
ment is recommended . The segment can contain any combination of
data statements defining variables to be used by the program . The
segment must not exceed 64 Kbytes of data . All data addresses in
the segment are relative to the ES segment register . When accessing
a variable in a far data segment, the ES register must be set to the
appropriate segment value . Also, the segment override operator
must be used with the variable's name (see the section, ''Attribute
Operators" in Chapter 5) .

Far data segments must be "WORD" aligned, must have ''PUB-

LIC'combination type, and should have the class name
"FAR-DATA ." These define loading instructions that are passed to
the linker . Although other segment attributes are available, they
must not be used . For a complete description of the attributes, see
the section, "SEGMENT and ENDS Directives," in Chapter 3 .


Microsoft Macro Assembler Reference Manual

Example

ARRAY DATA
array dw
dw
segment
0
1
word public 'FAR - DATA'
0
dw 2
dw 4
table dw 1600 dup(?)
ARRAY DATA ends

C .5 Bss Segments
Syntax

.J3SS SEGNIENT WORD PUBLIC'BSS'

statements
J3SS ENDS

A bss segment defines uninitialized data space . A bss segment's

name must be " .J3SS ." The segment can contain any combination of
data statements defining variables to be used by the program . The
0
segment must not exceed 64 Kbytes . All data addresses in the seg-
ment are relative to the predefined group ''DGROUP'' . Therefore,
the statements

DGROUP group J3SS

assume (is : DGROUP

must appear at the beginning of the segment . These statements en-

sure that each variable declared in the bss segment will be associat-
ed with the DS segment register and DGROUP (see the sections,
"ASSUME Directive" and "GROUP Directive" in Chapter 3) .

0
 Segment Names For High-Level Languages

0 Note

The group name DGROUP must not be defined in more than one
GROUP directive in a source file . If a source file contains both a
DATA and BSS segment, the directive

DGROUP group J)ATA, _BSS

should be used .

A bss segment must be "WORD" aligned, must have "PUBLIC"

combination type, and must have the class name "BSS ." These de-
fine loading instructions that are passed to the linker . Although
other segment attributes are available, they must not be used . For a
complete description of the attributes, see the section, ''SEGMENT
and ENDS Directives,'' in Chapter 3 .

Example
0 DGROUP group _BSS
assume ds : DGROUP

_BSS segment word public 'BSS'

count dw ?
array dw 10 dup(?)
string db 30 dup(?)
_BSS ends


Microsoft Macro Assembler Reference Manual

C .6 Constant Segments
Syntax

CONST SEGMENT WORD PUBLIC 'CONST'

is
statements
CONST ENDS

A constant segment defines constant data that will not change dur-
ing program execution . Constant segments are typically used in
large model programs to hold the segment values of far data seg-
ments .

The constant segment's name must be "CONST ." The segment can
contain any combination of data statements defining constants to be
used by the program . The segment must not exceed 64 Kbytes . All
data addresses in the segment are relative to the predefined group
"DGROUP'' . Therefore, the statements

DGROUP group CONST

assume ds : DGROUP

must appear at the beginning of the segment . These statements en-

0
sure that each variable declared in the constant segment will be as-
sociated with the DS segment register and DGROUP (see the sec-
tions, "ASSUME Directive" and "GROUP Directive" in Chapter 3) .

Note

The group name DGROUP must not be defined in more than one
GROUP directive in a source file . If a source file contains a
DATA, BSS, and CONST segment, the directive

DGROUP group -DATA, BSS, CONST

should be used .

Segment Names For High-Level Languages

A constant segment must be "WORD" aligned, must have "PUB-

LIC" combination type, and must have the class name "CONST ."
0 These define loading instructions that are passed to the linker .
Although other segment attributes are available, they must not be
used . For a complete description of the attributes, see the section,
"SEGMENT and ENDS Directives," in Chapter 3 .

Example

DGROUP group CONST

assume ds : DGROUP

CONST segment word public 'CONST'

segi dw ARRAY _DATA
seg2 dw MESSAGE DATA
CONST ends

In this example, the constant segment receives the segment values of

two far data segments : ARRAY-DATA and MESSAGE-DATA .
These data segments must be defined elsewhere in the module .

s
0

Index
segment override Conditional assembly (continued)
operator 5-15 on blank arguments 7-3
= directive 4-8 on defined symbols 7-3
on expressions 7-2
on identical arguments 7-4
ABS type 6-3 Constant Operands 5-2
Absolute (AT) segments 3-7 constants, default radix 9-2
Alignment .CREF directive 9-9
EVEN directive 3-12 Cross-reference listing 9-9
ORG directive 3-11
segments 3-6
AND operator 5-13 Data
Arithmetic operators 5-10 bytes 4-3
Assembly listing doublewords 4-4
false conditionals 9-7 quadwords 4-5
macros 9-8 ten-byte words 4-6
page breaks 9-5 words 4-3
page dimensions 9-5 DB directive 4-3

0 subtitle 9-5
suppressing 9-6
symbols 9-9
DD directive 4-4
Declarations
byte data 4-3
title 9-4 doubleword data 4-4
ASSUME directive 3-10 label 4-1
AT segments 3-7 quadword data 4-5
record 4-15
structure 4-14
Based indexed operands 5-7 ten-byte words 4-6
Based operands 5-5 word data 4-3
Bitwise operators 5-13 Default input radix 9-2
Default segment registers 3-10
Direct memory operands 5-2
Character Set 2-1 Directives, summary B-1
Class argument 3-7 DQ directive 4-5
Combine argument 3-6 DT directive 4-6
COMMENT directive 2-8 DW directive 4-3
Comments 2-7, 2-8

s COMMON segments 3-6

Conditional assembly
directives 7-1
nesting 7-2
END directive 3-8
ENDM directive 8-8,8-10
ENDP directive 3-12
on assembly passes 7-2 ENDS directive 3-4, 4-11
Index

Entry point 3-8 Label declarations 4-1

EQ operator 5-12 LABEL directive 4-10
EQU directive 4-9 Labels
EVEN directive 3-12
Expressions 5-10
external symbols 6-3
near 4-1
procedure 3-12, 4-2
.LALL directive 9-8
0
EXITM directive 8-11 LE operator 5-12
Expression operator 8-14 LENGTH operator 5-20
EXTRN directive 6-3 .LFCOND directive 9-7
.LIST directive 9-6
Literal character operator 8-14
Forward references 5-23 Literal text operator 8-13
Loading options 3-6
LOCAL directive 8-5
GE operator 5-12 Location counter 5-3
global symbols 6-1 LOW operator 5-17
GROUP directive 3-9 LT operator 5-12
Group
definition 3-9
size restriction 3-9 MACRO directive 8-2
GT operator 5-12 Macros

HIGH operator 5-17

calls 8-4
comments 8-15
definitions 8-1, 8-2
0
local symbols 8-5
purging 8-6
IF directive 7-2 MASK operator 5-22
IF1 directive 7-2 MEMORY segments 3-7
IF2 directive 7-2 Messages at user terminal 9-3
IFB directive 7-3 Module
IFDEF directive 7-3 end 3-8
IFDIF directive 7-4 main 3-8
IFE directive 7-2 name 9-4
IFIDN directive 7-4
IFNB directive 7-3
IFNDEF directive 7-3 NAME directive 9-4
INCLUDE directive 9-1 Names
Index operator 5-13 definition 2-5
Indexed operands 5-6 group 3-9
integers 2-1 module 9-4
IRP directive 8-8
IRPC directive 8-10
segment classes 3-7
segments 3-4
NE operator 5-12
40
Nested conditionals 7-2

2
 Index

NOT operator 5-13 Packed Decimal Numbers 2-3

PAGE directive 9-5

s OFFSET operator 5-18

Operands
based 5-5
Precedence of operators 5-22
PROC directive 3-12
Procedures 3-12
Program
based indexed 5-7 entry point 3-8
direct memory 5-2 loading options 3-6
indexed 5-6 segments 3-4
location counter 5-3 PTR operator 5-14
record field 5-9 PUBLIC directive 6-2
record 5-9 PUBLIC segments 3-6
register 5-4 public symbols 6-2
relocatable 5-3 PURGE directive 8-6
strong typing 5-26
structures 5-8
Operators .RADIX directive 9-2
arithmetic 5-10 Record declarations 4-15
bitwise 5-13 RECORD directive 4-12
DUP 4-7 Record field operand 5-9
HIGH 5-17 Record operands 5-9

0 index 5-13
LENGTH 5-20
LOW 5-17
Register operands 5-4
Relational operators 5-12
Relocatable operands 5-3
MASK 5-22 REPT directive 8-7
OFFSET 5-18
PTR 5-14
relational 5-12 .SALL directive 9-8
SEG 5-17 SEG operator 5-17
segment override ( :) 5-15 SEGMENT directive 3-4
shift 5-11 Segment override operator 5-15
SHL 5-11 Segments
SHORT 5-16 alignment 3-6
SHR 5-11 AT 3-7
SIZE 5-20 class argument 3-7
THIS 5-16 combine types 3-6
TYPE 5-18 COMMON 3-6
.TYPE 5-19 definition 3-4
WIDTH 5-21 groups 3-9
XOR 5-13 loading options 3-6
OR operator 5-13 MEMORY 3-7
ORG directive 3-11 nesting 3-4
%OUT directive 9-3 origin 3-11
PUBLIC 3-6

3
Index

Segments (continued) Symbols (continued)

STACK 3-6 public 6-2
.SFCOND directive 9-7
Shift operators 5-11
SHL operator 5-11
relocatable 5-3
variables 4-10 0
SHORT operator 5-16
SHR operator 5-11 .TFCON'D directive 9-7
SIZE operator 5-20 THIS operator 5-16
Source files TITLE directive 9-4
end 3-8 Title for assembly listing 9-4
including 9-1 Type declarations 5-18
STACK segments 3-6 TYPE operator 5-18
Statements 2-7 .TYPE operator 5-19
Strong Typing 5-26 Types
STRUC directive 4-11 operand matching 5-26
Structure record 4-12
declarations 4-14 structure 4-11
operands 5-8
Substitute operator 8-12
Subtitle for assembly listing Variables
9-5 default segment register 3-10
SUBTTL Directive 9-5 definitions 4-10
Symbols
absolute 4-8, 4-9
aliases 4-9 WIDTH operator 5-21
default segment register
3-10
external 6-3 .XALL directive 9-8
global 6-2, 6-3 .XCREF directive 9-9
labels 4-10 MIST directive 9-6
XOR operator 5-13

0
4