Topic: CPU Type Equate
Syntax: @Cpu
Description:
Predefined equate returning the type of processor selected by the
previous processor directive (8086 is the default). Bits are set
for each group of instructions supported by the processor. For
example, when the .286 and .287 directives are in effect, bits 0,
1, 2, 8, and 10 will be set.
The .486 directive sets bits in @Cpu as if the .387 directive were
used.
15 8 7 0
ÚÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄ¿ÚÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄÂÄÄÄ¿
³ ³ ³ ³ ³387³287³ ³87 ³³Prv³ ³ ³486³386³286³186³86 ³
³ ³ ³ ³ ³ ³ ³ ³ ³³ ³ ³ ³ ³ ³ ³188³88 ³
ÀÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÙÀÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÁÄÄÄÙ
Bit Processor Compatibility
0 8086/8088
1 80186/80188
2 80286
3 80386
4 80486
7 Privileged instructions enabled
8 8087
10 80287
11 80387
All other bits are reserved, and their values are undefined.
--
Topic: Code Segment Text Macro
Syntax: @code
Description:
Text macro representing the segment name defined by .CODE. Can be
used in ASSUME statements or any place a segment name would be
valid. Under the TINY memory model, @code expands to DGROUP.
--
Topic: Code Size Equate
Syntax: @CodeSize
Description:
Predefined equate giving a value of 0 for tiny, small, compact, and
flat models, or 1 for medium, large, and huge models. The .MODEL
directive must precede references to this equate. Useful in
conditional assembly.
--
Topic: Current Segment Name Macro
Syntax: @CurSeg
Description:
Text macro returning the name of the current segment. Useful for
ASSUME statements and segment overrides (especially inside
macros), as well as for ending the current segment when mixing
simplified and full segments. @CurSeg allows you to terminate
segments started in include files so that the segment will close
before the next include. Returns <> (blank) when not in a segment.
--
Topic: Pointer to DATA/DATA?/CONST/STACK
Syntax: @data
Description:
Predefined equate representing DGROUP, which contains all near
data segments that are defined by the .DATA, .DATA?, .CONST, and
.STACK directives. To access data in any of these segments, DS
must contain the value @data (under DOS, the .STARTUP directive
automatically initializes DS). This equate can be used with the
ASSUME directive or other directives that require segment names.
The .MODEL directive must precede this equate.
--
Topic: Data Size Equate
Syntax: @DataSize
Description:
Predefined equate giving a value of 0 for tiny, small, medium, and
flat models, 1 for compact and large models, and 2 for huge model.
This equate is often used in conditional assembly blocks.
The .MODEL directive must precede this directive.
--
Topic: Current Date and Time Text Macros
Syntax: @Date
@Time
Description:
@Date is a text macro returning the system date at the time of
assembly in mm/dd/yy format. The @Time text macro returns the system
time at assembly in hh:mm:ss 24-hour format. These macros are useful
for time-stamping assembler output.
--
Topic: Environment Variable Macro
Syntax: @Environ(envvar)
Description:
Returns the value of environment variable <envvar>. Returns a
blank if <envvar> is not defined.
--
Topic: Far Data Location Macro
Syntax: @fardata
@fardata?
Description:
Predefined text macro returning the name of the segment defined by
the last .FARDATA or .FARDATA? directive. This macro normally
equals FAR_DATA or FAR_BSS.
--
Topic: Current Source Filename Macros
Syntax: @FileCur
@FileName
Description:
@FileCur is a text macro returning the name of the current source
or include file, including any necessary relative or absolute path.
The @FileName text macro returns the base name of the current
assembly file; if in an include file, it returns the name of the
calling source file. This macro is useful for any situation in which
you want a name to change whenever the name of the file or include
file changes.
--
Topic: Current Source Filename Macro
Syntax: @Interface
Description:
Predefined equate returning a byte-size bit flag describing the
current language and operating-system types.
Bits 0-2 Bit 7
000 Reserved 0 MS-DOS or Windows
001 C 1 OS/2
010 SYSCALL
011 STDCALL
100 Pascal
101 FORTRAN
110 Basic
111 Reserved
All other bits are reserved for future use, and their values are
undefined.
--
Topic: Current Line-Number Macro
Syntax: @Line
Description:
Predefined equate returning the current line number in the module.
If in an include file, returns the line number relative to the
include file. If in a macro, returns the line number relative to
the beginning of the source file. Useful for showing the line
number of a programmer-defined error.
Example:
IFNDEF Country
.ERR <Country code expected at line @Line>
ENDIF
--
Topic: Model Equate
Syntax: @Model
Description:
A predefined equate that returns one of the following values,
depending on memory model previously defined with the .MODEL
directive:
Value Memory model
1 TINY
2 SMALL
3 COMPACT
4 MEDIUM
5 LARGE
6 HUGE
7 FLAT
The @Model equate is the only way of identifying the TINY and FLAT
memory models. This equate is often used in conditional assembly
blocks. The @Model equate is defined only after a .MODEL directive.
--
Topic: Stack Location Macro
Syntax: @stack
Description:
Predefined equate returning the name of the group containing the
stack segment. This equate expands to DGROUP for NEARSTACK and to
STACK for FARSTACK, as defined in a preceding .MODEL statement.
--
Topic: Assembler Version Equate
Syntax: @Version
Description:
Prefined equate returning a three-digit string giving the current
version number of the assembler. Returns 600 for this version
of the assembler, 520 for QuickAssembler, and 510 for MASM 5.1. It
is undefined for MASM version 5.0 and earlier.
--
Topic: Word Size Equate
Syntax: @WordSize
Description:
Predefined equate returning the size of a word. In default 16-bit
mode, @WordSize returns 2. On 80386/486 processors in a 32-bit
segment (such as the FLAT model), @WordSize returns 4.
Outside of a segment this equate returns the default word size as
set by a processor selection directive or the OPTION SEGMENT:
directive.
--
Topic: Align Data and Code
Syntax: ALIGN [number]
EVEN
Description:
ALIGN aligns the next variable or instruction on an offset address
that is a multiple of <expression>. The <number> parameter must be
a power of 2 (1,2,4,8,...) less than or equal to the alignment of
the current segment. If <number> is omitted, the alignment is
determined by the align field of the preceding SEGMENT directive.
In a segment containing no instructions, the assembler pads each
skipped byte with nulls (00h). In a code segment, the assembler
inserts a no-operation sequence (not necessarily NOP instructions)
to fill the gap.
This directive is useful for optimizing data and instruction
fetches on processors with 16- or 32-bit data paths.
EVEN is a synonym for ALIGN 2.
--
Topic: Define Segment Ordering
Syntax: .SEQ
.DOSSEG
.ALPHA
Description:
The .SEQ directive outputs segments to the object file in the same
order they appear in the source code. The .ALPHA directive outputs
segments to the object file in alphabetical order by segment name.
The .DOSSEG directive orders segments according to the standard
DOS convention used by other Microsoft languages:
þ CODE segments
þ Other non-DGROUP segments
þ DGROUP segments
þ Segments not in BSS or STACK
þ BSS class segments
þ STACK class segments
When other Microsoft languages are linked with MASM modules, the
linker automatically uses the .DOSSEG ordering.
The .SEQ directive is in effect by default.
The .DOSSEG directive also causes the linker to generate two
special symbols, _end and _edata. Do not use these names for your
own symbols.
--
Topic: Register Assumptions
Syntax: ASSUME segregister:seglocation [, segregister:seglocation]...
ASSUME dataregister:qualifiedtype
[, dataregister:qualifiedtype]...
ASSUME register:ERROR [, register:ERROR]...
ASSUME [register:]NOTHING [, register:NOTHING]...
Description:
A general-purpose directive that allows the assembler to
determine offsets, select the correct segment register, and verify
certain register use assumptions at assembly.
The "ASSUME segregister:seglocation" syntax is used to inform the
assembler of the current value of <segregister>. The assembler
uses this information to calculate offsets correctly and to guard
against segment selection errors. This directive does not generate
code to change the value of <segregister>. The ASSUME directive is
not necessary for the CS register, since CS is assumed to the
current segment or group automatically. The <seglocation> can be any
segment or group name, or an equivalent expression.
The "ASSUME dataregister:type" syntax informs the assembler that
<dataregister> is subject to the constraints of <type>. If an
assumed register is used incorrectly, the assembler generates an
error. The <type> parameter must be the same size as
<dataregister>.
ASSUME bx:WORD
mov ax, [bx] ;Error--cannot dereference non-pointer
ASSUME bx:PTR WORD
mov [bx], 10h ;Assumes operand size is WORD
mov [bx], al ;Error--cannot move byte into word memory
ASSUME al:WORD ;Error--al is only byte-sized
ASSUME bx:BYTE ;Error--bx is word-sized
The "ASSUME register:ERROR" syntax causes the assembler to
generate an error if <register> is later used explictly or
implicitly. The OPATTR, .TYPE, and TYPE directives do not cause
errors when referring to registers assumed to ERROR.
The "ASSUME register:NOTHING" syntax causes the assembler to
remove all assumptions about <register>. ASSUME NOTHING removes
all assumptions about all registers.
Use an ASSUME statement each time you load a known value into a
segment register. Although not required, the ASSUME directive
helps the assembler safeguard against segment selection errors and
determine offsets. You may need to use instructions to initialize
segment registers properly at run time.
If you use the ASSUME directive to set assumptions about a data
register, it will override any assumptions for its subregisters.
For example, ASSUME EDX:DGROUP will override assumptions for DL,
DH, and DX.
Parameter Description
segregister CS, DS, ES, FS, GS, or SS. The assembler
automatically maintains assumptions for the CS
segment register.
seglocation A segment address, another segment register, a
group, or FLAT. You can find the segment address
of a label by using the SEG operator. FLAT is
the label of the single FLAT segment.
dataregister Any byte, word, or 32-bit register.
qualifiedtype Any qualified type that will fit in
<dataregister>.
register Any segment or data register.
--
Topic: Concatenate Strings
Syntax: @CatStr(string[, string...])
name CATSTR [textitem[, textitem...]]
Description:
The @CatStr macro function concatenates one or more text items.
The result can be used anywhere a text item is appropriate. The
@CatStr function will not expand macros or expressions unless
you use the expression operator (%).
The CATSTR directive concatenates strings and assigns the result
to <name>. These two lines are equivalent:
language TEXTEQU @CatStr (<Quick>, <Pascal>)
language CATSTR <Quick>, <Pascal>
The <name> is a unique symbolic name, <string> is a text string,
and <textitem> is a text item.
--
Topic: Start Code Segment
Syntax: .CODE [name]
Description:
Starts a code segment (with segment name <name>, if given)
and ends the previous segment, if any. Aligns the segment on a
2-byte boundary (.8086, .186, .286) or a 4-byte boundary (.386,
.486). The .MODEL directive must precede this directive.
Segment name <name> is an optional parameter that overrides the
default segment name. If <name> is not specified, the assembler
generates a segment called _TEXT (tiny, small, compact, and flat
models) or <modulename>_TEXT (medium, large, and huge models).
--
Topic: Create Communal Variables
Syntax: COMM [langtype] [NEAR³FAR] label:type[:count]
[,[langtype] [[NEAR³FAR] label:type[:count]]...
Description:
Creates one or more communal variables. Communal variables are
uninitialized, public, and allocated by the linker. The assembler
has no control over the order, position, or initial value of
communal variables. Communal variables are usually declared in
include files. Use EXTERNDEF to include data variables from other
languages.
Parameter Description
NEAR³FAR Communal variable distance. PROC is interpreted
as NEAR or FAR depending on the memory model
chosen.
langtype Any language type. Determines how the linker
outputs variable names.
label Name of the variable.
type Type specifier (BYTE, WORD, etc.), constant, or
structure name.
count Specifies the number of data objects in an array
(1 is the default).
--
Topic: Multiline Comments
Syntax: COMMENT delimiter [text]
[text]
[text] delimiter [text]
Description:
Ignores all text between delimiters or on the same line as a
delimiter. The two comment delimiters can be on the same or
different physical lines.
In the following code segment, the text inside the asterisks and
the MOV instruction are ignored:
COMMENT * This text is ignored
by the assembler * mov ax, 10h
Parameter Description
delimiter First nonblank character following the COMMENT
directive
text All text up to and including the line containing
the next occurrence of the delimiter.
--
Topic: Start a Constant Data Block
Syntax: .CONST
Description:
Starts a constant data segment (called CONST in DGROUP) and ends
the previous segment, if any. For consistency with other
languages, this segment should contain all strings, real numbers,
and other constant data accessed by a high-level language. The
CONST segment has the READONLY attribute.
The .MODEL directive must precede this directive.
--
Topic: Turn On/Off Symbol Cross-Referencing
Syntax: .CREF
.NOCREF [name[, name]...]
Description:
The .CREF directive enables collection of information for all
symbols. These symbols will appear in the symbol table at the end
of a listing file. If you generate a source-browser file with the
/FR or /Fr command-line option, the browser will be able to access
cross-reference information for these symbols. This directive is
in effect by default.
The .NOCREF directive turns off cross-referencing for all symbols.
Any references to symbols while .NOCREF is in effect are omitted
from the cross-reference listing. If the <name> parameter is given
with this directive, only the cross-reference information for the
symbols specified by <name> is omitted.
.XCREF is a synonym for .NOCREF and is provided for compatibility
with previous versions of the assembler.
--
Topic: Start a Data Segment
Syntax: .DATA
.DATA?
Description:
The .DATA directive starts the initialized data segment (with
segment name _DATA) and ends the previous segment, if any. The
.DATA segment should contain all global data that have initial
values.
The .DATA? directive starts the uninitialized data segment (with
segment name _BSS) and ends the previous segment, if any. Place all
uninitialized data in the .DATA? segment.
Although uninitialized data can be placed in the .DATA segment by
declaring data with the ? operator, use the .DATA? directive to
minimize the size of the .EXE file and to maximize compatibility
with other languages.
The .MODEL directive must precede these directives. It generates a
GROUP statement that places _DATA and _BSS in DGROUP.
--
Topic: Declare Variables
Syntax: [name] [S]BYTE initializer [, initializer]...
[name] [S]WORD initializer [, initializer]...
[name] [S]DWORD initializer [, initializer]...
[name] FWORD initializer [, initializer]...
[name] QWORD initializer [, initializer]...
[name] TBYTE initializer [, initializer]...
[name] REAL4 initializer [, initializer]...
[name] REAL8 initializer [, initializer]...
[name] REAL10 initializer [, initializer]...
Description:
Integer
Type Abbr Size Range Types Allowed
ÚÄÄÄÄÄÄÄÂÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ BYTE ³ DB ³ 1 byte ³ -128 to ³ Character, String ³
³ ³ ³ ³ +255 ³ ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ WORD ³ DW ³ 2 bytes ³ -32,768 to ³ 16-bit near ptr, 2 characters, ³
³ ³ ³ ³ +65,535 ³ double-byte character ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ DWORD ³ DD ³ 4 bytes ³ -2Gig to ³ 16-bit far ptr, 32-bit near ptr, ³
³ ³ ³ ³ +4Gig-1 ³ 32-bit long word ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ FWORD ³ DF ³ 6 bytes ³ ÄÄ ³ 32-bit far pointer ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ QWORD ³ DQ ³ 8 bytes ³ ÄÄ ³ 64-bit long word ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ TBYTE ³ DT ³10 bytes ³ ÄÄ ³ BCD, 10-byte binary numbers ³
ÀÄÄÄÄÄÄÄÁÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
ÚÄÄÄÄÄÄÄÂÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ REAL4 ³ DD ³ 4 bytes ³ ÄÄ ³ Single-precision floating point ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ REAL8 ³ DQ ³ 8 bytes ³ ÄÄ ³ Double-precision floating point ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´
³ REAL10³ DT ³10 bytes ³ ÄÄ ³ 10-byte floating point ³
ÀÄÄÄÄÄÄÄÁÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ
These directives allocate and optionally initialize one or
more bytes of global data. The S prefix indicates signed data,
but this information is used internally by the assembler for
comparisons used by control-flow directives and
argument passing in INVOKE statements. CodeView also uses this
information to specify the data format.
The abbreviations (such as DB, DD) are limited forms of the
data-declaration directives; they cannot be used as types. They
are included for compatibility with previous versions of the
assembler.
String initializers, available with the BYTE directive, allocate
a byte for each character of the string. The characters are stored
with the leftmost character in the lowest memory location so that
BYTE "WASHINGTON"
would be assembled to
57 41 53 48 49 4E 47 54 4F 4E "WASHINGTON"
Character initializers, however, are stored with the leftmost
character in the highest memory location. They are also limited
to the current expression size so that under the default
OPTION EXPR32
DWORD "WASH"
would be assembled to
48 53 41 57 "HSAW"
and under OPTION EXPR16
WORD "WA"
would be assembled to
41 57 "AW"
Use the REAL4, REAL8, and REAL10 data types for floating-point
data. They inform CodeView that the data is in floating-point
format and cause the assembler to perform more stringent type
checking.
Parameter Description
name Symbol name assigned to the variable. If no name is
assigned, the memory space is allocated, but the
starting address of the variable has no symbolic
name.
initializer A type shown in the table above, constant integer
expression, ?, or DUP expression. Separate multiple
values with commas or use the DUP operator.
--
Topic: Display Message during Assembly
Syntax: ECHO message
Description:
Displays message during assembly. The message is usually output to
the screen, but you can redirect it to a file or another device.
This directive can help show which statements were assembled. %OUT
is a synonym for ECHO and is included for compatibility.
The <message> is any line of ASCII characters up to but not
including any comment on the line. If angle brackets are used to
enclose <message>, the angle brackets are not displayed. To perform
macro substitution, put the macro substitution operator (%) at the
beginning of the line. Use a separate ECHO directive for each line.
To output the time and date of assembly, insert this line in your
source code:
% ECHO Assembled on @Date at @Time
--
Topic: End Source File
Syntax: END [address]
Description:
Marks the end of a source file and optionally indicates the
program load address. The optional <address> is a label or
expression identifying where program execution begins. You can
define <address> only once in a program, usually in the main
module.
You cannot specify <address> if you have used the .STARTUP
directive, which automatically sets a start address. If you are
linking with a high-level language, the start address is
typically set by that language's compiler.
END also closes the last segment in the source file.
--
Topic: End Macro and Iterative Blocks
Syntax: ENDM
Description:
Terminates macro and iterative blocks.
--
Topic: End Segment and Structure Blocks
Syntax: name ENDS
Description:
Marks the end of a segment or a structure definition previously
started with SEGMENT, STRUCT, or UNION. To end a simplified segment
(such as one started with .DATA), use the line
@CurSeg ENDS ;End current segment
A single .STACK statement opens and closes the stack segment,
so you should not include an additional ENDS statement.
--
Topic: Numeric and String Equate
Syntax: name EQU expression
name EQU <text>
name TEXTEQU textmacro
name TEXTEQU %expression
Description:
The EQU directive assigns <expression> or <text> to <name>. Angle
brackets indicate that <text> should not be evaluated as an
expression.
EQU evaluates the numeric value of <expression> and assigns
the resulting constant value to <name>. Unlike =, EQU does not
allow numeric equates to be redefined. If <expression> cannot be
evaluated, EQU treats <expression> as text.
The TEXTEQU directive acts like the EQU directive with text
equates but performs macro substitution at assembly and does not
require angle brackets. The TEXTEQU directive will also resolve
the value of an expression preceded by a percent sign (%). The EQU
directive does not perform macro substitution or expression
evaluation for strings.
Text equates are limited to 255 characters. Text equates can be
redefined to another value but not to a different type of symbol.
Parameter Description
name Symbolic name for <expression> or <text>
expression Variable or constant numeric expression (not a
memory expression)
text String enclosed in angle brackets (<>)
textmacro A text macro (such as @Date) or a string enclosed in
angle brackets (<>).
expression An expression preceded by a %.
Example:
MASM EQU 5.1 + 0.9 ;Evaluates to 6.0
Msft EQU <Microsoft> ;String equate
libpath TEXTEQU @Environ(<LIB>) ;Text Macro Equate
endstr TEXTEQU %(endadr-staradr);String equate to numeric value
--
Topic: Generate Severe Error
Syntax: .ERR [message]
Description:
Generates an A2052 error message when assembled. Generally, this
directive occurs in a conditional-assembly block and is used to
indicate some error condition discovered at assembly time.
This directive can be useful for verifying that the program
assembled correctly and that user-defined bounds were not exceeded.
If <message> is given, it will be displayed with the standard
assembler error messages. The <message> parameter is any text item
--
Topic: Generate Error for Missing Argument
Syntax: .ERRB <textitem> [,message]
.ERRNB <textitem> [,message]
Description:
The .ERRB directive generates an A2057 error if <textitem> is
blank. The .ERRNB directive generates an A2058 error if <textitem>
is not blank.
These directives are usually used within macro definitions; a
macro parameter is replaced by an empty string if you call the
macro and do not give a corresponding argument. These directives
let you write macros that generate an assembly-time error if the
wrong number of arguments is used in the macro call. However, the
:REQ parameter attribute or the variable argument feature often
provides the same functionality in a more straightforward way.
Parameter Description
textitem Item to be tested, any text item.
message Programmer-supplied error message, any text item.
--
Topic: Generate Error for Undefined Symbol
Syntax: .ERRDEF name [,message]
.ERRNDEF name [,message]
Description:
The .ERRDEF directive generates an A2056 error message if <name>
is a previously defined symbol. The .ERRNDEF directive generates
an A2055 error message if <name> has not been previously
defined.
One of the most common uses of the .ERRNDEF directive is to ensure
that a symbol has been defined before you attempt to use it. This
situation can occur if the source code depends on the command-line
/D option to define a symbol.
If <message> is given, it will be displayed with the standard
assembler error messages. The <message> parameter is any text item.
--
Topic: Generate Error If Arguments Are Same/Different
Syntax: .ERRDIF[I] <textitem1>, <textitem2> [,message]
.ERRIDN[I] <textitem1>, <textitem2> [,message]
Description:
The .ERRDIF directive generates an A2060 error if <textitem1> and
<textitem2> are different. .ERRIDN generates an A2059 error if the
arguments are identical. These directives are commonly used inside
macros to test for bad values passed as parameters. The .ERRDIFI
and .ERRIDNI directives act the same as the .ERRDIF and .ERRIDN
directives but perform case-insensitive comparisons.
The <textitem1> and <textitem2> parameters are text items.
If <message> is given, it will be displayed with the standard
assembler error messages. The <message> parameter is any text item.
--
Topic: Generate Error If Argument Is Zero/Nonzero
Syntax: .ERRE expression [,message]
.ERRNZ expression [,message]
Description:
Tests value of <expression> and generates an error depending on
the resulting value. The .ERRE directive generates an A2053 error
if <expression> evaluates to false (zero). .ERRNZ generates an
A2054 error if <expression> evaluates to true (nonzero). If
<message> is given, it will be displayed with the standard
assembler error message.
Parameter Description
expression Expression that evaluates to true, false, or a
numeric constant. The expression cannot contain
forward references.
message Programmer-supplied error message, any text item.
--
Topic: End Macro and Repeat Blocks
Syntax: EXITM [textitem]
Description:
Terminates expansion of the current macro or repeat block and
begins assembly of the next statement outside the block. If the
EXITM directive is encountered in a nested macro block, the
assembler returns to expanding the previous block level.
The <textitem> parameter is a text item that is returned to the
calling statement. The <textitem> field is valid only with an
EXITM directive at the end of a MACRO block.
--
Topic: Define External Variables, Labels, and Symbols
Syntax: EXTERNDEF [langtype] name:qualifiedtype
[, [langtype] name:qualifiedtype]...
EXTERN [langtype] name[(altID)]:qualifiedtype
[, [langtype] name[(altID)]:qualifiedtype]...
Description:
The EXTERNDEF directive tells the assembler that one or more
variables, symbols, data structures, or labels are defined in
other modules. The behavior of the EXTERNDEF directive is
determined by its context:
þ If <name> is used in the current module but is not defined,
<name> is made external.
þ If <name> is defined in the current module, it is made
PUBLIC.
þ If <name> is neither used nor defined, the directive is
ignored.
The EXTERNDEF directive allows you to put global data declarations
in an include file without forcing the linker to pull in unneeded
modules. Usually, you define <name> in one module and put the
EXTERNDEF directive in a file that is included in all program
modules. The PROTO directive automatically generates an EXTERNDEF
for its related procedure.
EXTERN is a less flexible version of EXTERNDEF. It declares
<name> as external whether or not it is used in the module.
EXTRN is a synonym for EXTERN and is included for compatibility
with previous versions of the assembler.
With the EXTERN directive, <name> can be followed by (altID),
which allows the linker to select an alternate resolution for
<name>. This is useful when creating library files.
Parameter Description
langtype A language type appropriate to <name>.
name A unique global symbolic name. Case mapping is
overridden by OPTION CASEMAP.
qualifiedtype The qualified type to be given to <name>. Can
also be ABS, which causes <name> to be imported
as a constant. Does not have to match type given
to <name> in original definition.
altID A unique global symbolic name to use as an alternate
for <name>. Must be of the same type as <name>. The
<altID> parameter cannot be declared as a <name>
with an altID in an EXTERN statement in this or any
other module.
--
Topic: Start a Far Data Segment
Syntax: .FARDATA [name]
.FARDATA? [name]
Description:
The .FARDATA directive starts a far data segment for initialized
data (segment name FAR_DATA or <name>, if given), ending any
previous segment. The .FARDATA? directive starts a far data
segment for uninitialized data (segment name FAR_BSS or
<segmentname>, if given), ending any previous segment.
Data in segments defined with .FARDATA and .FARDATA? are not
placed in a group or combined with far data segments for other
source modules. Using <name> allows you to create multiple far
data segments in one source module. The .MODEL directive must
precede these directives.
Putting uninitialized arrays and buffers into a segment created
by .FARDATA? rather than .FARDATA can decrease the size of object
files and libraries.
Normally, you cannot access far data segments by name, because
there may be multiple PRIVATE segments with the same name. Use
SEG expressions instead.
--
Topic: Iterative Macro
Syntax: FOR parameter[:REQ³:=default], <argument [,argument]...>
statements
ENDM
Description:
Repeats <statements> once for each argument specified. The current
argument replaces <parameter> in each iteration. IRP is a synonym
for FOR and is included for compatibility with previous versions
of the assembler.
Parameter Description
parameter A valid symbol name. If parameter appears in
statements, it is replaced by a different argument
in each iteration.
:REQ Optional tag for <parameter> causing an assembler
error if <parameter> is given a blank argument.
:=default Optional tag for <parameter> causing <parameter> to
be assigned <default> if given a blank argument.
argument Text, symbol, string, or numeric constant. Separate
multiple iterations with commas. Angle brackets are
required if a string <argument> includes spaces or
commas. Leading spaces of string arguments are
ignored.
statements Any valid assembler statements.
--
Topic: Iterative Macro (for Character)
Syntax: FORC parameter, <string>
statements
ENDM
Description:
Repeats <statements> once for each character in the string. The
character replaces <parameter> in each repetition. IRPC is a synonym
for FORC and is included for compatibility with previous versions
of the assembler.
Parameter Description
parameter A valid symbol name. If <parameter> appears in
statements, then it is replaced by a different
character each iteration.
string A literal string or a symbol defined with a string
equate. All spaces are counted as characters. Angle
brackets are required.
statements Any valid assembler statements.
--
Topic: Skip to Label
Syntax: GOTO macrolabel
Description:
Causes assembler to skip to <macrolabel>. The GOTO directive is
only allowed inside a MACRO, FOR, FORC, REPEAT, or WHILE block.
The <macrolabel> is only visible within the block.
Example:
MACRO Instruments
IFNDEF Cymbal
GOTO Crash
ENDIF
ù
ù
ù
:Crash
.ERR <Undefined symbol.>
ù
ù
ù
ENDM
--
Topic: Combine Segments
Syntax: name GROUP segment [,segment]...
Description:
Adds the <segment> parameters to a group called <name>. Creates
group <name> if it does not exist. This causes the linker to
combine the given logical segments into one physical segment, so
that the logical segments share a common physical segment address.
Under the FLAT memory model, all segments are automatically
assigned to a common group called FLAT.
All logical segments in a group must have the same WordSize
attribute. If they are 16-bit segments, their total size cannot
exceed 64K bytes. If they are 32-bit segments (allowed on
80386/486 processors), groups can be up to 4 gigabytes.
The <name> is a unique symbolic name or previously defined group.
If the same group name appears in more than one GROUP statement,
the effect is cumulative; the new segments are added to the group.
The <segment> is a segment name defined with the SEGMENT directive.
--
Topic: IF Block Syntax
Syntax: IFcond expression
ifstatements
[ELSEIFcond expression
elseifstatements]
ù
ù
ù
[ELSE
elsestatements]
ENDIF
Description:
The IF block format can be used to create a source file that will
generate a variety of programs, depending on constants or
environment variables. For example, you can create a single source
file that generates code for different memory models and operating
environments. IF blocks can be nested up to 20 levels but cannot
span include files or structure, union, or macro definitions.
The statements following the ELSE directive are assembled only if
the preceding IF directive was found to be false (zero). Only one
ELSE statement is allowed in each IF block, although there can be
several ELSEIF statements.
IFcond is one of the conditional assembly directives beginning
with "IF" (such as IF, IFE, and IFB). There is an optional
ELSEIFcond corresponding to each IFcond.
The <ifstatements>, <elseifstatements>, and <elsestatements> are
each a series of one or more assembly-code statements. The
respective conditions determine which block is assembled, if any.
The ELSE and ELSEIF blocks are optional.
--
Topic: IF/IFE/ELSEIF/ELSEIFE Directives
Syntax: [ELSE]IF expression
[ELSE]IFE expression
Description:
IF causes assembly of a block of statements if expression is true
(nonzero). IFE causes assembly of a block of statements if
expression is false (zero).
The <expression> must resolve to a constant and contain no forward
references.
--
Topic: IFB/IFNB/ELSEIFB/ELSEIFNB Directives
Syntax: [ELSE]IFB expression
[ELSE]IFNB expression
Description:
IFB causes assembly of a block of statements if <expression> is
blank. IFNB causes assembly of a block of statements if <expression>
is not blank. The <expression> field is any name, number, or
expression; typically, it is the name of a parameter of a macro.
Within a macro, a parameter name is replaced by an empty string if
you call the macro without giving a corresponding argument. IFB
and IFNB let you define default behavior when an argument is
missing, but the :REQ and :=default MACRO parameters are preferred.
--
Topic: IFDEF/IFNDEF/ELSEIFDEF/ELSEIFNDEF Directives
Syntax: [ELSE]IFDEF name
[ELSE]IFNDEF name
Description:
IFDEF causes assembly of a block of statements if <name> is a
previously defined symbol. IFNDEF causes assembly of a block of
statements if name has not been defined.
Use of this feature with the IFDEF and IFNDEF directives lets you
control which statements are assembled from the command line.
--
Topic: IFDIF/ELSEIFDIF Variations
Syntax: [ELSE]IFDIF[I] textitem1, textitem2
[ELSE]IFIDN[I] textitem1, textitem2
Description:
Causes assembly of a block of statements depending on whether two
textitems are different or identical. IFDIF assembles the block if
<textitem1> and <textitem2> are different. IFIDN assembles the block
if they are the same. IFDIFI and IFIDNI do the same actions but are
not case sensitive.
The <textitem1> and <textitem2> parameters are text items.
--
Topic: Insert Source Code
Syntax: INCLUDE filename
INCLUDE <filename>
Description:
Inserts source code from <filename> into the current source file
during assembly. If <filename> does not include a fully-specified
path, the assembler searches the directory of the current file,
the /I command-line include path, and then the INCLUDE environment
variable. Nested INCLUDE directives are allowed.
The <filename> parameter is an existing file containing valid
assembly-language statements and directives. No default file
extension is assumed. Angle brackets are required if the filename
or path includes a backslash, semicolon, greater-than, less-than,
single quotation marks, or double quotation marks.
--
Topic: Link with LIB File
Syntax: INCLUDELIB libraryname
INCLUDELIB <libraryname>
Description:
Informs the linker that the current module should be linked with
the <libraryname>. If <path> is not given, the linker searches the
current working directory, directories given in the ML or LINK
library field, and then the LIB environment variable from the
TOOLS.INI file.
A common use of INCLUDELIB is to specify OS2.LIB, which is
required for all system calls under OS/2.
The <libraryname> parameter is an existing file containing code in
LIB format. If no extension is specified, the default extension
.LIB is assumed. Angle brackets are required if the libraryname
or path includes a backslash, semicolon, greater-than, less-than,
single quotation marks, or double quotation marks.
--
Topic: Search for String
Syntax: @InStr([position], string1, string2)
name INSTR [position,] textitem1, textitem2
Description:
The @InStr macro function searches for the first occurrence of
<string2> inside <string1> and returns the position of the
first character of the match. The search begins at <position>,
if you give that parameter. The @InStr function will not expand
macros or expressions unless you use the expression operator (%).
The first character is indexed as 1. @InStr returns 0 if
<string1> is not found.
The INSTR directive performs the same function as @InStr but
assigns the result to <name>. These two lines are equivalent:
develop TEXTEQU @InStr (2, <MikeBobMichaelJim>, <Mi>)
develop INSTR 2, <MikeBobMichaelJim>, <Mi>
;develop is now 8
Parameter Description
name Name of the resulting constant.
position Starting character position of the search
(default 1). Must be a positive integer.
string1 String being searched; any text.
string2 String to search for; any text.
textitem1 String being searched; any text item.
textitem2 String to search for; any text item.
--
Topic: Call Stack-Based Procedures
Syntax: INVOKE expression [,arguments]
Description:
Automates the call interface to stack-based procedures. Handles all
pushing of parameters onto the stack. Cleans up the stack when the
procedure returns.
The <invokelist> is passed to the procedure according to the types
given in that procedure's prototype. If necessary, the assembler
will generate code to convert the elements of <invokelist> to the
types specified in the prototype.
Parameter Description
expression Expression yielding address or label of procedure
to be called. Must resolve to a valid address and
cannot include any forward references.
arguments Sequential list of parameters passed. Can be
register::register (for a register pair), expression,
or ADDR label. ADDR label passes the address of
<label> (segment and offset if DWORD, segment only
if WORD) to the procedure.
--
Topic: Create Label
Syntax: name LABEL qualifiedtype
Description:
Creates a new label of a given type at a specified location by
assigning the current location-counter value and the given type to
<name>. The <qualifiedtype> parameter determines the type of data
or call distance for the label. This directive does not allocate
data.
Parameter Description
name Symbol assigned to the label.
qualifiedtype Any qualified type.
--
Topic: List Source Statements to .LST File
Syntax: .LIST
Description:
Enables listing of all source statements to the .LST file. The
.LST file must first be enabled with the /Fl command-line option.
This directive is in effect by default.
--
Topic: List All Statements to .LST File
Syntax: .LISTALL
Description:
Enables listing of all statements to the .LST file. The .LST file
must first be enabled with the /Fl command-line option. This
directive is equivalent to the combination of the .LIST, .LISTIF,
and .LISTMACROALL directives.
--
Topic: List Statements in Conditional Blocks
Syntax: .LISTIF
Description:
Enables listing of all statements in conditional blocks, even
those in false blocks. This directive is in effect by default. The
.LFCOND directive is a synonym of .LISTIF and is included for
compatibility with previous versions of the assembler.
--
Topic: Enable Assembly Listing File
Syntax: .LISTMACRO
Description:
Enables an assembly listing file that includes macro expansion
statements that generate code or data. Comments, equates, and
segment definitions are not listed. This directive is in effect by
default. The .LFCOND directive is a synonym of .LISTMACRO and is
included for compatibility with previous versions of the
assembler.
--
Topic: List Source Statements in Macro Expansion
Syntax: .LISTMACROALL
Description:
Enables listing of all source statements in a macro expansion,
including normal comments but excluding macro comments. The .LALL
directive is a synonym of .LISTMACROALL and is included for
compatibility with previous versions of the assembler.
--
Topic: Local Variables in Procedures
Syntax: LOCAL name [[count]][:qualifiedtype] [, name [[count]]
[:qualifiedtype]]...
Description:
Generates code to create one or more stack (automatic) variables,
which can be accessed only within the current procedure. The
assembler uses the same method used by high-level languages to
create local variables.
The <name> parameter is the name of the variable, and <count> is
an optional expression (which must appear in square brackets)
indicating the number of elements to allocate. The <qualifiedtype>
parameter is any qualified type appropriate to <name>. The default
<qualifiedtype> is WORD in a 16-bit segment and DWORD in a 32-bit
segment.
Once declared in a LOCAL statement, local variables can be
referred to by name. The assembler translates references to these
variables into references to their actual location on the stack
using the BP indirect addressing mode.
The assembler will generate an error if you have already defined
<name> as a label.
Example:
LOCAL array[20]:BYTE
--
Topic: Local Variables in Macros
Syntax: LOCAL localname [,localname]...
Description:
Declares a label or symbol for local use within a macro or
iterative block. The assembler generates a different internal name
for the symbol each time it expands the macro. The LOCAL directive
allows you to call a macro that contains local jump statements and
variable definitions without generating the same label each time
the macro is expanded.
The <localname> parameter is the name of a label or symbol inside
the macro. Inside the macro expansion, <localname> takes precedence
over a global label or symbol with the same name.
--
Topic: Macro Block
Syntax: name MACRO [parameter[:tag]] [,parameter[:tag]]...]
[LOCAL varlist]
statements
ENDM [value]
Description:
Marks the beginning of a macro definition called <name> and takes
optional parameters. The assembler generates the statements in the
macro block each time the macro is called in source code. Macro
procedures and macro functions can be nested up to 40 levels. Text
macros may be nested up to 20 levels.
Macro procedures can be redefined at any time. The new definition
affects any subsequent calls to this macro. Macro functions can
only be redefined, if they have not been called yet.
Example:
mymacro MACRO value:REQ, reg:=<AX>, options:VARARG
LOCAL returnval
ù
ù
ù
ENDM returnval
Parameter Description
name A unique symbol name. It can appear later in source
code, to call the macro.
parameter A valid symbol name. Each parameter can appear in
the statements and is replaced by the corresponding
item in the argument list whenever the macro is
called.
:tag Either :REQ, :=default, or :VARARG. :REQ causes an
assembler error if the parameter is given a blank
argument. :=default causes <parameter> to be
assigned <default> if given a null argument.
:VARARG allows a variable number of arguments to be
passed as a comma-separated list to <parameter>. If
:VARARG is used, it must be applied only to the
last parameter of the MACRO directive.
statements Any valid assembler statements.
value Optional return value for macro function.
--
Topic: Initialize Memory Model
Syntax: .MODEL memorymodel [,langtype] [,ostype] [,stackoption]
Description:
Initializes the program memory model. Must be placed at the
beginning of the source file before any other simplified segment
directive. Generates ASSUME and GROUP statements used by the
specified memory model. Also creates the predefined equates for
the various simplified segments. The .MODEL directive can occur
only once in a program.
If you use the langtype argument with .MODEL, nested procedures
are not allowed.
Parameter Description
memorymodel TINY, SMALL, COMPACT, MEDIUM, LARGE, HUGE, or
FLAT. If you are writing an assembler routine for
a high-level language, this option should match
the memory model used by the compiler or
interpreter. FLAT is valid only in .386 or .486
mode. You must use the /AT command-line option or
/TINY linker option to assemble tiny-model programs.
langtype Any language type. Instructs the assembler to
follow the naming, calling, and return conventions
for the indicated language. This affects the
PUBLIC, EXTERN, PROC, PROTO, and INVOKE
directives.
ostype OS_DOS or OS_OS2. Determines the behavior of the
.STARTUP and .EXIT commands for compatibility with
these operating systems. DOS is the default.
stackoption NEARSTACK (if SS equals DS) or FARSTACK (if SS is
not equal to DS). NEARSTACK is the default. The
stack is not part of DGROUP with the FARSTACK
option. This affects the code generated by the
.STARTUP directive.
--
Topic: Suppress Program Listing
Syntax: .NOLIST
Description:
Suppresses program listing. Use in conjunction with .LIST to
prevent a particular section of a source file from being listed.
The .XLIST directive is a synonym for .NOLIST and is included for
compatibility with previous versions of the assembler.
--
Topic: Turn off List
Syntax: .NOLISTIF
Description:
Turns off the listing of the lines in subsequent conditional blocks
whose condition is false. The .SFCOND directive is a synonym for
.NOLISTIF and is included for compatibility with previous versions
of the assembler.
--
Topic: Suppress Macro Listing
Syntax: .NOLISTMACRO
Description:
Suppresses listing of macro expansions in a listing file. Macro
calls are listed, but the source code generated by the call is
not. The .SALL directive is a synonym for .NOLISTMACRO and is
included for compatibility with previous versions of the
assembler.
--
Topic: Set Assembler Options
Syntax: OPTION optionlist
Description:
Modifies the behavior of certain features of the assembler. The
<optionlist> is a list of one or more of the following options.
Separate options with commas. These options affect the module from
the point they are used onward and override corresponding command-line
options:
Option Default
CASEMAP:maptype NOTPUBLIC
DOTNAME³NODOTNAME NODOTNAME
EMULATOR³NOEMULATOR NOEMULATOR
EPILOGUE:macroid Depends on OS and processor type
EXPR16³EXPR32 Depends on processor
LANGUAGE:langtype -none-
LJMP³NOLJMP LJMP
M510³NOM510 NOM510
NOKEYWORD:<keywordlist> -none-
NOSIGNEXTEND Off
OFFSET:offsettype GROUP
OLDMACROS³NOOLDMACROS NOOLDMACROS
OLDSTRUCTS³NOOLDSTRUCTS NOOLDSTRUCTS
PROC:visibility PUBLIC
PROLOGUE:macrofuncid Depends on OS and processor type
READONLY³NOREADONLY NOREADONLY
SCOPED³NOSCOPED SCOPED
SEGMENT:segmentsize USE16
--
Topic: Maximize Compatibility with MASM 5.1
Syntax: OPTION M510
OPTION NOM510
Description:
The M510 option sets all options to maximize compatibility with
MASM 5.10. Enables the following:
OLDMACROS
OLDSTRUCTS
DOTNAME
CASEMAP:ALL
EXPR16
The M510 option enables OPTION SCOPED if a language type is specified
in a .MODEL statement. Otherwise OPTION NOSCOPED is used.
Using OPTION M510 also changes the default for OFFSET to GROUP if a
.MODEL directive is in effect and to SEGMENT otherwise.
With OPTION M510, keywords and instructions that are not available
in the current CPU mode (such as ENTER under .8086) are not treated as
keywords. The USE32, FLAT, FAR32, and NEAR32 segment types and the
80386/486 registers are not keywords with processor selection
directives less than .386.
NOM510 is the default.
--
Topic: OLDMACROS³NOOLDMACROS Option
Syntax: OPTION OLDMACROS
OPTION NOOLDMACROS
Description:
The OLDMACROS option enables MASM 5.1-compatible macros and
parameter substitution. NOOLDMACROS is the default. The OLDMACROS
option is enabled with the M510 option.
--
Topic: OLDSTRUCTS³NOOLDSTRUCTS Option
Syntax: OPTION OLDSTRUCTS
OPTION NOOLDSTRUCTS
Description:
The OLDSTRUCTS option enables MASM 5.1-compatible scoping of
structure members. This option causes all structure members to
have the same scope as the structure name and prevents a label and
a member name from having the same name. This option also causes
the dot operator to act exactly like a plus.
NOOLDSTRUCTS is the default. The OLDSTRUCTS option is enabled with
the M510 option.
--
Topic: Automatic Conditional Jump Lengthening
Syntax: OPTION LJMP
OPTION NOLJMP
Description:
The LJMP option enables automatic conditional-jump lengthening.
LJMP is the default.
Enabling LJMP allows the assembler to generate code that emulates
a conditional jump of greater than -128 to +127 bytes. If the jump
is within this range, no special code is generated. It does not
affect unconditional jumps or the control-flow directives.
The assembler will generate an A6003 warning for a lengthened jump
so that you can identify it for later optimization.
--
Topic: Enable/Disable Dot Labels
Syntax: OPTION DOTNAME
OPTION NODOTNAME
Description:
The DOTNAME option enables the use of the period (.) as the leading
character in variable, label, macro, struct, union, and member names.
NODOTNAME is the default. The DOTNAME option is enabled with the M510
option, since previous versions of the assembler recognized names
with period prefixes.
The DOTNAME option does not have any effect on any of the reserved
words. The use of the period in names is discouraged, as it can be
confused with the field offset and structure operators.
--
Topic: Make Code Segment Read-Only
Syntax: OPTION READONLY
OPTION NOREADONLY
Description:
The READONLY option sets the READONLY attribute for subsequent code
segments. Enables checking for instructions that explicitly modify
segments or groups containing code. Useful for detecting self-
modifying code. NOREADONLY is the default.
This option replaces the command-line /P option from previous
versions of the assembler. Segments can be also be made read-
only with the READONLY parameter of the SEGMENT directive.
--
Topic: Localize Label
Syntax: OPTION SCOPED
OPTION NOSCOPED
Description:
The SCOPED option causes a label (defined with the "label:" syntax)
to be local to the procedure in which it is defined. Labels defined
with the LABEL directive or the "label::" syntax are not affected by
this option.
Using NOSCOPED will cause all labels to be global to the module.
SCOPED is the default. The NOSCOPED option is enabled with the
M510 option, since previous versions of the assembler did not have
scoped labels.
--
Topic: Specify Default Language Type
Syntax: OPTION LANGUAGE:langtype
Description:
Specifies the default language type to be used with many
directives. The most recent OPTION LANGUAGE: or .MODEL directive
determines the current language type. The <langtype> parameter is
any language type.
--
Topic: Control Case Mapping
Syntax: OPTION CASEMAP:maptype
Description:
Controls the mapping of characters to uppercase. The <maptype>
parameter can be ALL, NONE, or NOTPUBLIC, which correspond to the
/Cu, /Cp, and /Cx command-line options. You can use this option
only once per source file. The current language type, if any, will
override <maptype>.
CASEMAP:NOTPUBLIC is the default. The CASEMAP option is set to ALL
with the M510 option.
--
Topic: Floating-Point Code Generation
Syntax: OPTION EMULATOR
OPTION NOEMULATOR
Description:
Controls how floating-point instructions are generated. NOEMULATOR,
the default, generates the coprocessor instructions directly.
EMULATOR generates instructions as well as special fixup records
for the linker so that the floating-point emulator can be used. This
option is definable only once per source file.
To use this option, you must link your assembly-language module with
an emulator library from a Microsoft high-level language.
OPTION EMULATOR is equivalent to the /FPi command-line option.
--
Topic: Offset Relative to Segment/Group
Syntax: OPTION OFFSET:offsettype
Description:
Controls whether the OFFSET operator returns offsets relative to
the current segment or group. OPTION OFFSET:GROUP causes OFFSET
to return a group-relative offset if the label is in a segment
that is part of a group. OPTION OFFSET:SEGMENT causes OFFSET
to return a segment-relative offset. OPTION OFFSET:GROUP is the
default.
The FLAT option causes fixups to be relative to the FLAT group.
OPTION M510 sets OPTION OFFSET:GROUP if a .MODEL directive has been
used and OPTION OFFSET:SEGMENT otherwise. With previous versions of
the assembler, the OFFSET type was SEGMENT with complete segment
directives and GROUP with simplified segment directives.
The <offsettype> can be GROUP, SEGMENT, or FLAT.
--
Topic: Register Macro as Prologue or Epilogue
Syntax: OPTION PROLOGUE:macroname
OPTION EPILOGUE:macroname
Description:
PROLOGUE registers <macroname> as the macro function to be called
when a prologue needs to be generated. EPILOGUE registers
<macroname> as the macro procedure to be called when a RET or IRET
instruction is encountered.
You can revert to the default prologue or epilogue by specifying
PrologueDef or EpilogueDef as <macroname>. EPILOGUE code is
generated only if the RET or IRET instruction terminating the PROC
block has no operand. The RETN, RETF, and IRETF instructions do not
cause the assembler to generate epilogue code.
To suppress generation of the prologue or epilogue code, give NONE
as the <macroname>.
The assembler expects a macro definition of this form:
macroname MACRO procname, flags, argbytes, localbytes, <reglist>,
userparms:VARARG
Parameter Description
procname Macro name for the procedure or NONE.
flags Word-size bit flag: (1=On, 0=Off)
Bits Description
0-2 Language type:
000 Not specified
001 C
010 SYSCALL
011 STDCALL
100 Pascal
101 Fortran
110 Basic
111 Reserved
3 Reserved
4 Caller restores stack
5 FAR procedure
6 PRIVATE procedure
7 EXPORT procedure
8 Epilogue caused by IRET instruction
All other bits are reserved for future use.
argbytes The total number of bytes used by PROC arguments.
localbytes The total number of bytes used by variables defined
with the LOCAL directive inside the PROC block.
reglist Comma-delimited list of registers from the PROC
directive USE option. This list is reversed in
in the EPILOGUE directive. Angle brackets are
passed.
userparms Passed the optional macroarglist from the PROC
directive.
--
Topic: Disable/Enable Keyword Recognition
Syntax: OPTION NOKEYWORD:<keywordlist>
Description:
Disables the recognition of the reserved words in <keywordlist>
for the current module. The listed keywords can then be used as
user-defined symbols. Keywords disabled with this directive cannot
be reenabled. The <keywordlist> is a space-delimited list of
reserved words; literal operands and predefined symbols are not
allowed. The list of keywords must be enclosed in angle brackets (<>).
You can use this option to disable privileged instruction names
or obsolete synonyms so they are free to be used as labels and
variables. For example:
OPTION NOKEYWORD: <STR EXTRN IRPC>
STR BYTE 10 DUP (?)
--
Topic: Select 16- or 32-Bit Expressions
Syntax: OPTION EXPR16
OPTION EXPR32
Description:
The EXPR32 option selects 32-bit expressions and arithmetic. The
EXPR16 option selects 16-bit expressions and arithmetic. The
default is EXPR32. The expression word size cannot be changed once
it has been explicitly set.
Under OPTION M510, EXPR16 is the default unless the module contains
a .386 or greater processor-selection directive.
These options do not affect the processor type, segment size, or
registers used.
--
Topic: Select Segment Size
Syntax: OPTION SEGMENT:segmentsize
Description:
The SEGMENT:USE16 option selects 16-bit segments. The SEGMENT:USE32
option selects 32-bit segments. The SEGMENT:FLAT option selects
the 32-bit flat segment. This option overrides the segment size set
optionally set by the SEGMENT and .MODEL directives.
The default segment size is selected by the following rules:
þ A .386 or higher processor selection directive selects USE32.
þ A .MODEL FLAT statement selects FLAT. All other memory models select
USE16.
þ The OPTION SEGMENT: directive will override any other defaults.
þ In all other cases, the default is USE16.
--
Topic: Disable Byte Sign-Extended Opcode
Syntax: OPTION NOSIGNEXTEND
Description:
The NOSIGNEXTEND option disables the generation of the sign-
extended form (83h) of the AND, OR, and XOR instructions. The NEC
V25 and V35 microprocessors do not support this opcode.
--
Topic: Select Default PROC Visibility
Syntax: OPTION PROC:visibility
Description:
Sets the default procedure visibilty. The <visibility> parameter can
be PRIVATE, PUBLIC, or EXPORT. If you do not use this option, the
the default visibility will be PUBLIC.
With OPTION M510, the default <visibility> with no defined language type
is PRIVATE. If you specify a language type in a .MODEL or OPTION LANGUAGE
statement, the default <visibility> is PUBLIC.
--
Topic: Specify Assembly Start Address
Syntax: ORG expression
ORG $+expression
Description:
Sets the location counter to a specific address, given by <expression>.
The assembler implements this directive by adjusting the
location counter.
ORG $+expression causes the assembler add <expression> bytes to
the location counter. The <expression> must evaluate to a constant
without forward references.
Inside a STRUCT block, the <expression> parameter is relative to
the beginning of the structure. This can be used to create
structure elements that refer to bytes lower in memory than the
beginning of the structure.
--
Topic: Set Page Size
Syntax: PAGE [[length], width]
Description:
Sets maximum number of lines per page (length) and maximum number
of characters per line (width) for listing files. Generates a page
break if no arguments are given. A zero for <width> means that the
assembler does not generate line breaks. A zero for <length> means
that the assembler does not generate page breaks.
The <length> parameter is a number between 10 to 255 lines (default
is 0). The <width> parameter is a number between 60 to 255
characters (default is 0). To specify width without changing the
default length, omit the length parameter and precede <width> with
a comma.
--
Topic: Cause a Page Break
Syntax: PAGE +
Description:
Causes a page break by inserting an ASCII form-feed character
(0Ch), increments the section number, and resets the page number
to 1. This directive is useful only with printer listings.
Program-listing page numbers use the following format:
section-page, where section is the section number within the
module, and page is the page number within the section. By
default, section and page numbers begin with 1-1.
--
Topic: Define Procedure
Syntax: label PROC [distance] [langtype] [visibility]
[<prologuearg>]
[USES reglist] [,parameter [:tag]]...
[LOCAL varlist]
statements
label ENDP
Description:
Defines a procedure called <label>. To use <parameter>, you must
have previously specified a language type or used the <langtype>
parameter. You should use a PROTO prototype before each procedure
defined with the PROC directive. This ensures proper type checking
and allows you to call the procedure with the INVOKE directive.
Procedures usually end with the RET instruction. You can remove
data from the stack by specifying the number of bytes as a
parameter of the RET instruction.
The assembler automatically generates PROLOGUE and EPILOGUE code
to pass stack arguments properly to the procedure and clean up the
stack after completion of the procedure. You can override the
default prologue and epilogue code with user-defined macros by
using the OPTION PROLOGUE: and OPTION EPILOGUE: directives.
The RETF or IRETF instructions do not cause the assembler to
generate epilogue code.
Procedures can be nested if they do not have parameters, local
variables or the USES parameter and do not generate a new segment
or group. You can avoid having to nest procedures by using the RETN
and RETF instructions.
Local variables must be declared (using the LOCAL directive)
before any instructions. There can be several LOCAL statements in
a procedure.
Parameter Description
label Defines name for the procedure. Follows naming
convention of <langtype>.
prologuearg Arguments to pass to the prologue procedure. With
the default PROLOGUE and EPILOGUE, the FORCEFRAME
argument generates a stack segment, even if one is
not necessary. LOADDS causes the DS register to be
saved in the PROLOGUE and restored in the EPILOGUE.
Parameters must be separated by commas. Angle brackets
are required but not passed.
distance NEAR, FAR, NEAR16, NEAR32, FAR16, or FAR32. Indicates
the call distance of this procedure. If you choose
NEAR or FAR, the assembler will select 16- or 32-bit
NEAR or FAR depending on the current segment size. If
you do not specify this option, the assembler
determines the distance from the memory model and
processor type. NEAR is the default if you do not use
the .MODEL directive.
langtype Any valid language type. Determines naming style
and calling convention.
visibility PRIVATE, PUBLIC, or EXPORT. Determines how the
procedure is made available to other modules. PUBLIC
is the standard default, but the default can be reset
with the OPTION PROC directive. EXPORT implies PUBLIC
and FAR and informs the linker that the procedure
should be placed in the export entry table.
reglist List of registers that the prologue preserves on the
stack and the epilogue restores on exit. Separate
multiple registers with spaces.
parameter Procedure parameter. The assembler translates
argument references into a direct reference to the
stack location. Separate multiple arguments with
commas.
tag Either a qualified type or VARARG. VARARG allows a
variable number of arguments to be passed as a
comma separated list to <argument>. If VARARG is
used, it must be applied to the last parameter of
the PROC directive. VARARG is only allowed with
the C, SYSCALL, and STDCALL language types. If <tag>
is omitted, the assembler defaults to WORD in a 16-bit
segment or DWORD in a 32-bit segment.
statements Assembly-language statements and directives.
--
Topic: Define a Procedure Prototype
Syntax: label PROTO [distance] [langtype] [, [parameter]:tag]...
Description:
Defines a prototype for a subsequent procedure. Informs the
assembler about how many and what kind of arguments should be
expected in a procedure definition. This allows the assembler
to perform type checking on arguments.
If you define a prototype for all stack-based procedures defined
with the PROC directive, you can place procedure prototypes in a
separate include file. This is recommended when using procedures
in a library file.
Parameter Description
label Defines name for the procedure. Must exactly match
<label> in PROC definition.
distance NEAR, FAR, NEAR16, NEAR32, FAR16, or FAR32.
Indicates the call distance of this procedure.
If you choose NEAR or FAR, the assembler will
select 16- or 32-bit NEAR and FAR depending on
the processor directive in effect. If you do not
specify this option, the assembler determines the
distance from the memory model and processor type.
NEAR is the default if you do not use the .MODEL
directive.
langtype Any valid language type. Determines naming style
and calling convention.
parameter Procedure parameter. The assembler translates
argument references into a direct reference to the
stack location. Separate multiple arguments with
commas.
tag Either a qualified type or VARARG. VARARG
allows a variable number of arguments to be passed
as a comma separated list to <argument>. If VARARG
is used, it must be applied to the last parameter
of the PROC directive. VARARG is only allowed with
the C, SYSCALL, and STDCALL language types.
--
Topic: Make Variable Public
Syntax: PUBLIC [langtype] name [,[langtype] name]...
Description:
Makes one or more variables available to other modules in the
program. PUBLIC names can be forward referenced.
The following can be made PUBLIC:
þ NEAR and FAR code labels and procedures
þ Data created with user-defined types, BYTE, WORD, and other
types
þ Data created with user-defined structures, unions, and records
þ Labels created with the LABEL directive
þ Symbolic constants created with EQU or =
The PUBLIC directive is normally used with the EXTERN directive.
The EXTERNDEF and COMM directives allow more flexibility in
global data declaration than the PUBLIC and EXTERN directives.
Parameter Description
langtype Any language type. Used to control what format
label names are sent to the linker.
name The name of a variable, label, or numeric equate
defined within the current source file
--
Topic: Delete Macros from Memory
Syntax: PURGE macroname [, macroname]...
Description:
Deletes one or more currently defined macros from memory. Use this
directive if your system does not have enough memory to keep all
the macros needed for a source file in memory at the same time.
The macro skeleton will remain, but it will not expand.
A macro can remove itself if PURGE is on the last line of the
macro. Redefining a macro automatically purges the previous
definition. Calling a purged macro is legal, but the macro will
act like a blank macro.
--
Topic: Push/Pop Assembler Settings
Syntax: PUSHCONTEXT context
POPCONTEXT context
Description:
PUSHCONTEXT stores the context information indicated in <context>.
POPCONTEXT restores the context information indicated in <context>.
You can nest PUSHCONTEXT directives up to 10 levels.
You can use these directives to save and restore the state of the
assembler in include files and procedures.
<context> Items Saved
ASSUMES Register assumptions
RADIX Current default radix
LISTING Listing and cref flags
CPU CPU and coprocessor directives
ALL All of the above
--
Topic: Set Default Radix (Number Base)
Syntax: .RADIX expression
Description:
Sets the default radix (base) for integer constants to the value
of <expression>. The default radix at the start of assembly is 10.
The .RADIX directive does not affect floating-point constants or
numbers that have explicit radix overrride tags:
Tag Base
H hexadecimal
O or Q octal
T decimal
Y binary
R floating point
With a radix of 10 or below, you can use the characters B (b) and D
(d) as the radix override characters for base 2 and base 10,
respectively.
The <expression> must evaluate to a decimal number in the range 2
to 16 and cannot contain forward references.
--
Topic: Declare Record
Syntax: recordname RECORD field [, field]...
Description:
Declares a record template of one or more specified bit fields
but does not allocate storage for the template. Separate multiple
fields with a comma.
Records can be used as constants or expressions. They are treated
as a BYTE or WORD with 16-bit expressions and as a BYTE, WORD, or
DWORD with 32-bit expressions. The sum of the widths for all fields
must not exceed the expression width.
Once a record template is declared, you can use it to define
record variables or constants, in which each field not initialized
assumes the default value. Records are defined with the following
syntaxes:
[name1] recordname {[initializer1] [, initializer2]...}
[name1] recordname <[initializer1] [, initializer2]...>
Use of <recordname> is similar to the other variable definition
directives (such as BYTE and WORD). Curly braces or angle brackets
are required even if no initializers are given.
If a record constant appears as part of an expression in a control
flow directive (such as .IF or .WHILE), you must use curly braces
instead of angle brackets to enclose the fields.
The assembler will treat the name of a record field without the
MASK or WIDTH operators as the bit number of the first bit of the
record field.
Parameter Description
recordname A unique symbolic name.
field Each field is in the form
fieldname:width[= expression]
where <width> is a constant giving the width of the
field (in bits) and <expression> optionally sets an
initial or default value.
--
Topic: Repeat Assembly of Block
Syntax: REPEAT expression
statements
ENDM
Description:
Assembles a block of statements <expression> times. REPT is a
synonym for REPEAT and is included for compatibility with previous
versions of the assembler.
The <expression> parameter must evaluate to a numeric constant. This
constant is evaluated during the first pass. The <statements> are
any valid assembler statements.
--
Topic: Define Segment
Syntax: name SEGMENT [align] [READONLY] [combine] [use] ['class']
statements
name ENDS
Description:
Defines a program segment called <SegName> with optional segment
attributes: align, READONLY, combine, use, and class. These
attributes give the linker and assembler information on how to set
up, combine, and refer to segments. A segment can be reopened within
a module by specifying the same <name> in a later SEGMENT statement.
The SEGMENT directive automatically saves any segment definition
that is already in effect. When the assembler encounters a closing
ENDS, it restores the saved segment definition.
Parameter Description
name Name of the segment being defined. You can use the
@CurSeg macro function with the ENDS directive to
terminate the current segment.
align BYTE, WORD (2 bytes), DWORD (4), PARA (16), or PAGE
(256). Aligns segment to boundary. PARA is the
default.
combine PRIVATE, PUBLIC, STACK, COMMON, MEMORY, or AT
address. Defines how the linker combines segments.
PRIVATE is the default.
use USE16, USE32, or FLAT. Selects the segment word size.
READONLY Makes segment read-only. The assembler will generate
an error if an instruction explicitly modifies a
segment marked with the READONLY attribute. Useful
for protected-mode code segments and segments in ROM.
class A class name (such as CODE or DATA). Must be enclosed
in quotation marks. Used to associate segments with
different names and to control segment order. Code
segments should have class 'CODE'.
--
Topic: Find String Length
Syntax: @SizeStr(string)
name SIZESTR textitem
Description:
The @SizeStr macro function returns the length of a text item in
characters. The @SizeStr function will not expand macros or
expressions unless you use the expression operator (%). A zero
indicates a null (empty) string.
The SIZESTR directive performs the same function but assigns the
result to <name>. These two lines are equivalent:
namelength TEXTEQU @SizeStr(<Denise>)
namelength SIZESTR <Denise>
;namelength is 6
The <name> is a unique symbolic name, <string> is a string, and
<textitem> must be a text item.
--
Topic: Start Stack Segment
Syntax: .STACK [size]
Description:
Creates the program stack segment (with segment name STACK) nested
inside the current segment, if any. The .MODEL directive must
precede this directive. The .MODEL directive generates a GROUP
statement that places the STACK segment in DGROUP unless the
FARSTACK attribute is given.
A single .STACK statement opens and closes the stack segment,
so you should not include an additional ENDS statement.
The <size> parameter specifies size of the stack in bytes (default
1024).
--
Topic: Generate Start-Up/Exit Code
Syntax: .STARTUP
.EXIT [expression]
Description:
The .STARTUP directive generates start-up code for the given CPU
type and the memory model, operating system, and stack type
defined by the .MODEL directive. Defines a start-address label,
so that you don't need to give a start address with END. .STARTUP
initializes DS, SS, and SP under DOS.
The .EXIT directive generates code that terminates the program and
returns control to the operating system or calling program. Use of
the <expression> parameter returns a numeric exit code to the
operating system or calling program.
The <expression> parameter is an optional return code that can be
read by the calling program or by a batch file. It can be a byte-
sized register (word-sized under OS_OS2), memory location, or
constant.
With the TINY model, the .STARTUP directive also generates an
ORG 100h.
The .MODEL directive must precede these directives. The default
OSType is DOS.
To use the .EXIT directive under OS/2, you must link with OS2.LIB
or a library that provides a termination procedure with a
prototype such as:
DosExit PROTO terminate: WORD, ; This is the prototype in
exitcode: WORD ; OS2.INC
--
Topic: Declare Structure Data Type
Syntax: name STRUCT [alignment] [, NONUNIQUE]
fielddeclarations
name ENDS
Description:
Declares a structure as a new data type. STRUC is a synonym for
STRUCT and is included for compatibility.
Once a structure name is declared, you can use it to define
variables in which each field not initialized assumes the default
value:
[name] structname <[initializer [, initializer]...]>
or
[name] structname { \
[initializer] \
[, initializer]... \
}
or
[name] structname constant DUP ({[initializer[, initializer]...]})
Curly braces or angle brackets are required even if no initializers
are given. The DUP operator can be used to make duplicate
initializations. Structures may be nested.
You must refer to structure members in the format
structurename.membername or with a pointer to a structure followed
by the .membername tag. You can use multiple sequential membernames
to specify elements of nested structures.
The NONUNIQUE parameter requies elements of the structure to be
accessed only by their fully specified names.
The ORG directive has a special meaning inside a STRUCT block.
Parameter Description
name A unique symbolic name for the structure.
alignment 1, 2, or 4. Byte boundary to align structure
fields. The default is 1.
fielddeclarations Any valid data definitions (using BYTE, WORD,
etc.) with initial values. Can also be another
previously defined structure or a user-defined
type. Field names do not need to be unique; you
can reuse the same name in multiple structures.
Some other directives are allowed in this field;
see the BNF Appendix in the MASM Programmer's
Guide.
initializer Data initializer for structure field.
--
Topic: Extract Characters from String
Syntax: @SubStr(string, start [,length])
name SUBSTR textitem, start [,length]
Description:
The @SubStr macro function extracts specified characters from a
text item. If <length> is not given, the function will return all
characters to the right of (and including) the character pointed
to by <start>. The @SubStr function will not expand macros or
expressions unless you use the expression operator (%).
The SUBSTR directive performs the same function but assigns the
result to <name>. These two lines are equivalent:
country TEXTEQU @SUBSTR (<AndorraMonacoLuxembourg>,8,6)
country SUBSTR <AndorraMonacoLuxembourg>,8,6
;country is <Monaco>
Parameter Description
name A unique symbolic name.
string A string to extract characters from.
textitem A text item to extract characters from.
start Starting position of substring; the first character
is indexed as 1. Must be a positive integer constant.
length Number of characters to extract. Must be a positive
integer constant.
--
Topic: Toggle .LISTIF/.NOLISTIF
Syntax: .TFCOND
Description:
Toggles the state of the assembler between .LISTIF and .NOLISTIF,
determining whether or not false conditional blocks are included
in assembler listings.
--
Topic: Specify Title/Subtitle
Syntax: TITLE text
SUBTITLE text
Description:
The TITLE directive specifies the title to be used on each page
of assembly listings. The <text> is printed flush left on the
second line of every page of the listing. Only one TITLE directive
per module is allowed.
The SUBTITLE directive specifies the subtitle to be used on each
page of assembly listings. The <text> is printed flush left on the
third line of every page of the listing. Each new SUBTITLE
statement replaces the current subtitle; the change will be
displayed on the next page of the output. SUBTTL is a synonym of
SUBTITLE and is included for compatibility with previous versions
of the assembler.
The <text> is any combination of characters up to 60 characters.
--
Topic: Define Type Symbol
Syntax: name TYPEDEF qualifiedtype
name TYPEDEF PROTO prototypelist
Description:
Defines a new type or creates a synonym for an already defined
type. The TYPEDEF directive associates <name> with a type, and,
once defined, the symbol can be used anywhere a type can be used
or as a data declaration directive. The <qualifiedtype> parameter
can specify a pointer to a qualified type. The TYPEDEF PROTO
syntax defines a prototype type.
Once a type is defined, you can use it to define variables. Use is
similar to the other variable definition directives (like BYTE and
WORD).
Parameter Description
qualifiedtype Any qualified type. Can include a type
previously defined by a TYPEDEF directive, but
recursive definitions are not allowed.
prototypelist List of parameters for procedure prototype. Uses
the same syntax as the PROTO directive.
--
Topic: Declare Union as Data Type
Syntax: name UNION [alignment] [, NONUNIQUE]
fielddeclarations
[name] ENDS
Description:
Declares a union as a new data type. Allows the same memory
locations to be overlapped with different types. Identical to
STRUCT except that each member has a 0 offset. The size of the
union is the size of the largest member of the union.
Unions can be used to store one type of data in some circumstances
and another type in a different situation. Unions also allow you
to store data as one data type and then read it as another. Unions
are initialized by using the union name as a data declaration
directive. You only need to initialize a union for one data type.
You must refer to union members by their member names. The LABEL
directive allows you to refer to the entire union as a unit.
The first-level definition of a union must include the <name>
label preceding the ENDS. In nested unions, terminate the block
with a ENDS statement without the <name> label.
The <alignment> field determines the byte alignment of any
structures. This field can be 1, 2, or 4. The default is 1, unless
overridden by the /Zp command-line option or the
ALIGN or EVEN directives.
The NONUNIQUE parameter allows elements of the union to be
accessed only by their fully specified names.
Some directives are allowed in the <fielddeclarations> field;
see the BNF Appendix in the MASM Programmer's Guide.
Example:
EXTENDCHAR UNION
ascii BYTE ? ;Define a union of byte and
kanji WORD ? ; word
EXTENDCHAR ENDS
initial EXTENDCHAR <J> ;Create a union variable
mov al, initial.ascii ;Move byte-length data
mov bx, initial.kanji ;Move word-length data
--
Topic: Assemble While Expression is True
Syntax: WHILE expression
statements
ENDM
Description:
Marks a block of statements to be assembled repeatedly until
<expression> is false (zero). The <expression> is a constant
expression whose value is computed at assembly time.
--
Topic: Labeling Punctuation (:/::)
Syntax: label:
label::
:macrolabel
register::register
Description:
Gives name <label> to the memory location of the next instruction
or piece of data. Can be target of loop, branch, jump, load, or
any instruction or directive that requires a memory location.
The register::register syntax is independent of this definition. In
this case, the double-colon is used as a delimiter for a register
pair passed with the INVOKE directive.
With the single colon, <label> has global scope within its
module under the default OPTION NOSCOPED. Under OPTION SCOPED,
<label> is LOCAL inside a PROC block and is global elsewhere.
The <label> cannot be declared public.
The double colon acts the same as the single colon except that
<label> has global scope within its module, independent of OPTION
SCOPED, and can be declared PUBLIC.
The :macrolabel labeling syntax is used exclusively inside MACRO,
FOR, FORC, REPEAT, and WHILE blocks. It can be used only as the
destination of the GOTO directive.
--
Topic: Segment Override Operator (:)
Syntax: segment:expression
Description:
Overrides the default segment of <expression> with <segment>.
Forces the address of the variable or label to be computed
relative to the specified segment.
Parameter Description
segment A segment register (CS, DS, SS, ES, FS, or GS),
group name, segment name, or segment expression.
expression A memory expression.
--
Topic: Structure Field Reference (.)
Syntax: expression.field[.field]...
expression2.structtype.field[.field]...
Description:
Returns the offset of <expression> plus the value of <field>. This
operator is usually used to access a field of data within a structure
or union variable. You can use several dot operators to access nested
structures.
Parameter Description
expression1 An expression for which the qualified type is a
structure
expression2 An arbitrary expression.
structtype A defined structure type.
field A field within a previously defined structure type.
Each field has an offset relative to the beginning
of the structure.
Example:
DPSTRUCT STRUCT ; Memory-mapped dsp
ctrlreg WORD ? ; data structure
addrreg DWORD ?
DPSTRUCT ENDS
IOSTRUCT STRUCT ; Set up nested structure
vio VIDEOSTRUCT <> ; for I/O
dsp DPSTRUCT <> ;
IOSTRUCT ENDS
ioInst IOSTRUCT <> ; Instance of IOSTRUCT
lea ax, (IOSTRUCT PTR [bx]).\ ; Loads offset of
dsp.ctrlreg ; ctrlreg element of I/O
; structure pointed to
; by the bx register
assume bx:PTR IOSTRUCT
lea ax, [bx].dsp.ctrlreg ; Same as above code line
mov ioInst.dsp.ctrlreg, 10h ; Set control register to 10
--
Topic: Index ([])
Syntax: expression1[expression2]
Description:
The brackets (also called the "index operator") return the sum of
<expression1> and <expression2>. If <expression2> is a register,
the brackets indicate an indirect memory operand rather than a
register-direct operand.
In the syntax above, the brackets are literal and must be
included. The expression outside the brackets is optional. You
cannot add two direct memory operands.
--
Topic: String Delimiters ("/')
Syntax: "text"
'text'
Description:
Treats <text> as a string. You can use single or double quotation
marks, but the quotation marks on both sides of <text> must be
identical. A string can be up to 255 characters long and must be
on a single physical line. You can use a quotation mark inside a
string by repeating it twice in a row ("" or ''). The left-hand
single quotation mark (`) is not allowed as a delimiter.
Example:
quote1 BYTE "This was called by 'int 23h'"
quote2 BYTE 'This was called by "int 23h"'
quote3 BYTE "Use the ""ASSUME"" directive"
quote4 BYTE 'Use the ''ASSUME'' directive'
--
Topic: Literal Text Operator (<>)
Syntax: <text>
Description:
Treats <text> as a single literal string.
Angle brackets are often used in macro calls and with the FOR
directive to ensure that values in a parameter list are treated as
a single parameter. For example,
MyMacro <one, two, three> ;Passes one argument to
;MyMacro
MyMacro one, two, three ;Passes three arguments to
;MyMacro
The assembler removes one set of angle brackets each time it
inserts an argument into a macro expansion.
The <text> is any name, number, or expression. It can contain
commas, spaces, tabs, or semicolons. The exclamation point (!) is
an escape character that allows you to include special characters
such as the semicolon, ampersand, and quotation marks.
--
Topic: Literal Character Operator (!)
Syntax: !character
Description:
Treats <character> as a literal character rather than as an
operator or a symbol. Used with special characters (<, >, ", ', %,
;, and comma) when the usual assembly language meaning of the
character must be suppressed. A double exclamation point (!!) is
treated as a single exclamation point. The escape character does
not apply to strings in quotation marks or to backslashes at the
end of a line.
For example:
<I!'m afraid I can!'t do that!!>
--
Topic: Comment Delimiter (;/;;)
Syntax: ;text
;;text
Description:
The single semicolon treats <text> to the end of the line as a
comment. The double semicolon treats <text> to the end of the
line as a macro comment. In a listing file, macro comments appear
with the macro definition, not with the macro expansion.
Comments must follow all other fields in a statement line.
--
Topic: Expression Operator (%)
Syntax: %expression
Description:
Computes the value of <expression> and treats it as a text string.
Use in macro calls when you need to pass the result of an
expression rather than the actual expression to a macro. The
<expression> can also be a text macro or a macro function.
When placed at the beginning of the line, % causes the
calculation and substitution of all text macros on that line,
including those inside angle brackets (<>). Macro function calls
inside angle brackets (<>) are not expanded unless precedes by a
%.
--
Topic: Substitution Operator (&)
Syntax: ¶meter&
Description:
Operator used within a macro or a repeat block; enables parameter
substitution for <parameter>. Two parameters can be joined to form
one symbol. You can join any number of parameters with the
ampersand operator.
You can also use this operator to force parameter substitution in
a quoted string. For this reason, if you want an ampersand to be
included in a string, you must use the string escape character (!)
before the &.
Use ampersands (&) only around macro parameters, in quoted strings,
and inside angle brackets (<>). Each parameter to be substituted
must have one ampersand on the left and right. If an ampersand is
adjacent to white space, it can be omitted as long as one
ampersand is next to each parameter to be substituted.
Example:
Guard MACRO Prisonernum:REQ, Prisonername:=Anonymous
ECHO <Number &Prisonernum has arrived at &@Time.>
EXITM Prisonernum&&Prisonername
ENDM
Badge Guard 2
--
Topic: Repeat Declaration Operator
Syntax: count DUP (initialvalue [,initialvalue]...)
Description:
Specifies <count> declarations of <initialvalue>. You can define
arrays, buffers, and other data structures consisting of multiple
data objects of the same size with the DUP operator. The
<initialvalue> parameters must be inside parentheses. This
operator can be used with data definition directives.
The <count> parameter is the number of declarations of
<initialvalue>. This parameter cannot be negative or
forward-referenced. The <initialvalue> parameter is either the
undefined data symbol (?), a string, a constant expression, or
another DUP operator. The value or values of <initialvalue> are
evaluated once before duplication. Separate multiple initial
values with commas.
--
Topic: High/Low-Order Byte
Syntax: HIGH expression
LOW expression
Description:
The HIGH operator returns the high-order (most significant) byte
of <expression> in two's-complement form. The LOW operator returns
the low-order (least significant) byte of <expression> in two's-
complement form. The <expression> must resolve to a constant or
an OFFSET expression.
--
Topic: High/Low-Order Word
Syntax: HIGHWORD expression
LOWWORD expression
Description:
The HIGHWORD operator returns the high-order (most significant)
word of <expression> in two's-complement form. The LOW operator
returns the low-order (least significant) word of <expression> in
two's- complement form. The <expression> must resolve to a constant
or an OFFSET expression.
--
Topic: Variable Length
Syntax: LENGTHOF variable
SIZEOF variable
SIZEOF type
LENGTH expression
SIZE expression
Description:
The LENGTHOF operator returns the number of data items allocated
for <variable>. The SIZEOF operator returns the total number of
bytes allocated for <variable> or the size of <type> in bytes. For
variables, SIZEOF is equal to the value of LENGTHOF times the
number of bytes in each element.
The LENGTH and SIZE operators are allowed for compatibility with
previous versions of the assembler. When applied to a data label,
the LENGTH operator returns the number of elements created by the
DUP operator; otherwise it returns 1. When applied to a data
label, the SIZE operator returns the number of bytes allocated by
the first initializer at the <variable> label.
--
Topic: Bit Mask
Syntax: MASK record
MASK recordfieldname
Description:
Returns a bit mask for the bit positions in a record or record
field. A bit in the mask contains a 1 if that bit corresponds to
a field bit. All other bits contain 0.
The <record> parameter is the name of any record. The
<recordfieldname> parameter is the name of any field in a record.
--
Topic: Offset Address
Syntax: OFFSET expression
Description:
Returns offset address of <expression> (usually a variable). The
value returned by the OFFSET operator is an immediate operand.
OFFSET can be applied to any immediate or memory expression
except a register or segment.
The offset returned is relative to either the current group
or segment. If there is both a current group and a current
segment, the offset will have a group-relative default offset.
This default can be changed with the M510 and OFFSET: options.
The OFFSET operator can accept an expression specifying a segment.
In this case, the OFFSET operator returns the offset of the last
byte of the given segment, relative to that segment's group. This
value reflects the size of the given segment when the OFFSET
operator is assembled.
The <expression> is any label, variable, segment, or other direct
memory operand.
--
Topic: Loader-Resolved Offset
Syntax: LROFFSET expression
Description:
Similar to OFFSET, but causes the offset to be resolved by the
loader at run time. LROFFSET is usually applied to the offset of
a function pointer. This run-time resolution allows Microsoft
Windows to relocate code segments in real mode.
The <expression> is any label, variable, or other direct memory
operand.
Example:
INVOKE CreateRoutine, LROFFSET MyFunc, 0
--
Topic: Specify Type for Expression
Syntax: qualifiedtype PTR expression
PTR qualifiedtype
Description:
The first syntax treats <expression> as having the specified type.
Type casting can be used with forward references or unlabeled
addresses to specify a reference size, type, or distance.
The second syntax is used in defining qualified types.
The PTR keyword can also appear in qualified types to indicate
that the type is a pointer variable.
The <qualifiedtype> can be any qualified type. The <expression>
can be any valid expression. If <qualifiedtype> is a distance,
<expression> cannot be a memory expresssion or a data label.
Example:
mov ax, (MyStruct PTR [bx]).Username
fld TBYTE PTR MaxConvolution
INVOKE MyRoutine, PTR TempValue
--
Topic: Return Segment or Group of Expression
Syntax: SEG expression
Description:
Returns the segment or group of <expression>. If <expression> does
not have an explicit segment or group, SEG returns the segment or
group of the SEG expression itself. If the SEG expression has no
segment or group, SEG returns the value of <expression>.
The <expression> is any label, variable, group name, or other
memory operand; it cannot be a constant.
--
Topic: Force Label Type to SHORT
Syntax: SHORT label
Description:
Forces <label> type to SHORT. Normally, the assembler selects
short jumps and branches when possible, but SHORT can be used to
generate an error if a short jump to <label> is not possible. It
disables any automatic conditional-jump lengthening (OPTION LJMP).
Short labels can be used in JMP instructions when the distance is
less than 128 bytes from the start of the next instruction. This
saves a byte of memory and reduces the number of clock cycles used.
--
Topic: Specify Same Operand Type
Syntax: THIS qualifiedtype
Description:
Returns an operand of <qualifiedtype> with offset and segment
values equal to the current location-counter value. THIS can be
used with EQU or = to create labels and variables. THIS NEAR is
equivalent to $.
These two lines are equivalent:
tag1 EQU THIS BYTE
tag1 LABEL BYTE
The <qualifiedtype> can be any qualified type.
--
Topic: Return Expression Attributes
Syntax: TYPE expression
Description:
The TYPE operator returns a value and size and distance attributes
appropriate to <expression>. You can use the constant returned by
TYPE directly or use the attributes returned by TYPE. For example,
you can use the returned attribute to specify a type for PTR.
<expression> Returns
Variable Number of bytes allocated for each element
Structure Total number of bytes in the structure
Constant 0
Code label Distance
Register Size of register in bytes
--
Topic: OPATTR Operator
Syntax: OPATTR expression
.TYPE expression
Description:
The OPATTR operator returns a one-word constant defining the mode
and scope of expression. If <expression> is not valid or is forward-
referenced, OPATTR returns a 0. If <expression> is valid, a
nonrelocatable word is returned. The .TYPE operator returns only the
low byte (bits 0-7) of the OPATTR operator and is included for
compatibility with previous versions of the assembler.
Bit Set If
Position <expression>
0 References a code label
1 Is a memory expression or has a relocatable data
label
2 Is an immediate expression
3 Uses direct memory addressing
4 Is a register expression
5 References no undefined symbols and is without error
6 Is an SS-relative memory expression
7 References an external label
8-11 Language type:
Bits Language
000 No language type
001 C
010 SYSCALL
011 STDCALL
100 Pascal
101 FORTRAN
110 Basic
All other bits are undefined and reserved for future expansion.
--
Topic: Record/Record-Field Width
Syntax: WIDTH {recordfieldname³record}
Description:
Returns width (in bits) allocated for a record or record field.
The <recordfieldname> is the name of any field defined in any
record. The <record> is the name of any defined record.
--
Topic: Local Code Labels
Syntax: [instruction] @F
.
.
.
@@: [statement]
.
.
.
[instruction] @B
Description:
The @@: label defines a local code label, which is in effect until
the next instance of @@:. The @F and @B operands can be used in
conditional and unconditional jump statements to jump to the next
and previous @@: label respectively.
The @@: label is useful for defining a nearby jump point where a
full label is not appropriate.
Example:
cmp ax, 18h
jg @F
ù ;Less than or equal
ù
ù
@@: ;Greater than
mov cx, 640 ;Set count
@@:
ù ;Loop statements
ù
ù
loop @B ;Loop back
--
Topic: Line-Continuation (\) Operator
Syntax: text \
text
Description:
Enables an assembly-language statement to continue on the next
line, ignoring the line break. You can join any number of physical
lines with this method. A backslash occurring inside a comment
or string is not considered to be a line-continuation character.
Logical lines cannot exceed a total of 512 characters.
Comments can appear to the right of the \. A backslash is not
required on a line ending with a comma.
--
Topic: Redefinable Numeric Equate
Syntax: name = expression
Description:
Creates or redefines a constant symbol by assigning the numeric
value of <expression> to <name>. This equate can be used in
subsequent statements as a symbolic constant and can be redefined
at any time.
The <name> field must be either a unique name or one previously
defined with =. The <expression> fieldis any valid constant
expression. Resolved at definition by the assembler.
--
Topic: Current Offset ($) Value
Syntax: $
Description:
Equates to the current value of the location counter (current
offset address). Equivalent to THIS NEAR.
Example:
title BYTE "Space Mutants II"
level WORD 0
hiscore BYTE 20 DUP (?)
tablelen EQU $-title ;tablelen = 38
--
Topic: Uninitialized Value (?)
Syntax: ?
Description:
Used as an initializer in data declarations; indicates a value
that the assembler allocates but does not initialize. Can be used
alone or with DUP, as in the following examples:
Extension WORD ? ; Allocate 1 uninitialized word
Initials BYTE ?,?,? ; Allocate 3 uninitialized bytes
Fullname BYTE 20 DUP (?) ; Allocate 20 uninitialized bytes
To minimize the size of executable files, use the .DATA? or .FARDATA?
directives to define an undefined data segment. Put undefined data
in these segments.
--
Topic: Arithmetic Operators
Unary Binary Scaling
ÚÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄ¿
+ ³ X ³ X ³ ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄ´
- ³ X ³ X ³ ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄ´
* ³ ³ X ³ X ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄ´
/ ³ ³ X ³ ³
ÃÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄÅÄÄÄÄÄÄÄ´
MOD ³ ³ X ³ ³
ÀÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÁÄÄÄÄÄÄÄÙ
Description:
All of these operators can be used with two operands to calculate
a numeric result. The minus (-) operator can be placed in front of
an expression to negate its value. The plus (+) operator can also
be placed before an expression, but it has no effect. The modulus
(MOD) operator can only operate on integer expressions. The
multiplication (*) operator can be used to scale index registers
on 80386/486 processors. For example:
.386
movzx eax, 10
mov bx, base [eax*2]
ù
ù
ù
inc eax
--
Topic: Logical and Shift Operators
Syntax: expression1 AND expression2
expression1 OR expression2
expression1 XOR expression2
NOT expression
expression SHL count
expression SHR count
Description:
These operators perform logical manipulations of constant integer
expressions. They return expressions of the size determined by the
current expression size. Use the LOW and LOWWORD operators to
return expressions of smaller sizes.
These operators should not be confused with their instruction
counterparts. Operators cannot act on registers or memory.
Operand Description
expression Any constant integer expression in any valid radix.
count The number of bits to be shifted. Must be a
constant positive integer. Bits shifted in are
always 0.
--
Topic: Relational Operators
Syntax: expression1 EQ expression2
expression1 NE expression2
expression1 GT expression2
expression1 LT expression2
expression1 GE expression2
expression1 LE expression2
Description:
The EQ, NE, GT, LT, GE, and LE relational operators determine if
two constant expressions or data labels (in the same segment)
are equal, not equal, greater than, less than, greater than or
equal, or less than or equal to each other. The comparison returns
true (-1) or false (0).
These operators work only with assembler symbols and constants;
they cannot be used to evaluate registers or memory locations.
--
