Assembly Language Processor (ALP) Assembler Reference

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

About this Reference

The following notations are used in this reference:

KEYWORD	Commands and language keywords.
KEYWORD	The default value for a command or language keyword when multiple values are possible but none are actually specified.
Phrase	Typically indicates a hypertext link to a separate panel containing a description for that phrase.
Parameter	Parameters whose actual names or values are to be supplied by the programmer.
Definition	A term being defined for the first time, or special emphasis.
Subscript	Subscripted text.
Superscript	Superscripted text (other than ý).
<Name>	A text value represented by "Name" is to be substituted in place of <Name> typically at assembler run-time.

Assembly Language Processor (ALP) Overview

The Assembly Language Processor (ALP) is an assembler that runs under OS/2 Warp. ALP is a functional replacement for the Microsoft Macro Assembler (MASM) and accepts:

• The full syntax of the Intel 80X86 architecture
• The full syntax of the MASM 5.10 high-level directive language
• A subset of the MASM 6.00 high-level directive language

ALP generates standard Object Module Format (OMF) files that can be linked to produce DOS or OS/2 executables. It can also generate symbolic debugging information compatible with the IBM family of source code debuggers. A MASM 5.10-compatible command line utility (MASM2ALP) is also provided to enable use of ALP with little or no change to existing build environments.

ALP also offers a rich set of command line options, as well as a comprehensive listing output cabability that is highly configurable, allowing a visual perspective not possible with other assemblers.

• Installation

• Understanding ALP

• Using ALP

Language Elements

Description

The following sections describe the elements you use to build an ALP program source file.

Character Set

All elements in an assembler language source file are built from collections of characters contained in the character set, which are defined as:

• The uppercase and lowercase letters of the English alphabet
• The decimal digits 0 through 9
• The following graphic characters:

~   !   "   #   $   %   ^   &   '   (   )   | 
*   +   ,   -   .   /   :   ;   =   <   >   ? 
[   \   ]   _   {   }   @ 

• The space and horizontal tab characters
• The end of line character(s)

White Space

White space is a character or contiguous stream of characters that is ignored or removed from the input stream by the ALP preprocessor.

White space characters are any contiguous sequence of one or more space or tab characters not enclosed in single or double quotes. White space characters are significant only in that they serve to separate language tokens from one another; they are removed from the input stream by the scanner.

Syntax

Token:

Reserved-Word

Identifier

Literal

Punctuator

Reserved Words

Description

This section describes all of the assembler reserved words.

Syntax

Reserved-Word:

Preprocessor-Directive

Assembler-Directive

Processor-Mnemonic

Processor-Register

Scalar-TypeName

Distance-TypeName

Language-Name

Anonymous-Label-Alias

Location-Counter-Alias

Indeterminate-Value-Alias

Directive-Keyword

Operator-Keyword

Preprocessor Directives

Description

Preprocessor Directives are symbolic names that describe the various assembly-time text processing instructions interpreted by the preprocessor phase of the assembler.

Syntax

Preprocessor-Directive: one of

CATSTR      COMMENT     ELSE        ELSEIF
ELSEIF1     ELSEIF2     ELSEIFB     ELSEIFDEF
ELSEIFDIF   ELSEIFDIFI  ELSEIFE     ELSEIFIDN
ELSEIFIDNI  ELSEIFNB    ELSEIFNDEF  ENDIF
ENDM        EQU         EXITM       FOR
FORC        IF          IF1         IF2
IFB         IFDEF       IFDIF       IFDIFI
IFE         IFIDN       IFIDNI      IFNB
IFNDEF      INCLUDE     INSTR       IRP
IRPC        LOCAL       MACRO       PURGE
REPEAT      REPT        SIZESTR     SUBSTR

Assembler Directives

Description

Assembler Directives are symbolic names that describe the various assembly-time instructions interpreted by the assembler itself.

Syntax

Assembler-Directive: one of

.186          .286          .286C         .286P
.287          .386          .386C         .386P
.387          .486          .486C         .486P
.586          .586P         .686          .686P
.8086         .8087          ALIGN        .ALPHA
 ASSUME       %BIN          .CODE          COMM
.CONST        .CREF         .DATA         .DATA?
 DB            DD            DF            DOSSEG
.DOSSEG        DQ            DT            DW
 ECHO          END           ENDP          ENDS
 EQU          .ERR          .ERR1         .ERR2
.ERRB         .ERRDEF       .ERRDIF       .ERRDIFI
.ERRE         .ERRIDN       .ERRIDNI      .ERRNB
.ERRNDEF      .ERRNZ         EVEN          EXTERN
 EXTERNDEF     EXTRN        .FARDATA      .FARDATA?
 GROUP         INCLUDELIB    LABEL        .LALL
.LFCOND       .LIST         .LISTALL      .LISTIF
.LISTMACRO    .LISTMACROALL  LOCAL        .MMX
.MODEL         NAME         .NOCREF       .NOLIST
.NOLISTIF     .NOLISTMACRO  .NOMMX         OPTION
 ORG          %OUT           PAGE          PROC
 PUBLIC       .RADIX         RECORD       .SALL
 SEGMENT      .SEQ          .SFCOND       .STACK
 STRUC         STRUCT        SUBTITLE      SUBTTL
.TFCOND        TITLE         TYPEDEF       UNION
.XALL         .XCREF        .XLIST

Processor Mnemonics

Description

Processor Mnemonics are symbolic names given to the various instructions in the processor instruction set.

Syntax

Processor-Mnemonic: one of

AAA        AAD        AAM        AAS        ADC
ADD        AND        ARPL       BOUND      BSF
BSR        BSWAP      BT         BTC        BTR
BTS        CALL       CBW        CDQ        CLC
CLD        CLI        CLTS       CMC        CMOVA
CMOVAE     CMOVB      CMOVBE     CMOVC      CMOVE
CMOVG      CMOVGE     CMOVL      CMOVLE     CMOVNA
CMOVNAE    CMOVNB     CMOVNBE    CMOVNC     CMOVNE
CMOVNG     CMOVNGE    CMOVNL     CMOVNLE    CMOVNO
CMOVNP     CMOVNS     CMOVNZ     CMOVO      CMOVP
CMOVPE     CMOVPO     CMOVS      CMOVZ      CMP
CMPS       CMPSB      CMPSD      CMPSW      CMPXCHG
CMPXCHG8B  CPUID      CWD        CWDE       DAA
DAS        DEC        DIV        EMMS       ENTER
ESC        F2XM1      FABS       FADD       FADDP
FBLD       FBSTP      FCHS       FCLEX      FCMOVB
FCMOVBE    FCMOVE     FCMOVNB    FCMOVNBE   FCMOVNE
FCMOVNU    FCMOVU     FCOM       FCOMI      FCOMIP
FCOMP      FCOMPP     FCOS       FDECSTP    FDISI
FDIV       FDIVP      FDIVR      FDIVRP     FENI
FFREE      FIADD      FICOM      FICOMP     FIDIV
FIDIVR     FILD       FIMUL      FINCSTP    FINIT
FIST       FISTP      FISUB      FISUBR     FLD
FLD1       FLDCW      FLDENV     FLDENVD    FLDENVW
FLDL2E     FLDL2T     FLDLG2     FLDLN2     FLDPI
FLDZ       FMUL       FMULP      FNCLEX     FNDISI
FNENI      FNINIT     FNOP       FNSAVE     FNSAVED
FNSAVEW    FNSTCW     FNSTENV    FNSTENVD   FNSTENVW
FNSTSW     FPATAN     FPREM      FPREM1     FPTAN
FRNDINT    FRSTOR     FRSTORD    FRSTORW    FSAVE
FSAVED     FSAVEW     FSCALE     FSETPM     FSIN
FSINCOS    FSQRT      FST        FSTCW      FSTENV
FSTENVD    FSTENVW    FSTP       FSTSW      FSUB
FSUBP      FSUBR      FSUBRP     FTST       FUCOM
FUCOMI     FUCOMIP    FUCOMP     FUCOMPP    FWAIT
FXAM       FXCH       FXTRACT    FYL2X      FYL2XP1
HLT        IDIV       IMUL       IN         INC
INS        INSB       INSD       INSW       INT
INTO       INVD       INVLPG     IRET       IRETD
IRETDF     IRETF      JA         JAE        JB
JBE        JC         JCXZ       JE         JECXZ
JG         JGE        JL         JLE        JMP
JNA        JNAE       JNB        JNBE       JNC
JNE        JNG        JNGE       JNL        JNLE
JNO        JNP        JNS        JNZ        JO
JP         JPE        JPO        JS         JZ
LAHF       LAR        LDS        LEA        LEAVE 
LES        LFS        LGDT       LGS        LIDT 
LLDT       LMSW       LOCK       LODS       LODSB 
LODSD      LODSW      LOOP       LOOPD      LOOPE 
LOOPED     LOOPEW     LOOPNE     LOOPNED    LOOPNEW 
LOOPNZ     LOOPNZD    LOOPNZW    LOOPW      LOOPZ 
LOOPZD     LOOPZW     LSL        LSS        LTR 
MOV        MOVD       MOVQ       MOVS       MOVSB 
MOVSD      MOVSW      MOVSX      MOVZX      MUL 
NEG        NOP        NOT        OR         OUT 
OUTS       OUTSB      OUTSD      OUTSW      PACKSSDW 
PACKSSWB   PACKUSWB   PADDB      PADDD      PADDSB 
PADDSW     PADDUSB    PADDUSW    PADDW      PAND 
PANDN      PCMPEQB    PCMPEQD    PCMPEQW    PCMPGTB 
PCMPGTD    PCMPGTW    PMADDWD    PMULHW     PMULLW 
POP        POPA       POPAD      POPD       POPF 
POPFD      POPW       POR        PSLLD      PSLLQ 
PSLLW      PSRAD      PSRAW      PSRLD      PSRLQ 
PSRLW      PSUBB      PSUBD      PSUBSB     PSUBSW 
PSUBUSB    PSUBUSW    PSUBW      PUNPCKHBW  PUNPCKHDQ 
PUNPCKHWD  PUNPCKLBW  PUNPCKLDQ  PUNPCKLWD  PUSH 
PUSHA      PUSHAD     PUSHD      PUSHF      PUSHFD 
PUSHW      PXOR       RCL        RCR        RDMSR 
RDPMC      RDTSC      REP        REPE       REPNE 
REPNZ      REPZ       RET        RETF       RETN 
ROL        ROR        RSM        SAHF       SAL 
SAR        SBB        SCAS       SCASB      SCASD 
SCASW      SETA       SETAE      SETB       SETBE 
SETC       SETE       SETG       SETGE      SETL 
SETLE      SETNA      SETNAE     SETNB      SETNBE 
SETNC      SETNE      SETNG      SETNGE     SETNL 
SETNLE     SETNO      SETNP      SETNS      SETNZ 
SETO       SETP       SETPE      SETPO      SETS 
SETZ       SGDT       SHL        SHLD       SHR 
SHRD       SIDT       SLDT       SMSW       STC 
STD        STI        STOS       STOSB      STOSD 
STOSW      STR        SUB        TEST       UC2 
VERR       VERW       WAIT       WBINVD     WRMSR 
XADD       XCHG       XLAT       XLATB      XOR

Processor Registers

Description

Processor Registers are the symbolic names assigned to the various internal processor registers. They are normally used as operands to processor instructions.

Syntax

Processor-Register:

General-Purpose-Register

Segment-Register

Control-Register

Debug-Register

Test-Register

MMX-Register

Floating-Point-Register

General-Purpose-Register:

8-Bit-Register

16-Bit-Register

32-Bit-Register

8-Bit-Register: one of

AL AH BL BH CL CH DL DH

16-Bit-Register: one of

AX BX CX DX DI SI BP SP

32-Bit-Register: one of

EAX EBX ECX EDX EDI ESI EBP ESP

Segment-Register: one of

CS DS ES FS GS SS

Control-Register: one of

CR0 CR2 CR3 CR4

Debug-Register: one of

DR0 DR1 DR2 DR3 DR4 DR5 DR6 DR7

Test-Register: one of

TR3 TR4 TR5 TR6 TR7

MMX-Register: one of

MM0 MM1 MM2 MM3 MM4 MM5 MM6 MM7

Floating-Point-Register: ST

Scalar Type Names

Description

Scalar Type Names are the symbolic names given to the integral data types. These are the fundamental types of data upon which the processor can directly operate.

Syntax

Scalar-TypeName:

BYTE

SBYTE

WORD

SWORD

DWORD

SDWORD

REAL4

FWORD

QWORD

REAL8

TBYTE

REAL10

Distance Type Names

Description

Distance Type Names are the symbolic names given to the integral types of pointers directly supported by the processor. Their names reflect a fundamental property of the Intel processor architecture known as distance. The type of pointer is defined by the distance required to reach the information to which it points.

Syntax

Distance-TypeName:

NEAR

NEAR16

NEAR32

FAR

FAR16

FAR32

Language Names

Description

Language Names refer to the various high level programming languages (or more specifically, the calling conventions used by such languages) with which the assembler has the ability to interface.

Syntax

Language-Name:

C

SYSCALL

STDCALL

PASCAL

FORTRAN

BASIC

OPTLINK

Anonymous Label Aliases

Description

The Anonymous Label Aliases are reserved symbolic names that return a context-sensitive value when referenced in expressions.

The reserved name @B (backward reference) returns the internally generated name representing the nearest @@: code label appearing before the current location in the input stream.

The reserved name @F (forward reference) returns the internally generated name representing the nearest @@: code label appearing after the current location in the input stream.

Syntax

Anonymous-Label-Alias:

@B

@F

Location Counter Alias

Description

The Location Counter Alias is a reserved name used in expressions to return the offset within the current segment or structure being assembled.

Syntax

Location-Counter-Alias:

$

Indeterminate Value Alias

Description

The Indeterminate Value Alias is a reserved name used in expressions to represent an uninitialized value.

Syntax

Indeterminate-Value-Alias:

?

Directive Keywords

Description

Directive Keywords are symbolic names recognized and used in the body of various assembler directives.

Syntax

Directive-Keyword:

ABS         AT            BASIC         C
CASEMAP     CODE          COMMON        DOTNAME
EMULATOR    EPILOGUE      ERROR         EXPORT
EXPR16      EXPR32        FARSTACK      FLAT
FORTRAN     HUGE          LANGUAGE      LARGE
LJMP        MEDIUM        NEARSTACK     NODOTNAME
NOEMULATOR  NOKEYWORD     NOLANGUAGE    NOLJMP
NONE        NOOLDMACROS   NOOLDSTRUCTS  NOREADONLY
NOSCOPED    NOSIGNEXTEND  NOTHING       NOTPUBLIC
OLDMACROS   OLDSTRUCTS    OPTLINK       OS_DOS
OS_OS2      PAGE          PARA          PASCAL
PRIVATE     PROC          PROLOGUE      PUBLIC
READONLY    SCOPED        SEGMENT       SIGNEXTEND
SMALL       STACK         STDCALL       SYSCALL
TINY        USE16         USE32         USES

Operator Keywords

Description

Operator Keywords are symbolic names used in expressions to denote an operation to be performed on one or more operands.

Syntax

Operator-Keyword:

AND         DUP         EQ          GE
GT          HIGH        HIGHWORD    LE
LENGTH      LENGTHOF    LOW         LOWWORD
LT          MASK        MOD         NE
NOT         OFFSET      OPATTR      OR
PTR         SEG         SHL         SHORT
SHR         SIZE        SIZEOF      THIS
.TYPE       TYPE        WIDTH       XOR

Identifiers

Description

This section describes the syntax for identifiers and the various types of information they can be made to represent.

Syntax

Identifier:

Normal-Identifier

Dot-Identifier

Normal-Identifier

NonDigit

Normal-Identifier Identifer-Character

Dot-Identifier . Normal-Identifier

Identifier-Character NonDigit Digit

NonDigit: one of

_ $ @ ?
a b c d e f g h i j k l m
n o p q r s t u v w x y z
A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z

Digit: one of

0 1 2 3 4 5 6 7 8 9

Identifier Types

Description

This section describes the various types of identifiers that the assembler will create and manipulate.

Definition

Identifier-Type:

EquateName

FieldName

GroupName

LabelName

MacroName

SegmentName

UserDefined-TypeName

Equate Name

Definition

EquateName:

Numeric-EquateName

Text-EquateName

Description

An EquateName is a symbolic identifier that is associated with an expression or a body of text. The assembler substitutes the value of the EquateName at the point of reference.

Numeric Equate Name

An identifier becomes a Numeric-EquateName when it is defined in a EQU or = directive. Procedure parameter names and local variable names are also created as Numeric-EquateNames, but are visible only from within the procedure where they are defined. All other Numeric-EquateNames are globally-scoped identifiers visible across the entire module.

A Numeric-EquateName may only be referenced from within expressions, as its replacement value is itself an expression.

Text Equate Name

A Text-EquateName is a globally-scoped identifier created during the processing of a EQU preprocessor directive. A Text-EquateName is associated with a body of text whose content may not span across line breaks. In certain contexts the assembler replaces the Text-EquateName with the text that it represents and recursively evaluates the result.

Field Name

Definition

FieldName:

Record-FieldName

Structure-FieldName

Union-FieldName

Description

An identifier becomes a FieldName when it is defined within a RECORD, STRUCT, or UNION directive.

Record Field Name

A Record-FieldName is a globally-scoped identifier created during the processing of a RECORD directive. It is a special variation of a Numeric-EquateName and can be used in the same contexts.

Structure Field Name

An identifier becomes a Structure-FieldName when it is defined in a STRUCT directive. If the assembler is operating in M510 mode, or if the OPTION OLDSTRUCTS directive has been specified, then a Structure-FieldName is a globally-scoped identifier treated as a special variation of a Numeric-EquateName and can be used in the same contexts. Otherwise, a Structure-FieldName is private to the defining structure and is only accessible in expressions through use of the Structure/Union Field Selection (. Operator).

Union Field Name

An identifier becomes a Union-FieldName when it is defined in a UNION directive. A Union-FieldName is private to the defining union and is only accessible in expressions through use of the Structure/Union Field Selection (. Operator).

Group Name

A GroupName is a globally-scoped identifier created during the processing of a GROUP directive. It is referenced from within expressions.

Label Name

Definition

LabelName:

Code-LabelName

Data-LabelName

Description

A LabelName is globally-scoped identifier that is associated with a program address at application run-time. It has an explicit or inherited Type-Declaration, and an optional Language-Attribute. These attributes are described in the following sections.

Type Declaration

The type declaration associated with a label name depends on how the label was defined. See the Code-LabelName and Data-LabelName sections for descriptions on how this attribute is assigned.

Language Attribute

A LabelName can have an assigned Language-Attribute, set either implicitly through the use of a Language-Name keyword in the body of a .MODEL or OPTION directive, or explicitly through the use of an overriding Language-Name keyword in the body of a EXTERN/EXTRN, EXTERNDEF, PROC, or PUBLIC directive. The Language-Attribute determines the exact spelling of the LabelName identifier when it is written to the object file. According to the Language-Attribute, identifier spellings are modified from their appearance in the assembly language source module as follow:

LANGUAGE ATTRIBUTE	IDENTIFIER SPELLING
OPTLINK, SYSCALL	No modifications are made to the identifier when written to the object file.
C, STDCALL	A leading underscore character is appended to the front of the name.
BASIC, FORTRAN, PASCAL	All characters in the identifier are converted to uppercase.

Code Label Name

Definition

Code-LabelName:

Target-LabelName

Procedure-LabelName

Description

A Code-LabelName is an identifier that is associated with an executable code address at application run-time. There are two types of Code-LabelNames: Target-LabelNames and Procedure-LabelNames.

Target Label Name

An identifier becomes a Target-LabelName when it is defined with a :, ::, or LABEL directive.

If a Target-LabelName created with a single colon (:) is defined within the body of a procedure, then the name is visible only from within that procedure unless operating in M510 mode (and no .MODEL directive with a Language-Name has been specified), or unless the OPTION NOSCOPED directive has been specified.

A Target-LabelName defined outside the body of a procedure is visible to the entire module, and may also be given PUBLIC visibility.

Procedure Label Name

An identifier becomes a Procedure-LabelName when it is defined in a PROC directive.

Data Label Name

A Data-LabelName is an identifier that is the address of a program variable at application run-time. An identifier becomes a Data-LabelName when it is named in a data allocation statement, or when a scalar, aggregate, or vector type is associated with the identifier named in a LABEL, EXTERN/ EXTRN, EXTERNDEF, or COMM directive.

Macro Name

A MacroName is a globally-scoped identifier created during the processing of a MACRO directive. It is associated with a multi-line body of text. A MacroName may only be used in contexts where a normal assembler directive is expected.

Macro Parameter Name

An identifier becomes a Macro-ParameterName when it is named as a parameter to a macro in a MACRO directive. It is associated with a body of text whose content may not span across line breaks. It is only recognized and acted upon from within the body of a macro expansion.

Segment Name

A SegmentName is a globally-scoped identifier created during the processing of a SEGMENT directive. It may be referenced from within expressions or in the body of a GROUP directive.

User-Defined Type Name

Definition

UserDefined-TypeName:

Record-TypeName

Structure-TypeName

Typedef-TypeName

Union-TypeName

Description

An identifier becomes a UserDefined-TypeName when it is defined within a RECORD, STRUCT, TYPEDEF, or UNION directive.

Record Type Name

A Record-TypeName is a globally-scoped identifier created during the processing of a RECORD directive. It is recognized from within Expressions, Type-Declarations, or as a pseudo-directive in a data allocation statement.

Structure Type Name

A Structure-TypeName is a globally-scoped identifier created during the processing of a STRUCT directive. It is recognized from within Expressions, Type-Declarations, or as a pseudo-directive in a data allocation statement.

Typedef Type Name

A Typedef-TypeName is a globally-scoped identifier created during the processing of a TYPEDEF directive. It is recognized from within Expressions, Type-Declarations, or as a pseudo-directive in a data allocation statement.

Union Type Name

A Union-TypeName is a globally-scoped identifier created during the processing of a UNION directive. It is recognized from within Expressions, Type-Declarations, or as a pseudo-directive in a data allocation statement.

Predefined Identifiers

The following sections describe the predefined identifiers created by the assembler. When a case-sensitive assembly is being performed, the predefined identifiers must be spelled exactly as they appear in the following descriptions with respect to uppercase and lowercase characters.

Segment Information

The following sections describe the predefined identifiers created by the assembler in support of segment manipulation.

@code

The @code identifier is a Text-EquateName created by the assembler when a .MODEL directive is encountered, at which time the assembler performs an automatic ASSUME CS:@code operation. The @code symbol is not defined if a .MODEL directive has not been issued.

Under MASM 5.10 emulation, the @code symbol is set to the name of the implicitly-defined default code segment (the segment opened when a .CODE directive is used) and its value is never changed. In other modes, the @code symbol is updated to reflect whatever segment is opened by using .CODE, whether defined implicitly or as an explicit parameter to the .CODE directive.

The value assigned to the @code symbol when the default code segment is opened is determined by the memory model as follows:

Memory Model Value for @code

TINY DGROUP

SMALL _TEXT

MEDIUM module _TEXT

COMPACT_TEXT

LARGE module _TEXT

HUGE module _TEXT

FLAT CODE32

The module entry is replaced with base file name of the top-level module being assembled.

@CodeSize

The @CodeSize identifier is a Numeric-EquateName created by the assembler when a .MODEL directive is encountered. @CodeSize indicates whether code segments created by the .CODE directive are named such that the linker will combine them into a single (NEAR) segment or into multiple (FAR) segments. The @CodeSize symbol is set to 0 (NEAR) for the TINY, SMALL, COMPACT, and FLAT memory models, and to 1 (FAR) for the MEDIUM, LARGE, and HUGE memory models. The @CodeSize symbol is not defined if a .MODEL directive has not been issued.

@CurSeg

The @CurSeg identifier is a Text-EquateName defined by the assembler to hold the name of the currently opened segment. If no segment is currently open, @CurSeg will expand into an empty string.

@data

The @data identifier is a Text-EquateName created by the assembler when a .MODEL directive is encountered. It expands to the group name shared by all of the near data segments. If a .MODEL FLAT has been issued, the @data identifier expands to FLAT. For all other memory models, it expands to DGROUP.

@DataSize

The @DataSize identifier is a Numeric-EquateName created by the assembler when a .MODEL directive is encountered, and represents the default data distance. Depending on the currently selected memory model, the @DataSize identifier is set to the following values:

TINY 0

SMALL 0

COMPACT 1

MEDIUM 1

LARGE 1

HUGE 2

FLAT 0

@Model

The @Model identifier is a Numeric-EquateName created by the assembler when a .MODEL directive is encountered, and is set to a unique value for each memory model. The values are as follows:

TINY 1

SMALL 2

COMPACT 3

MEDIUM 4

LARGE 5

HUGE 6

FLAT 7

@WordSize

The @WordSize identifier is a Numeric-EquateName that reflects the address size attribute of the current segment. It is set to 2 for a USE16 segment, and 4 for a USE32 segment. If no segment is currently open, it reflects the default address size as determined by the currently selected processor.

Version Information

These identifiers offer methods of testing the various operating modes of the assembler to determine what features are activated or disabled, or how the assembler will behave under various conditions.

@Alp

The @Alp identifier is a Text-EquateName that can be tested to determine if ALP is assembling the source file (versus some other assembler). It is always set to the string 100.

@AlpMajor

The @AlpMajor identifier is a Text-EquateName that reflects the major portion of the three-part assembler version number. It is padded on the right with zeros to allow major version number comparisions independant of the minor version and revisions numbers. See @AlpVersion for more information.

This identifier is only defined in ALP mode.

@AlpMinor

The @AlpMinor identifier is a Text-EquateName that reflects the minor portion of the three-part assembler version number. It is padded on the right with zeros to allow minor version number comparisions independant of the major version and revisions numbers. See @AlpVersion for more information.

This identifier is only defined in ALP mode.

@AlpRevision

The @AlpRevision identifier is a Text-EquateName that reflects the revision portion of the three-part assembler version number. It allows revision number comparisions independant of the major and minor version numbers. See @AlpVersion for more information.

This identifier is only defined in ALP mode.

@AlpVersion

The @AlpVersion identifier is a Text-EquateName that reflects the full three-part assembler version number. This is an encoding of the version number printed in the program banner when the assembler is invoked. This number and its requisite parts may be tested to determine the presence or absence of features provided by the assembler.

The assembler version number consists of three parts:

1. The major version number (one digit)
2. The minor version number (two digits)
3. The revision number (three digits)

In the assembler banner, the numbers are separated by the period (.) character; the period is removed from the text defined by the predefined identifiers.

For example, if the major version number is 1, the minor version number is 2, and the revision number is 3, then the full version number is printed in the assembler banner as 1.02.003, and the various predefined version identifers would be set as follows:

@AlpVersion   102003
@AlpMajor     100000
@AlpMinor       2000
@AlpRevision     003

This identifier is only defined in ALP mode.

@Cpu

The @Cpu identifier is a Numeric-EquateName that reflects the currently selected processor for which ALP is assembling instructions. This value is affected by issuing a Processor-Control-Directive, and is a bit map that indicates the currently active processor instruction set(s).

B	A	9	8	7	6	5	4	3	2	1	0	BIT SET IF ASSEMBLING FOR
											1	8086/8088
										1		80186
									1			80286
								1				80386
							1					80486
						1						80586 (Pentium)
					1							80686 (Pentium Pro)
				1								Privileged mode
			1									8087
		1										MMX Extensions
	1											80287
1												80387

@Version

The @Version identifier is a Text-EquateName that reflects the MASM-compatible version number. The current emulation mode of the assembler affects the value of this symbol as follows:

M510 510

M600 600

ALP 4294967295 (the highest possible value for an unsigned 32-bit integer)

Date and Time Information

These identifiers allow the programmer to query the system date or time during the assembly. Each time they are referenced, a new system request for the current date and time is made and the values held in the identifiers are refreshed.

@Date

The @Date identifier is a Text-EquateName that is set to the current system date. If the current operating mode is M600, the date is returned in the MM/DD/YY format. In native ALP mode, the date is returned in the MM/DD/YYYY format.

The @Date identifier is not available in M510 mode.

@Time

The @Time identifier is a Text-EquateName that is set to the current system time in 24-hour HH:MM:SS format.

The @Time identifier is not available in M510 mode.

File Information

These identifiers return information about the file(s) being assembled.

@FileName

The @FileName identifier is a Text-EquateName that is set to the base name of the main file being assembled (as it appears on the command line).

@Line

The @Line identifier is a Numeric-EquateName that is set to the current source line number in the file currently being assembled.

The @Line identifier is not available in M510 mode.

Literals

Description

Literals are the notational method whereby numeric values or strings of character data are represented in the source stream. Literals are also commonly referred to as constants (especially in the context of high level languages) because they typically represent objects whose values do not change throughout the life of the assembly or compilation. However, literals should not be confused with run-time "constants"; ("read-only"; data items allocated by the programmer); they are assembly-time tokens used by the assembler to represent numeric values or character strings.

Syntax

Literal:

Floating-Point-Literal

Integer-Literal

String-Literal

Integer Literals

Description

An integer literal represents a fixed-point numeric value. An integer literal must begin with one of the numeric digits 0 - 9, and may be optionally terminated with a suffix character called a radix specifier. The radix specifier tells the assembler whether the literal is to be interpreted as a base 2 (binary), 8 (octal), 10 (decimal), or 16 ( hexadecimal) number. If the literal is not suffixed with a radix specifier , the assembler uses the value of the current radix to determine the base of the number. The default radix is 10 (decimal), but the .RADIX directive can be used to specify an alternate radix.

Syntax

Integer-Literal:

Binary-Integer-Literal

Octal-Integer-Literal

Decimal-Integer-Literal

Hexadecimal-Integer-Literal

Binary Integer Literals

Syntax

Binary-Integer-Literal:

Unqualified-Binary-Integer-Literal

Qualified-Binary-Integer-Literal

Unqualified-Binary-Integer-Literal:

Binary-Digit

Binary-Integer-Literal Binary-Digit

Qualified-Binary-Integer-Literal:

Unqualified-Binary-Integer-Literal Binary-Radix

Binary-Digit:

0

1

Binary-Radix:

b

B

y

Y

Description

A base-2 number containing either of the digits 0 and 1.

Examples

The following are examples of unqualified binary integer literals:

10101
0
000001
1111000010101010

The following are examples of qualified binary integer literals:

00001111b
1111Y
00y
1111000010101010B

Octal Integer Literals

Syntax

Octal-Integer-Literal:

Unqualified-Octal-Integer-Literal

Qualified-Octal-Integer-Literal

Unqualified-Octal-Integer-Literal:

Octal-Digit

Octal-Integer-Literal Octal-Digit

Qualified-Octal-Integer-Literal:

Unqualified-Octal-Integer-Literal Octal-Radix

Octal-Digit: one of:

0 1 2 3 4 5 6 7

Octal-Radix:

o

O

q

Q

Description

A base-8 number containing any of the digits 0 through 7.

Examples

The following are examples of unqualified octal integer literals:

01234567
27
765

The following are examples of qualified octal integer literals:

27q
013o
567O
01234567Q 

Decimal Integer Literals

Syntax

Decimal-Integer-Literal:

Unqualified-Decimal-Integer-Literal

Qualified-Decimal-Integer-Literal

Unqualified-Decimal-Integer-Literal:

Decimal-Digit

Decimal-Integer-Literal Decimal-Digit

Qualified-Decimal-Integer-Literal:

Unqualified-Decimal-Integer-Literal Decimal-Radix

Decimal-Digit: one of:

0 1 2 3 4 5 6 7 8 9

Decimal-Radix:

d

D

t

T

Description

A base-10 number containing any of the digits 0 through 9.

Examples

The following are examples of unqualified decimal integer literals:

0123456789
19
090

The following are examples of qualified decimal integer literals:

01d
89t
4567D
0123456789T 

Hexadecimal Integer Literals

Syntax

Hexadecimal-Integer-Literal:

Unqualified-Hexadecimal-Integer-Literal

Qualified-Hexadecimal-Integer-Literal

Unqualified-Hexadecimal-Integer-Literal:

Decimal-Digit

Hexadecimal-Integer-Literal Decimal-Digit

Hexadecimal-Integer-Literal Hexadecimal-Digit

Qualified-Hexadecimal-Integer-Literal:

Unqualified-Hexadecimal-Integer-Literal Hexadecimal-Radix

Decimal-Digit: one of:

0 1 2 3 4 5 6 7 8 9

Hexadecimal-Digit: one of:

a b c d e f
A B C D E F

Hexadecimal-Radix:

h

H

Description

A base-16 number using any combination of the digits 0 through 9 and the lowercase letters a through f or the uppercase letters A through F. The lowercase and uppercase representations of any given hexadecimal letter are equivalent.

Constraints

A hexadecimal integer literal may not begin with any of the alphabetic hexadecimal characters or it will be interpreted as an identifier; such numbers must be prefixed with the 0 digit.

Examples

The following are examples of unqualified hexadecimal integer literals:

01BD
9A
0AB

The following are examples of qualified hexadecimal integer literals:

1234ABCDh
01DH
0bh
1111FFFFH

Floating-Point Literals

Description

A floating-point literal is a notation for representing real numbers. The assembler provides both decimal and hexadecimal floating-point notations for representing real numbers.

Syntax

Floating-Point-Literal:

Decimal-Floating-Point-Literal

Hexadecimal-Floating-Point-Literal

Decimal Floating-Point Literals

Syntax

Decimal-Floating-Point-Literal:
Significand-Part
Significand-Part Exponent-Part

Significand-Part:
Digit-Sequence.Digit-Sequence
Digit-Sequence.

Exponent-Part:
E-Character Digit-Sequence
E-Character Sign Digit-Sequence

E-Character:
e
E

Sign:
-
+

Digit-Sequence:
Digit
Digit-Sequence Digit

Digit:one of:
0 1 2 3 4 5 6 7 8 9

Description

A decimal floating-point literal has a significand part that may be followed by an exponent part. The significand part consists of a digit sequence representing the whole-number part, followed by a period (.), followed by a digit sequence representing the fraction part. The exponent part consists of an introductory character (eor E), followed by an optional sign character (+or -), followed by a digit sequence representing the exponent.

Constraints

The introductory Digit-Sequence in the Significand-Part must be specified ( the literal cannot begin with a ".").

Examples

25.23 
2.523E1 
2523.0E-2

Hexadecimal Floating-Point Literals

Syntax

Hexadecimal-Floating-Point-Literal:
Hexadecimal-Literal Float-Radix

Hexadecimal-Literal:
Decimal-Digit
Hexadecimal-Literal Decimal-Digit
Hexadecimal-Literal Hexadecimal-Digit

Decimal-Digit:one of:
0 1 2 3 4 5 6 7 8 9

Hexadecimal-Digit:one of:
a b c d e f
A B C D E F

Float-Radix:
r
R

Description

A hexadecimal floating-point literal provides a means of initializing floating point values using a notation more closely tied to the internal machine representation than that of the Decimal-Floating-Point-Literal. Such literals are coded in a fashion similar to that of a normal Hexadecimal-Integer-Literal, but a different radix suffix is used to inform the assembler that the value is to be used in the allocation of real numbers rather than integers.

Constraints

A hexadecimal floating-point literal may not begin with any of the alphabetic hexadecimal characters or it will be interpreted as an identifier; such numbers must be prefixed with the 0 digit.

The literal must specify the correct number of hexadecimal digits according to the size of the real-number data-type to which it will be assigned. For REAL4, REAL8, and REAL10 variables, the respective number of digits in the literal must be 8, 16, and 20. For literals encoded with a leading zero, the respective number of digits must be 9, 17, and 21.

Examples

3F800000r

String Literals

Syntax

String-Literal:
D-String
S-String

D-String:
D-Quote D-Quote
D-Quote D-Char-Sequence D-Quote

S-String:
S-Quote S-Quote
S-Quote S-Char-Sequence S-Quote

D-Char-Sequence:
any printable character except D-Quote
D-Quote D-Quote

S-Char-Sequence:
any printable character except S-Quote
S-Quote S-Quote

D-Quote:
"

S-Quote:

Description

A string literal contains a sequence of zero or more characters enclosed in quotation mark symbols. Either a single (') or double (") quotation mark symbol may be used as the quote character that opens and closes the string literal. If a single quotation mark symbol is used as the quote character, then double quotation mark symbols may appear as data characters within the string literal, and vice versa. If the quote character must also appear as a character within the string literal, use two adjacent quote characters; this will allow a single occurrence of the quote character to be inserted into the string literal.

A quote character must be used to terminate the string literal before the end of the line is reached, otherwise an error message is issued and the literal is terminated by the end of line character. A string literal may span multiple lines only if a backslash (\) appears as the last non- whitespace character on the line, in which case the backslash, all surrounding whitespace characters, and the end of line character are deleted and the literal is continued with the first character on the next line.

Examples

'Hello, world'
"That's the way it is"
'Unless its not'
"SuperStringCon \
catenated"

Punctuators

Description

Punctuators are used as operators and separator characters.

Syntax

Punctuator:one of
[ ] ( ) { } * , : = ; %

Declarations

A Type Declaration is a language construct that specifies the characteristics of code and data objects used in a program.

Type Declarations

Description

A Type-Declaration is a common construct used in various assembler directives to establish type attribute information for a program object. A Type-Declaration is needed to determine the data type of a variable or labeled address. The TYPEDEF directive offers a method of assigning a name to a Type-Declaration.

Syntax

Type-Declaration:

TypeName

TypeName Array-Spec

Pointer-Spec

Pointer-Spec TypeName

Pointer-Spec TypeName Array-Spec

Pointer-Spec:

PTR

Distance-TypeName PTR

Pointer-Spec Array-Spec

Array-Spec:

[ Expression ]

Array-Spec [ Expression ]

TypeName:

Distance-TypeName

Scalar-TypeName

UserDefined-TypeName

Examples

The TYPEDEF directive is used to illustrate the type declaration syntax:

CHAR        typedef   byte               ;   Alias of intrinsic TypeName
PBYTE       typedef   ptr  byte          ;   Pointer to intrinsic TypeName
PCHAR       typedef   ptr  CHAR          ;   Pointer to TypeDef-TypeName
PPCHAR      typedef   ptr  PCHAR         ;   Pointer to a pointer to a CHAR
PPBYTE      typedef   ptr  ptr byte      ;   Similar to PPCHAR
PVOID       typedef   ptr                ;   Pointer to nothing (pointer to code)
PCODE       typedef   ptr  PROC          ;   Similar to PVOID
PFCODE      typedef   far  ptr far       ;   Far pointer to far code address

; vector declarations

ACHAR       typedef   CHAR[16]          ;   Array of 16 characters
AAWORD      typedef   word[2][2]        ;   multi-dimensional array
APBYTE      typedef   ptr[8] byte       ;   Array of 8 pointers to byte
APACHAR     typedef   ptr[4] ACHAR      ;   Array of 4 ptrs to arrays of 16 chars

SIZES_T     struct                     ;   define an intrinsic structure type
   little   byte      ?
   Medium   word      ? 
   BIG      dword     ? 
SIZES_T     ends 

SIZES       typedef   SIZES_T           ;   alias for intrinsic structure type
PSIZES      typedef   ptr SIZES_T       ;   and a type to point to it

PFORWARD    typedef   ptr FORWARD       ;   Pointers to forward-referenced types
FORWARD     struct                     ;   are assumed to be pointers to structs
   blah      word     ?
FORWARD     ends

Expressions

An expression is a sequence of operators and operands that are evaluated to derive a numeric result, an effective address, or a register operand.

Expressions are specified using standard infix notation, which is recursive in nature, ie., expressions may be nested within other expressions. The evaluation of an expression occurs in a left to right manner, and is influenced by the rules of operator precedence and associativity. The order in which expressions are evaluated can be controlled by grouping operands and operators together using parentheses ().

Expression Syntax

Description

This section describes the complete expression syntax.

Syntax

Expression:

Duplicative-Expression

Duplicative-Expression:

Attribute-Expression

Attribute-Expression DUP ( Initializer-List )

Attribute-Expression:

OR-Expression SHORT Additive-Expression

.TYPE OR-Expression

OPATTR OR-Expression

OR-Expression:

AND-Expression

OR-Expression OR AND-Expression

OR-Expression XOR AND-Expression

AND-Expression]]:

NOT-Expression]]

AND-Expression]] AND NOT-Expression

NOT-Expression]]:

Relational-Expression NOT Relational-Expression

Relational-Expression:

Additive-Expression

Relational-Expression EQ Additive-Expression

Relational-Expression NE Additive-Expression

Relational-Expression GT Additive-Expression

Relational-Expression GE Additive-Expression

Relational-Expression LT Additive-Expression

Relational-Expression LE Additive-Expression

Additive-Expression:'

Multiplicative-Expression

Additive-Expression + Multiplicative-Expression

Additive-Expression - Multiplicative-Expression

Multiplicative-Expression:

Narrowed-Expression

Multiplicative-Expression * Narrowed-Expression

Multiplicative-Expression / Narrowed-Expression

Multiplicative-Expression MOD Narrowed-Expression

Multiplicative-Expression SHL Narrowed-Expression

Multiplicative-Expression SHR Narrowed-Expression

Narrowed-Expression:

Cast-Expression

HIGH Cast-Expression

HIGHWORD Cast-Expression

LOW Cast-Expression

LOWWORD Cast-Expression

Cast-Expression:

Element-Selection-Expression

OFFSET Cast-Expression

SEG Cast-Expression

THIS Element-Selection-Expression

TYPE Element-Selection-Expression

Cast-Expression PTR Cast-Expression

Cast-Expression : Cast-Expression

Element-Selection-Expression:

Sign-Expression

Element-Selection-Expression

Sign-Expression

Element-Selection-Expression . Sign-Expression

Sign-Expression:

Primary-Expression

- Primary-Expression

+ Primary-Expression

Primary-Expression:

Literal-Operand

Record-Constant

Identifier-Operand

Register-Operand

Integral-TypeName-Operand

Value-Substitution-Operand

LENGTH Identifier-Operand

LENGTHOF Identifier-Operand

MASK Identifier-Operand

SIZE Element-Selection-Expression

SIZEOF Element-Selection-Expression

WIDTH Identifier-Operand

Parenthesized-Expression

Indirected-Expression

Compound-Initializer

Literal-Operand:

Floating-Point-Literal

Integer-Literal

String-Literal]]

Record-Constant:

Identifier-Operand < Field-List >

Identifier-Operand { Field-List }

Field-List:

Attribute-Expression

Field-List , Attribute-Expression

Identifier-Operand:

Identifier

Register-Operand:

Processor-Register

Integral-TypeName-Operand:

Scalar-TypeName

Distance-TypeName

Value-Substitution-Operand:

Anonymous-Label-Alias

Location-Counter-Alias

Indeterminate-Value-Alias

FLAT

Parenthesized-Expression:

( Attribute-Expression )

Indirected-Expression:

[ Attribute-Expression ]

Compound-Initializer:

< Initializer-List >

{ Initializer-List }

Initializer-List:

Duplicative-Expression

Initializer-List , Duplicative-Expression

Duplicative Initialization Expression

Description

A Duplicative Initialization Expression is one that can be optionally used during the initialization of variables such that the operand is duplicated a specified number of times.

Syntax

Duplicative-Expression:

Attribute-Expression

Attribute-Expression

#DUP ( Initializer-List )

Initializer-List:

Duplicative-Expression

Initializer-List , Duplicative-Expression

Duplicative Initialization (DUP Operator)

Description

The DUP operator creates a Duplicated-ExpressionType from the Initializer-List enclosed in parentheses. This construct can be used to create arrays of information during data allocation.

Syntax

Attribute-Expression DUP (Initializer-List) Initializer-List: Duplicative-Expression Initializer-List,|Duplicative-Expression

Constraints

The left hand operand of the DUP operator must evaluate to an Absolute-ExpressionType.

Each Duplicative-Expression in the Initializer-List must evaluate to an Initializer-ExpressionType.

Examples

STR   STRUCT 
 One   BYTE  0
 Two   BYTE  0
STR   ENDS 

Array1  WORD 4 DUP (1,2,3,4)         ; allocates 16 words
Array2  STR  8 DUP (<1,2>)           ; 8 structures

Attribute Expression

Description

An Attribute Expression is one that optionally extracts or modifies one or more of the basic properties of its operand.

Syntax

Attribute-Expression:

OR-Expression

SHORT Additive-Expression

.TYPE OR-Expression

OPATTR OR-Expression

Expression Descriptor Bitmap (.TYPE Operator)

Description

The .TYPE operator is considered obsolete. The #OPATTR operator should be used instead.

The .TYPE operator returns a byte value bitmap that describes various attributes of its operand. The return value is 0 if the expression could not be correctly parsed or evaluated, otherwise the bitmap returned is formatted according to the following table:

7	6	5	4	3	2	1	0	BIT SET IF EXPRESSION
							1	Is a Direct-ExpressionType
						1		Is a Indirect-ExpressionType, an Indexed-ExpressionType, or a combination of both
					1			Is an Immediate-ExpressionType
				1				Is an Indirect-ExpressionType
			1					Is a Register-ExpressionType
		1						Was parsed and evaluated without error (no undefined symbols, etc.)
	1							Is relative to the SS Segment-Register
1								Contains an External Reference

.TYPE OR-Expression

Syntax

.TYPE OR-Expression

Examples

BumpCounter macro bump 
  if (((.TYPE (bump)) and 07h) eq 04h)
     Counter = Counter + bump
  else
     .err <Non-constant value passed to BumpCounter>
  endif
endm

Extended Descriptor Bitmap (OPATTR Operator)

OPATTR OR-Expression

Syntax

OPATTR OR-Expression'

Description

The OPATTR operator returns a superset of the information returned by the .TYPE operator, which should be considered obsolete.

The OPATTR operator returns a word value bitmap that describes various attributes of its operand. The return value is 0 if the expression could not be correctly parsed or evaluated, otherwise the bitmap returned is formatted according to the following table:

A98	7	6	5	4	3	2	1	0	BIT SET IF EXPRESSION
								1	Is a Direct-ExpressionType
							1		Is a Indirect-ExpressionType, an Indexed-ExpressionType, or a combination of both
						1			Is an Immediate-ExpressionType
					1				Is an Indirect-ExpressionType
				1					Is a Register-ExpressionType
			1						Was parsed and evaluated without error (no undefined symbols, etc.)
		1							Is relative to the SS Segment-Register
	1								Contains an External Reference
LLL									Language encoding (described below)

The LLL field (bits 8, 9, and A) comprise an enumerated value that describes the language attribute assigned to the expression as follows:

• 000 No language attribute used in expression
• 001 C
• 010 SYSCALL
• 011 STDCALL
• 100 PASCAL
• 101 FORTRAN
• 110 BASIC
• 111 OPTLINK

Constraints

This operator is not available in M510 mode.

Examples

L_MASK     equ 011100000000y               ; mask to isolate language bits
L_OPTLINK  equ 011100000000y               ; setting for OptLink calling convention
VerifyCallBack   macro   ProcName 
  if (((OPATTR (ProcName)) and L_MASK) ne L_OPTLINK)
     .err <Call-back routine must have OptLink linkage>
  endif
endm

Force Short Relative Address (SHORT Operator)

Syntax

SHORT Additive-Expression

Description

The SHORT operator forces the assembler to calculate the distance from the start of the next instruction to the target specified by the operand (given by Additive-Expression) to be less than 128 bytes away. This can cause the assembler to generate more efficient control transfer instructions when the target is a forward reference. By default, the assembler assumes that the code-relative target is of NEAR distance when the target is an unqualified forward reference.

Constraints

The Additive-Expression must evaluate to a Direct-ExpressionType.

Examples

  JMP     Forward                ; target unknown, NEAR jump generated
  JMP     SHORT Forward          ; force SHORT encoding
  .
  .                      ; fewer than 128 bytes of instructions
  .
Forward:                 ; definition of target

Bitwise OR Expression

Description

A Bitwise OR Expression is one where an optional binary bitwise OR operation between the left and right operands is performed and the result returned.

Syntax

OR-Expression: AND-Expression OR-Expression OR AND-Expression OR-Expression XOR AND-Expression

Bitwise Inclusive OR (OR Operator)

Syntax

OR-Expression OR AND-Expression

Description

The OR operator performs a binary bitwise OR operation on the left and right hand operands.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

One  EQU  1
Two  EQU  2

MOV  AX, One OR Two        ; moves 3 into AX

Bitwise Exclusive OR (XOR Operator)

Syntax

OR-Expression XOR AND-Expression

Description

The XOR operator performs a binary bitwise XOR operation on the left and right hand operands.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

Lower  EQU  0101y          ; 7h - binary radix suffix
Upper  EQU  1100y          ; Eh - binary radix suffix

MOV  AX, Upper XOR Lower   ; moves 1001 into AX

Bitwise AND Expression

Description

A Bitwise AND Expression is one where an optional binary bitwise AND operation between the left and right operands is performed and the result returned.

Syntax

AND-Expression:

NOT-Expression

AND-Expression AND NOT-Expression

Bitwise AND (AND Operator)

Syntax

AND-Expression AND NOT-Expression

Description

The AND operator performs a binary bitwise AND operation on the left and right hand operands.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

Lower  EQU  0111y           ; 7h - binary radix suffix
Upper  EQU  1110y           ; Eh - binary radix suffix

MOV  AX, Upper XOR Lower    ; moves 0110 into AX

Bitwise One's Complement Expression

Description

A Bitwise One's Complement Expression is one that performs an optional unary bitwise negation of its operand and returns the result.

Syntax

NOT-Expression: Relational-Expression NOT Relational-Expression

Bitwise One's Complement (NOT Operator)

Syntax

NOT Relational-Expression

Description

The NOT operator performs a unary bitwise negation on its operand.

Constraints

The operand must evaluate to a Constant-ExpressionType.

Examples

  Value  EQU 0111y          ; 7h - binary radix suffix

  MOV    EAX, NOT Value     ; moves FFFFFFF8 into EAX

Relational Expression

Description

A Relational Expression is one where an optional binary comparision operation between the left and right operands is performed and the result returned.

Syntax

Relational-Expression:

Additive-Expression

Relational-Expression EQ Additive-Expression

Relational-Expression NE Additive-Expression

Relational-Expression GT Additive-Expression

Relational-Expression GE Additive-Expression

Relational-Expression LT Additive-Expression

Relational-Expression LE Additive-Expression

Equal To (EQ Operator)

Syntax

Relational-Expression EQ Additive-Expression

Description

The EQ operator performs a binary logical comparision on the left and right hand operands. It returns true (all bits on) if they are equal, and false (all bits off) if they are not equal.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

  IF 1234 EQ 5678
    TRUE = 1
  ELSE
    TRUE = 0                ; Sets TRUE to 0
  ENDIF 

Not Equal To (NE Operator)

Syntax

Relational-Expression NE Additive-Expression

Description

The NE operator performs a binary logical comparision on the left and right hand operands. It returns true (all bits on) if they are not equal, and false (all bits off) if they are equal.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

IF 1234 NE 5678
    TRUE = 1                ; Sets TRUE to 1
ELSE
    TRUE = 0
ENDIF

Greater Than (GT Operator)

Syntax

Relational-Expression GT Additive-Expression

Description

The GT operator performs a binary logical comparision on the left and right hand operands. It returns true (all bits on) if the left operand is greater than the right operand, and false (all bits off) if it is not.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

IF 1234 GT 5678 
  TRUE = 1 
ELSE 
  TRUE = 0              ; Sets TRUE to 0
ENDIF

Greater Than or Equal To (GE Operator)

Syntax

Relational-Expression GE Additive-Expression

Description

The GE operator performs a binary logical comparision on the left and right hand operands. It returns true (all bits on) if the left operand is greater than or equal to the right operand, and false (all bits off) if it is not.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

IF 1234 GE 1234 
    TRUE = 1                ; Sets TRUE to 1
ELSE 
    TRUE = 0 
ENDIF

Less Than (LT Operator)

Syntax

Relational-Expression LT Additive-Expression

Description

The LT operator performs a binary logical comparision on the left and right hand operands. It returns true (all bits on) if the left operand is less than the right operand, and false (all bits off) if it is not.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

  IF 1234 LT 5678
      TRUE = 1               ; Sets TRUE to 1
  ELSE
      TRUE = 0
  ENDIF

Less Than or Equal To (LE Operator)

Syntax

Relational-Expression LE Additive-Expression

Description

The LE operator performs a binary logical comparision on the left and right hand operands. It returns true (all bits on) if the left operand is less than or equal to the right operand, and false (all bits off) if it is not.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

  IF 1234 LE 1234
    TRUE = 1                  ; Sets TRUE to 1
  ELSE 
    TRUE = 0
  ENDIF

Additive Expression

Description

A Additive Expression is one where an optional binary additive arithmetic operation between the left and right operands is performed and the result returned.

Syntax

Additive-Expression:

Multiplicative-Expression

Additive-Expression + Multiplicative-Expression

Additive-Expression - Multiplicative-Expression

Addition (+ Operator)

Syntax

Additive-Expression + Multiplicative-Expression

Description

The + operator performs a binary addition operation on the left and right hand operands, and returns the result.

Constraints

One of the operands must evaluate to a Constant-ExpressionType. If one of the operands references an external identifier, then the other operand must be a Constant-ExpressionType without an external reference. Both operands must be of scalar type.

Examples

 VALUE = 100 + 11          ; sets VALUE to 111

Subtraction (- Operator)

Syntax

Additive-Expression - Multiplicative-Expression

Description

The - operator performs a binary subtraction operation on the left and right hand operands, and returns the result.

Constraints

The right operand must evaluate to a Constant-ExpressionType and reference no external identifiers. If both operands are relocatable, they must reside within the same segment, in which case the result is converted to a Absolute-ExpressionType. Both operands must be of scalar type.

Examples

 VALUE = 111 - 11           ; sets VALUE to 100

Multiplicative Expression

Description

A Multiplicative Expression is one where an optional binary multiplicative arithmetic operation between the left and right operands is performed and the result returned.

Syntax

Multiplicative-Expression:

Narrowed-Expression

Multiplicative-Expression * Narrowed-Expression

Multiplicative-Expression / Narrowed-Expression

Multiplicative-Expression MOD Narrowed-Expression

Multiplicative-Expression SHL Narrowed-Expression

Multiplicative-Expression SHR Narrowed-Expression

Multiplication (* Operator)

Syntax

Multiplicative-Expression * Narrowed-Expression

Description

The * operator performs a binary multiplication operation on the left and right hand operands, and returns the result.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

 VALUE = 9 * 3                 ; sets VALUE to 27

Division (/ Operator)

Syntax

Multiplicative-Expression / Narrowed-Expression

Description

The / operator performs a binary division operation on the left and right hand operands, and returns the result.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

 VALUE = 27 / 9                ; sets VALUE to 3

Remainder (MOD Operator)

Syntax

Multiplicative-Expression MOD Narrowed-Expression

Description

The MOD operator performs a binary modulus division operation on the left and right hand operands, and returns the remainder as the result.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

 VALUE = 18 MOD 4              ; sets VALUE to 2

Bitwise Left Shift (SHL Operator)

Syntax

Multiplicative-Expression SHL Narrowed-Expression

Description

The SHL operator shifts the bits in the left hand operand to the left by the number of bits specified in the right hand operand, and returns the result.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

 VALUE = 1111y SHL 4          ; sets VALUE to 11110000y

Bitwise Right Shift (SHR Operator)

Syntax

Multiplicative-Expression SHR Narrowed-Expression

Description

The SHR operator shifts the bits in the left hand operand to the right by the number of bits specified in the right hand operand, and returns the result.

Constraints

Each operand must evaluate to a Constant-ExpressionType.

Examples

 VALUE = 11110000y SHR 4      ; sets VALUE to 00001111y

Narrowed Expression

Description

A Narrowed Expression is one that performs an optional unary narrowing operation on its operand and returns the result.

Syntax

Narrowed-Expression:

Cast-Expression HIGH Cast-Expression

HIGHWORD Cast-Expression

LOW Cast-Expression

LOWWORD Cast-Expression

Upper 8 Bits of WORD Expression (HIGH Operator)

Syntax

HIGH Cast-Expression

Description

The HIGH operator returns the upper 8 bits of a 16-bit expression. Only bits 8-15 are returned, even if the magnitude of the operand exceeds 16 bits.

Constraints

The operand must evaluate to a Constant-ExpressionType.

Examples

 FIRST  = 1234h
 SECOND = HIGH FIRST        ; Sets SECOND to 12h

Upper 16 Bits of DWORD Expression (HIGHWORD Operator)

Syntax

HIGHWORD Cast-Expression

Description

The HIGHWORD operator returns the upper 16 bits of a 32-bit expression. Only bits 16-31 are returned, even if the magnitude of the operand exceeds 32 bits.

Constraints

The operand must evaluate to a Constant-ExpressionType.

This operator is not available in M510 mode.

Examples

 FIRST  = 12345678h 
 SECOND = HIGHWORD FIRST    ; Sets SECOND to 1234h

Lower 8 Bits of WORD Expression (LOW Operator)

Syntax

LOW Cast-Expression

Description

The LOW operator returns the lower 8 bits of its operand.

Constraints

The operand must evaluate to a Constant-ExpressionType.

Examples

 FIRST  = 1234h
 SECOND = LOW FIRST         ; Sets SECOND to 34h

Lower 16 Bits of DWORD Expression (LOWWORD Operator)

Syntax

LOWWORD Cast-Expression

Description

The LOWWORD operator returns the lower 16 bits of its operand.

Constraints

The operand must evaluate to a Constant-ExpressionType.

This operator is not available in #M510 mode.

Examples

 FIRST  = 12345678h
 SECOND = LOWWORD FIRST     ; Sets SECOND to 5678h

Type Conversion Expression

Description

A Type Conversion Expression is one that performs an optional type conversion operation on its operand and returns the result.

Syntax

Cast-Expression:

Element-Selection-Expression

OFFSET Cast-Expression

SEG Cast-Expression

THIS Element-Selection-Expression

TYPE Element-Selection-Expression

Cast-Expression PTR Cast-Expression

Cast-Expression : Cast-Expression

Address Offset (OFFSET Operator)

Description

The OFFSET operator returns the offset portion of its operand. For relocatable values, this is the offset into the segment or group to which the expression is relative.

Syntax

OFFSET Cast-Expression

Constraints

The operand may evaluate to any one of the following #ExpressionTypes:

• Absolute-ExpressionType
• Constant-ExpressionType
• Immediate-ExpressionType
• Direct-ExpressionType
• Indirect-ExpressionType

Examples

CodeLabel:
       MOV   AX, CodeLabel            ; illegal, no data at address 
       MOV   AX, OFFSET   CodeLabel   ; we want the address itself

Address Segment (SEG Operator)

Syntax

SEG Cast-Expression

Description

The SEG operator returns the segment or group to which a relocatable expression is relative.

Constraints

The operand must evaluate to one of the following ExpressionTypes:

• Immediate-ExpressionType
• Direct-ExpressionType
• Indirect-ExpressionType
• Indexed-ExpressionType

Examples

DATA    SEGMENT 
Stuff   DB    ? 
        MOV   AX, SEG Stuff    ; This construct is
        MOV   AX, DATA         ; equivalent to this
DATA    ENDS

Address Alias (THIS Operator)

Syntax

THIS Element-Selection-Expression

Description

The THIS operator returns an operand whose:

• Relative Frame attribute is set to that of the current segment
• Displacement attribute is set to the current location counter
• Type Declaration attribute is set to that of the expression given by the Element-Selection-Expression operand.

Constraints

The operand must evaluate to a Type-ExpressionType.

Examples

DATA      SEGMENT

ALIAS   EQU   THIS BYTE        ; reference this address as a byte
Stuff   DB    ? 
        MOV   AL, ALIAS        ; This construct is
        MOV   AL, Stuff        ; equivalent to this
DATA    ENDS

Datatype Extraction (TYPE Operator)

Syntax

TYPE Element-Selection-Expression

Description

The TYPE operator returns the Type-ExpressionType attribute of its operand.

Constraints

None

Examples

CODE    SEGMENT 
        ASSUME  CS:CODE, DS:CODE
Stuff   DB      ?                        ; TYPE Stuff is BYTE
        MOV     [BX],(TYPE Stuff) PTR 1  ; stores 1 as a BYTE at [BX]
CODE    ENDS

Type Conversion (PTR Operator)

Syntax

Cast-Expression PTR Cast-Expression

Description

The PTRoperator converts the right operand to the type specified by the left operand.

Constraints

The left operand must be a Type-ExpressionType.

Examples

CODE     SEGMENT 
         MOV  BYTE PTR [BX], 1    ; stores 1 as a BYTE at [BX]
CODE     ENDS

Segment Override (: Operator)

Syntax

Cast-Expression : Cast-Expression

Description

The : (colon) operator forces the right operand to have the Relative Frame attribute of the left operand.

Constraints

The left operand must evaluate to one of the following #ExpressionTypes:

• Register-ExpressionType where the Register Value attribute is that of a Segment-Register
• Immediate-ExpressionType where the Relative Frame attribute is that of a GroupName or SegmentName.

Examples

DATA       SEGMENT
Variable   DW    ?
DATA       ENDS

DGROUP     GROUP DATA, CODE

CODE       SEGMENT
  ASSUME   CS:CODE, DS:DGROUP
  MOV      AX, DGROUP:Variable         ; insure Variable is relative to DGROUP
  ASSUME   DS:NOTHING
  MOV      BX, CS:Variable             ; access Variable through CS register
CODE       ENDS

Element Selection Expression

Description

A Element Selection Expression is one that optionally selects a specific element of its operand and returns a reference to it.

Syntax

Element-Selection-Expression:

Sign-Expression]]

Element-Selection-Expression [Sign-Expression]

Element-Selection-Expression .Sign-Expression

Subscript ([] Operator)

Syntax

Element-Selection-Expression [ Sign-Expression ]

Description

The [] binary operator performs a subscripting (or indexing) operation between the operand to the left of the brackets and the operand enclosed within the brackets. This is a simple additive operation of BYTE granularity; the arithmetic performed is not influenced by the Operand Size of either operand.

The syntax for this operator describes a binary operation between the left hand expression and the bracketed expression. The bracketed expression is also subject to the same operations performed during the processing of a standalone Indirected-Expression as described in the section on Primary-Expressions.

Constraints

Only one of the operands may specify a relocatable value.

Examples

CODE    SEGMENT 
        ASSUME  CS:CODE, DS:CODE

Value    DB    0                         ;   Value [0]
         DB    1                         ;   Value [1]
         DB    2                         ;   Value [2]
         DB    3                         ;   Value [3]
         DB    4                         ;   Value [4] 

  MOV      AL, Value [3]        ;   load AL with the fourth byte at Value (3)
  MOV      BX, offset Value     ;   get address of Value 
  MOV      AL, [BX] [1] [2]     ;   also gets the fourth byte ( 3 ) 

CODE     ENDS

Structure/Union Field Selection (. Operator)

Syntax

Element-Selection-Expression . Sign-Expression

Description

The . (period) operator selects a structure or union field entry. It adds the left and right hand operands together and returns the result. The left operand should be an Indirect-ExpressionType, Indexed-ExpressionType, or Type-ExpressionType whose Type Declaration attribute resolves to that of a Structure-TypeName or Union-TypeName. The right operand should refer to a FieldName defined within the referenced type.

The Operand Size attribute of the result depends on the operands involved. If both operands have an operand size, a Structure-FieldName appearing as the right hand operand would override the operand size of the left operand and would dictate the operand size of the resulting expression.

Constraints

Only one of the operands may specify a relocatable value.

Examples

Number   STRUC
  One    DB   1
  Two    DW   2
Number   ENDS

; The following line is only allowed in MASM 5.10 mode ( OPTION OLDSTRUCTS ) 

  MOV   AX,[BX] .Two         ;  BX points to a "Number", get the "Two" entry 

; In other modes, "Two" is private to the "Number" structure type, so 
; one of the following methods are required : 

  MOV   AX,(Number PTR[BX]).Two  ; Explicit override
  MOV   AX,[BX] + Number.Two     ; Fully qualified reference
  ASSUME BX:Number               ; Associate BX with "Number"
  MOV   AX,[BX].Two              ; then original syntax is allowed

Unary Arithmetic Expression

Description

A Unary Arithmetic Expression is one that optionally alters the sign of its operand and returns the result.

Syntax

Sign-Expression:

Primary-Expression

-Primary-Expression

+Primary-Expression

Unary Minus (- Operator)

Syntax

- Primary-Expression

Description

The - operator makes its operand into a negative number and returns the result.

Constraints

The operand must evaluate to a Constant-ExpressionType.

Examples

Value  EQU  1

MOV  AX, -Value     ; move -1 into AX

Unary Plus (+ Operator)

Syntax

+ Primary-Expression

Description

The + operator returns its operand.

Constraints

The operand must evaluate to a Constant-ExpressionType.

Examples

Value EQU 1 
MOV   AX,+Value  ; move 1 into AX

Primary Expression

Description

A Primary Expression is one that returns an expression operand.

Syntax

Primary-Expression:

Literal-Operand

Record-Constant

Identifier-Operand

Register-Operand

Integral-TypeName-Operand

Value-Substitution-Operand

LENGTH Identifier-Operand

LENGTHOF Identifier-Operand

MASK Identifier-Operand

SIZE Element-Selection-Expression

SIZEOF Element-Selection-Expression

WIDTH Identifier-Operand

Parenthesized-Expression

Indirected-Expression

Compound-Initializer

Literal Operand

Syntax

Literal-Operand:

Floating-Point-Literal

Integer-Literal

String-Literal

Description

The assembler accepts several types of literal values as operands within expressions. Literal-Operands are converted to #ExpressionTypes according to the following table:

Floating-Point-Literal	Floating-Point-ExpressionType
Integer-Literal	Absolute-ExpressionType
String-Literal	Absolute-ExpressionType if the string length is less than or equal to the current Address Size; a String-ExpressionType otherwise.

The context where the expression is used determines whether or not a particular type of literal is legal.

Constraints

Arithmetic operations cannot be performed on #Floating-Point-Literals, thus they cannot be the operand of a unary or binary operator.

Value Substitution Operand

Syntax

Value-Substitution-Operand:

Anonymous-Label-Alias

Location-Counter-Alias

Indeterminate-Value-Alias

FLAT

Description

These operands are used to retrieve specialized values that are calculated internally by the assembler.

The FLAT operator returns an expression whose #Relative Frame is set to that of the predefined FLAT pseudo-group.

Constraints

The FLAT operand is only active when a 32-bit processor has been selected.

Record Constant Operand

Syntax

Record-Constant:

Identifier-Operand < Field-List >

Identifier-Operand { Field-List }

Field-List:

Attribute-Expression

Field-List , Attribute-Expression

Description

A Record-Constant provides a method of calculating a single numeric result value from a list of Record-FieldName values, and combining them together according to the definition of the Record-TypeName given by the Identifier-Operand. The result value is a Constant-ExpressionType suitable for use as an instruction operand, or for assigning to a record variable.

The Record-TypeName given by the Identifier-operand determines how the Field-List will be evaluated. The Attribute-Expression entries are position-dependent, and are matched with the corresponding Record-FieldName entries from the Record-TypeName definition to determine their width and shift values. Attribute-Expression entries may be omitted, in which case the default values from the record definition are used in the calculation.

Constraints

The Identifier-Operand must resolve to a Record-TypeName.

Examples

 DATE_T   record   Year  : 7 = 0,   ; 0 is 1980
                   Month : 4 = 1,   ; January
                   Day   : 5 = 1    ; 1st
 
 CODE SEGMENT
   mov  AX,DATE_T  < >                       ; January 1st, 1980
   mov  AX,DATE_T  < 1996 - 1980, 12, 25 >   ; Christmas, 1996
   mov  AX,DATE_T  < 10h, 0Ch, 19h >         ; equivalent values in hex
   mov  AX,DATE_T  < 10000y, 1100y, 11001y > ; equivalent values in binary
   mov  AX,2199h                             ; equivalent value manually coded
   mov  AX,0010000110011001y                 ; and in binary
 ;         YYYYYYYMMMMDDDDD
 CODE   ENDS

Register Operand

Syntax

Register-Operand:

Processor-Register

Description

Processor registers are valid expression operands. The context where the expression is used determines the allowable register operands.

Constraints

The currently selected processor dictates whether or not a register is visible to the expression evaluator.

Identifier Operand

Syntax

Identifier-Operand:

Identifier

Description

When an Identifier is used in an expression, it returns a value according to its Identifier-Type, as shown in the following table:

Identifier-Type	VALUE RETURNED
Numeric-EquateName	The value originally assigned to the equate.
Structure-FieldName	The offset in bytes from the beginning of the structure.
Union-FieldName	The offset in bytes from the beginning of the union (always 0).
Record-FieldName	The shift-count required to reach the field within the record.
Record-TypeName	The mask-value that isolates defined record fields from undefined fields.
Structure-TypeName	Zero if mode is M510, otherwise the size of the structure in bytes (the operand size of the structure type).
Union-TypeName	The size of the union in bytes (the operand size of the union type).
Typedef-TypeName	The operand size of the underlying data-type represented by the Typedef-TypeName.
GroupName	A Relative Frame attribute that represents the group, and a Displacement value of zero.
SegmentName	A Relative Frame attribute that represents the segment (or the group to which it belongs), and a Displacement value of zero if the mode is M510, or the current segment offset otherwise.
LabelName	The Relative Frame attribute where the label is defined, and the segment offset value of the label.

Constraints

The Identifier must resolve to one of the following Identifier-Types:

• Numeric-EquateName
• FieldName
• GroupName
• LabelName
• SegmentName
• UserDefined-TypeName

Integral Type-Name Operand

Syntax

Integral-TypeName-Operand:

Scalar-TypeName

Distance-TypeName

Description

When an Integral-TypeName-Operandis used in an expression, it is converted to a Type-ExpressionType. If used in a numeric context, the following numeric values are returned:

Integral-TypeName-Operand	VALUE RETURNED
Scalar-TypeName	The operand-size of the type in bytes.
Distance-TypeName	If mode is M510, NEAR returns FFFF, and FAR returns FFFE. Otherwise, NEAR and FAR are resolved and the values returned are: NEAR16=FF02, NEAR32=FF04, FAR16=FF05, FAR32=FF06.

Constraints

The NEAR32 and FAR32 keywords are only valid if a 32-bit processor has been selected.

Number of Data Elements (LENGTH Operator)

Syntax

LENGTH Identifier-Operand

Description

The LENGTH operator returns the number of data elements allocated to the operand. When applied to a variable initialized with a series of comma-separated expressions (elements), only the length of the first element is considered.

Constraints

The operand must evaluate to a Data-LabelName.

Number of Data Elements (LENGTHOF Operator)

Syntax

LENGTHOF Identifier-Operand

Description

The LENGTHOF operator returns the number of data elements allocated to the operand.

Constraints

The operand must evaluate to a Data-LabelName.

This operator is not available in M510 mode.

Examples

<none>

Record or Field Bit-Mask (MASK Operator)

Syntax

MASK Identifier-Operand

Description

The MASK operator returns the bit mask required to isolate a field within a record.

Constraints

The Identifier-Operand must resolve to a Record-TypeName or Record-FieldName; otherwise the result is zero.

Size of Variable in Bytes (SIZE Operator)

Syntax

SIZE Element-Selection-Expression

Description

The SIZE operator returns the number of bytes allocated to the operand. When applied to a variable initialized with a series of comma-separated expressions (elements), only the size of the first element is considered.

Constraints

None

Size of Variable in Bytes (SIZEOF Operator)

Syntax

SIZEOF Element-Selection-Expression

Description

The SIZEOF operator returns the number of bytes allocated to the operand.

Constraints

This operator is not available in M510 mode.

Record or Field Width (WIDTH Operator)

Syntax

WIDTH Identifier-Operand

Description

The WIDTHoperator returns the width of a record or a record field name.

Constraints

The Identifier-Operand must resolve to a Record-TypeName or Record-FieldName; otherwise the result is zero.

Precedence (() Operator)

Syntax

Parenthesized-Expression:

( Attribute-Expression )

Description

Parentheses forces the Attribute-Expression operand to be evaluated at a higher precedence level.

Examples

Value =   2 + 3   * 4     ; Value = 14 
Value = ( 2 + 3 ) * 4     ; Value = 20

Indirection ([] Operator)

Syntax

Indirected-Expression:

[ Attribute-Expression ]

Description

During evaluation of the Attribute-Expression, the [](indirection) operator will convert a Register-ExpressionType to a Indexed-ExpressionType by moving the Register Value attribute to either the Base Register or Index Register attribute field as appropriate for the register(s) referenced in the expression. This operation allows values contained in the processor registers to be used during effective address calculation at application run time.

Constraints

See the Indexed-ExpressionType section for information on registers that are valid for use in this context.

Examples

CODE      SEGMENT 
          ASSUME   CS : CODE ,   DS : CODE 
Value     DW     0 
          MOV    BX , offset   Value        ; load the address of Value into BX
          MOV    [ BX ] , BX                ; store the contents of BX into the
                                            ; memory location addressed by [BX]
CODE       ENDS

Compound Initializer List (<> Operator)

Syntax

Compound-Initializer:

< Initializer-List >

{ Initializer-List }

Initializer-List:

Duplicative-Expression

Initializer-List , Duplicative-Expression

Description

The <> (or {}) operator provides a way of specifying a list of expressions to be used for initializing complex (multi-field) variables such as records or structures.

The <> operator encloses a list of comma-separated expressions; individual expressions are optional, but are also positional with respect to the record or structure fields they are intended to initialize. Commas must therefore be used to maintain field positions if empty expressions are encountered in the list.

The initializer list itself may also be left out entirely for those cases where a variable allocation will use the default initializers provided in the record or structure definition (the <>or {} themselves are still required).

Examples

Numbers   STRUCT
  One     DB     0
  Two     DW     0
  Three   DB     0
  Four    DD     0
Numbers   ENDS

First    Numbers   < >               ;  empty initializer list
Second   Numbers   < 1, 2, 3, 4 >    ;  override all defaults
Third    Numbers   < 1 >             ;  override first entry only
Fourth   Numbers   < 1, , , 4 >      ;  override first and last entries

Expression Evaluation

After an expression is parsed and checked for syntax errors, it is evaluated. During evaluation, all calculations and conversions are performed on the operands according to the operators that are applied to them. The final result is a collection of #Expression-Attributes, to which an ExpressionType is assigned.

Expression Attributes

This section describes the Expression-Attributesthat are associated with an expression after it is evaluated.

Address Size

If an expression refers to an effective address, then it also has an associated #address size. The following #ExpressionTypes normally reference an effective address, and thus have an associated address size:

• Immediate-ExpressionType
• Direct-ExpressionType
• Indirect-ExpressionType
• Indexed-ExpressionType

The address size can be either 2 (USE16) or 4 (USE32). For an expression that references a label, the address size of the segment where the label is defined determines the address size of the expression.

Operand Size

The Operand Size of an expression can be set explicitly using the #Type Conversion (PTR Operator), or it may be a side-effect inherited from the type of data referenced in the expression. The following table describes the operand sizes that will be assigned when an identifier is referenced in an expression:

REFERENCE	OPERAND SIZE
8-Bit-Register	1
16-Bit-Register	2
32-Bit-Register	4
Segment-Register	2
Control-Register	4
Debug-Register	4
Test-Register	4
MMX-Register	8
Floating-Point-Register	10
BYTE	1
SBYTE	1
WORD	2
SWORD	2
DWORD	4
SDWORD	4
REAL4	4
FWORD	6
QWORD	8
REAL8	8
TBYTE	10
REAL10	10
NEAR	2 or 4
NEAR16	2
NEAR32	4
FAR	4 or 6
FAR16	4
FAR32	6
Numeric-EquateName	Inherited from equate expression
GroupName	2
SegmentName	2
Code-LabelName	SIZE (TYPE Code-LabelName)
Data-LabelName	SIZE (TYPE Data-LabelName)
Structure-FieldName	SIZE Structure-FieldName
Record-TypeName	SIZE Record-TypeName
Structure-TypeName	SIZE Structure-TypeName
Union-TypeName	SIZE Union-TypeName

The Operand Size is 0 for all other identifier types.

Displacement

The Displacement value in an expression is the final calculated value of all numeric quantities, and must be a scalar value. It may also be a reference to a relocatable address, in which case the expression will also have a Relative Frame and/or an External Reference attribute. A Displacement may be used in the calculation of an effective address, either alone or in combination with a Base Register and/or an Index Register.

Relative Frame

The Relative Frame attribute will be present if the expression contains a direct or indirect reference to any of the following #Identifier-Types:

• GroupName
• LabelName
• SegmentName

The Relative Frame attribute indicates that the expression is relocatable, and specifies the GroupName or SegmentName to which the expression is relative.

External Reference

The External Reference attribute will be present if the expression references any external identifiers.

Register Value

The Register Value attribute specifies the value of the Processor-Register referenced in a Register-ExpressionType.

Base Register

The Base Register attribute specifies the value for the base register used in an Indexed-ExpressionType.

Index Register

The Index Register attribute specifies the value for the index register used in an Indexed-ExpressionType.

Scale Factor

The Scale Factor attribute specifies the scaling value used (if any) in an Indexed-ExpressionType.

Type Declaration

The Type Declaration attribute specifies the type of data referenced in the expression. This is the value extracted from the expression when it is used as the left operand of the #Type Conversion (PTR Operator).

Expression Types

Description

An ExpressionType is assigned to every expression during evaluation. The ExpressionType is used to determine whether or not an expression is legal for the context in which it is used. The type of an expression is influenced primarily by the operands that are used, but the use of expression operators also play an important part in determining the type of an expression.

Definition

ExpressionType:

Absolute-ExpressionType

Constant-ExpressionType

Direct-ExpressionType

Floating-Point-ExpressionType

Immediate-ExpressionType

Indirect-ExpressionType

Indexed-ExpressionType

Register-ExpressionType

String-ExpressionType

Type-ExpressionType

Duplicated-ExpressionType

Compound-ExpressionType

Absolute Expression Type

An Absolute-ExpressionType is an expression that evaluates to an integer quantity. Its value must be representable using one of the following types of scalar data:

• BYTE
• SBYTE
• WORD
• SWORD
• DWORD
• SDWORD
• FWORD
• QWORD
• TBYTE

The following restrictions apply to an Absolute-ExpressionType:

• It cannot be relocatable (it may not contain references to a GroupName, SegmentName or LabelName).
• It cannot reference any external symbols.
• It cannot contain any forward references.

Constant Expression Type

A Constant-ExpressionType is an Absolute-ExpressionType with the following restrictions relaxed:

• It may contain forward references to identifiers defined later in the source stream.
• It may reference a single external symbol, provided that the symbol was declared in an EXTERN directive with the ABS attribute.

Immediate Expression Type

An Immediate-ExpressionType has all the properties of a Constant-ExpressionType with the following restrictions relaxed:

• It may contain references to a GroupName, SegmentName or LabelName(it may be relocatable).
• It may reference a relocatable external symbol.

An Immediate-ExpressionType must not be larger than 32 bits in magnitude; its value must be representable using one of the following types of scalar data:

• BYTE
• SBYTE
• WORD
• SWORD
• DWORD
• SDWORD

Direct Expression Type

A Direct-ExpressionType is an expression that references a Code-LabelName. It can be used directly in code-relative instructions without conversion. There is no data type associated with the address that a Direct-ExpressionType represents, therefore It may not be used in a data-relative instruction without first being explicitly converted to another expression type.

Indirect Expression Type

An Indirect-ExpressionType is an expression that references a Data-LabelName. It can be used directly in data-relative instructions without conversion to another expression type.

Indexed Expression Type

An Indexed-ExpressionType is an expression that calculates an effective memory address using the contents of a Base-Register, an Index-Register, or both. A Processor-Register must first be converted to a Base-Register or Index-Register by specifying it as the operand of the [[#Indirection ([] Operator)]]before the expression can be converted to an Indexed-ExpressionType.

When calculating a 16-bit effective address, only the BP and BX registers may be used as Base-Registers, and only the DI and SI registers may be used as Index-Registers.

When calculating a 32-bit effective address, only the EAX, EBX, ECX, EDX, EDI, ESI, EBP, and ESP registers may be used as Base-Registers, and only the EAX, EBX, ECX, EDX, EDI, ESI, and EBP registers may be used as Index-Registers.

Note: Only a single Base-Register and a single Index-Register may be used in a given expression.

On 80386 (and higher) processors, the #Multiplication (* Operator) may be used with an Index-Registeroperand and an Absolute-ExpressionType operand to establish a scaling factor that is applied to the Index-Register during effective address calculation. The scaling factor effectively causes the Index-Register to be multiplied by a fixed value at run time. The scaling Expression must evaluate to 1 (no scale factor), 2, 4, or 8.

A Direct-ExpressionType or an Indirect-ExpressionType may be a sub-expression of an Indexed-ExpressionType.

Register Expression Type

A Register-ExpressionType is an expression that specifies a single Processor-Register.

String Expression Type

A String-ExpressionType is an expression that specifies a single String- Literal.

Floating-Point Expression Type

A Floating-Point-ExpressionType is an expression that specifies a single Floating-Point-Literal.

Type Expression Type

A Type-ExpressionTypeis an expression that specifies one of the following:

• A Scalar-TypeName
• A Distance-TypeName
• A UserDefined-TypeName

Compound Expression Type

A Compound-ExpressionType evaluates to a list of (possibly nested) expressions collected together as a unit by the #Compound Initializer List ( <> Operator). A Compound-ExpressionTypeis used to initialize #aggregate data types (such as records, structures, and unions) and #vector data types (arrays).

Duplicated Expression Type

A Duplicated-ExpressionType evaluates to an expression that is to be duplicated (repeated) a specified number of times. This type of expression is created using the #Duplicative Initialization (DUP Operator).

Operand Expression Type

An Operand-ExpressionType consists of those #ExpressionTypes that are valid for use as operands in processor instructions. The following ExpressionTypes are not valid for use as an Operand-ExpressionType:

• Compound-ExpressionType
• Duplicated-ExpressionType
• A String-ExpressionType is only valid as an Operand-ExpressionType if it is short enough to be converted to an Absolute-ExpressionType having an Operand Size less than or equal to the current Address Size setting.

Operand-ExpressionType:

Absolute-ExpressionType

Constant-ExpressionType

Immediate-ExpressionType

Direct-ExpressionType

Indirect-ExpressionType

Indexed-ExpressionType

Register-ExpressionType

String-ExpressionType

Floating-Point-ExpressionType

Type-ExpressionType

Description

An Operand-ExpressionTypeconsists of those #ExpressionTypes that are valid for use as operands in processor instructions. The following ExpressionTypes are not valid for use as an Operand-ExpressionType:

• Compound-ExpressionType
• Duplicated-ExpressionType

A String-ExpressionType is only valid as an Operand-ExpressionType if it is short enough to be converted to an Absolute-ExpressionType having an Operand Size less than or equal to the current Address Size setting.

Definition

Operand-ExpressionType:

Absolute-ExpressionType

Constant-ExpressionType

Immediate-ExpressionType

Direct-ExpressionType

Indirect-ExpressionType

Indexed-ExpressionType

Register-ExpressionType

String-ExpressionType

Floating-Point-ExpressionType

Type-ExpressionType

Initializer Expression Type

An Initializer-ExpressionType consists of those #ExpressionTypes that are valid for use in initializing variables. The following ExpressionTypes are not valid Initializer-ExpressionTypes:

• Indexed-ExpressionType
• Register-ExpressionType

Initializer-ExpressionType:

Scalar-Initializer-ExpressionType

Compound-ExpressionType

Duplicated-ExpressionType

Scalar-Initializer-ExpressionType:

Absolute-ExpressionType

Constant-ExpressionType

Immediate-ExpressionType

Direct-ExpressionType

Indirect-ExpressionType

String-ExpressionType

Floating-Point-ExpressionType

Type-ExpressionType

Description

An Initializer-ExpressionType consists of those #ExpressionTypes that are valid for use in initializing variables. The following ExpressionTypes are not valid Initializer-ExpressionTypes:

• Indexed-ExpressionType
• Register-ExpressionType

Definition

Initializer-ExpressionType:

Scalar-Initializer-ExpressionType

Compound-ExpressionType

Duplicated-ExpressionType

Scalar-Initializer-ExpressionType:

Absolute-ExpressionType

Constant-ExpressionType

Immediate-ExpressionType

Direct-ExpressionType

Indirect-ExpressionType

String-ExpressionType

Floating-Point-ExpressionType

Type-ExpressionType

Text Preprocessor

The text preprocessor is a functional unit within the assembler that performs the text preprocessing translation phase. During text preprocessing, the following actions are performed:

1. Language Elements are recognized.
2. Text equates and macros are expanded.
3. Macro directives and conditional assembly directives are recognized and processed.
4. The preprocessed output is passed on to the assembler for final processing.

This section also describes the various types of preprocessor directives:

Type	Function	Directives
Conditional Assembly	Tests for a specified condition and assembles a block of statements if the condition is true.	IF IFB IFDEF IFDIFI IFE IFIDN IFNB IFNDEF IF1 IF2 ELSE ENDIF
Text Equate	Allows assignment of simple text strings to a symbolic name. Provides functions for expanding and operating on the values.	CATSTR EQU INSTR SIZESTR SUBSTR
Macro	Provides text processing that is done sequentially at assembly time. By the end of assembly, ALP expands all macros and assembles the resulting text into object code.	ENDM EXITM FOR FORC IRP IRPC LOCAL MACRO PURGE REPEAT REPT
Miscellaneous	Miscellaneous text processing functions.	COMMENT ECHO %OUT INCLUDE

Text Operators

Description

The #Text Preprocessor recognizes certain punctuator characters as text operators. The programmer may use these operators to force the Text Preprocessor to perform various operations such as delineating text, expanding arguments, and converting expressions into their text representations.

Syntax

Text-Operator:

Literal-Character-Operator

Literal-Text-Operator

Text-Expansion-Operator

Text-Substitution-Operator

Literal Character Operator (!)

Syntax

Literal-Character-Operator:

! any printable character

Description

When you use an exclamation point (!) in an operand, ALP treats the next character literally. (!) is typically used to prevent the assembler from recognizing and acting upon special characters such as the semicolon (;) or the ampersand (&), forcing them to appear as normal data characters.

Constraints

The Literal-Character-Operator has no effect when used inside of a String-Literal.

Examples

In this example, use of the ! in the second macro argument prevents the assembler from interpreting the rest of the line as a comment:

MACRONAME   First, !; NonComment, Third              ; Comment

Literal Text Operator (<>)

Syntax

Literal-Text-Operator:

< Char-Sequence >

Char-Sequence

any printable character

Char-Sequence any printable character

Description

The literal-text operator directs the assembler to treat Char-Sequence as a single literal element regardless of whether it contains commas, spaces, or other separators. The operator is most often used with macro calls and the FOR directive to ensure that values in a parameter list are treated as a single parameter.

The literal-text operator can also be used to force ALP to treat other special characters such as the semicolon (;) or the ampersand (&) literally. For example, the semicolon inside angle brackets (<>) becomes a semicolon, not a comment indicator.

ALP removes one set of angle brackets each time the parameter is used in a macro. When using nested macros, you will need to supply as many sets of angle brackets as there are levels of nesting. The assembler recognizes nested occurrences of text literals.

Examples

The following example illustrates how to pass arbitrary text to a macro as a single parameter:

MACRONAME   First, <Second Argument>, <Third, <Nested>, Argument>

The macro will receive three separate arguments:

1. First
2. Second Argument
3. Third, <Nested>, Argument

Notice that the outermost set of angle brackets were removed from the second and third arguments.

Text Expansion Operator (%)

Syntax

Text-Expansion-Operator:

% 2nd through Nth token on line

% Text-EquateName

% Expression

Description

The % Text-Expansion-Operator has different effects depending upon the context in which it is used. Its primary purpose is convert various sources of information into text literals that may in turn be passed to macros as arguments.

The % Text-Expansion-Operator causes the following types of conversions:

Line Expansion

When used as the first token on the line, the % operator forces expansion of Text-EquateNames in contexts where they would otherwise be left unexpanded. Text-EquateNames passed as arguments to macros are not automatically expanded; this is one context where the % operator is useful.

Expansion of a Text Equate Operand

As with Line Expansion, the % operator may be used within the body of a line to expand individual Text-EquateNames. This can be useful when expansion of all Text-EquateNames on the line is not desired.

Conversion of Numeric Expression to Text

If the Text-Expansion-Operatoris not the first token on the line or immediately followed by a Text-EquateName, then the argument of the % operator is assumed to be an Expression, which is evaluated and converted to the text representation of its value. This is useful when the need arises to pass the text representation of a number to a macro.

Constraints

When the % Expression form of the expansion operator is used, the Expression must evaluate to an Immediate-ExpressionType.

Examples

MakErr       MACRO       X 
LB           =           0 
             REPEAT      X 
LB           =           LB + 1 
             MakLib      % LB 
             ENDM        ; ; End of REPEAT
             ENDM        ; ; End of MACRO
MakLib       MACRO       Y 
Err & Y :    DB     ' Error    & Y ' ,0 
             ENDM 

             MakErr   3 
Err1 :    DB    ' Error   1 ' ,0
Err2 :    DB    ' Error   2 ' ,0
Err3 :    DB    ' Error   3 ' ,0

Text Substitution Operator (&)

Syntax

Text-Substitution-Operator:

Macro-ParameterName &

& Macro-ParameterName

Description

An ampersand (&) is used in the body of a macro to force the substitution of a Macro-ParameterName with the value of its argument during expansion of the macro.

Constraints

The assembler does not substitute a Macro-ParameterName that is in a quoted string or not preceded by a delimiter in the expansion unless it is immediately preceded by an ampersand (&).

It is necessary to separate a Macro-ParameterName from other Identifer-Characters with an ampersand (&) before any substitution or paste operations are performed.

Examples

ErrGen    MACRO     X 
Error &X: push      bx 
ABX       mov       BX, "A"; 
AB &X     mp        ERROR 
          ENDM

The statement ErrGen A produces this code:

ErrorA :   push     bx 
ABX        mov      BX , "A"; 
ABA        jmp      ERROR 

Preprocessor Tokens

Syntax

Preprocessing-Token:

Identifier

Text-Literal

FileName

Comment

Description

During the text preprocessing translation phase, certain conditions will cause the preprocessor to convert raw #Language Elements (#Tokens) into Preprocessing-Tokens. The act of text preprocessing typically causes Preprocessing-Tokens to either be removed from the input stream or converted back into Tokens before being passed on to the assembler for final processing.

Text Literals

Syntax

Text-Literal:

operand of Literal-Character-Operator

operand of Literal-Text-Operator

Description

A Text-Literal is a single unit of text that is used by the #Text Preprocessor in many different text handling contexts. In some contexts ( such as the processing of arguments to be passed to a macro), normal language #Tokens are implicitly treated as Text-Literals, provided they are not a delimiter character such as a comma or a blank. In other contexts, it may be necessary to explicitly convert a unit of text to a Text-Literal using the Literal-Text-Operator.

Constraints

A normal language Token is never implicitly considered to be a Text-Literal if a Text-Literal is explicitly required in the syntax of the construct being parsed.

File Names

Syntax

FileName:

FileName-Text

Text-Literal

FileName-Text:

FileName-Character

FileName-Text FileName-Character

FileName-Character:

any printable character except blank (ASCII 32)

Description

FileName arguments may be coded as an arbitrary sequence of printable characters, or as a Text-Literal; use the Text-Literal form if the FileName is to contain embedded spaces or other special characters.

If path information is included in the FileName, you can separate the individual directory names with either the back slash (\) or the forward slash (/) and they will be treated identically by the assembler.

Examples

  INCLUDE      <inc\macros.inc> 
  INCLUDELIB   os2386.lib

Comments

Comments are language elements that have significance only to the programmer and not to the assembler. Comments are effectively removed from the input stream during the text preprocessing phase.

There are two classes of comments recognized by ALP:

• Comments that start with a character sequence and continue to the end of the line (EndOfLine-Comment)

• Comments that start with a character sequence and continue until the occurrence of another character sequence (Block-Comment). See the #COMMENT directive for a description of #Block-Comments.

There are two types of EndOfLine-Comments:

Macro-Comment

Macro-Comments (beginning with two semicolons) do not appear in the listing output even when the .LALL directive is used. Use of Macro-Comments can significantly reduce the amount of memory workspace used by the definition of a macro. As a macro definition is read, Macro-Comments are discarded and not entered into the macro definition, whereas NonMacro-Comments are treated as normal text and are retained.

NonMacro-Comment

NonMacro-Comment (beginning with a single semicolon) are preserved in macro definitions and appear in the listing output during macro expansions.

Syntax

Comment:

EndOfLine-Comment

Block-Comment

EndOfLine-Comment:

NonMacro-Comment

Macro-Comment

NonMacro-Comment:

; Char-Sequence

Macro-Comment:

;; Char-Sequence

Char-Sequence:

any printable character

Char-Sequence any printable character

#Block-Comment:

See the #COMMENT directive

Description

Comments are language elements that have significance only to the programmer and not to the assembler. Comments are effectively removed from the input stream during the text preprocessing phase.

There are two classes of comments recognized by ALP:

• Comments that start with a character sequence and continue to the end of the line (EndOfLine-Comment)
• Comments that start with a character sequence and continue until the occurrence of another character sequence (Block-Comment). See the #COMMENT directive for a description of #Block-Comments.

There are two types of EndOfLine-Comments:

Macro-Comment

Macro-Comments (beginning with two semicolons) do not appear in the listing output even when the .LALL directive is used. Use of Macro-Comments can significantly reduce the amount of memory workspace used by the definition of a macro. As a macro definition is read, Macro-Comments are discarded and not entered into the macro definition, whereas NonMacro-Comments are treated as normal text and are retained.

NonMacro-Comment

NonMacro-Comment (beginning with a single semicolon) are preserved in macro definitions and appear in the listing output during macro expansions.

Example

The following are examples of EndOfLine-Comments:

; Comments may be on a line all by themselves. They can be empty ...
; 
                        ; They don't have to start in the first column
BumpCount MACRO Amount  ; They can appear to the right of statements
  Count = Count + Amount       ; This appears in macro expansions
  $Total = $Total + Amount     ;; This does not, discarded during definition
ENDM

Text Arguments

Many preprocessing directives operate on sequences of raw text characters called Text-Arguments. A Text-Argumentmay be specified using any one of several methods:

• Specifying the text directly using a raw Text-Literal.
• Using the Text-Expansion-Operator to convert a numeric expression to its text representation.
• Using a Text-EquateName in those contexts where a Text-Argumentis expected. In this case the preprocessor will automatically resolve the Text-EquateName and use its value as the Text-Argument.

Text-Argument:

Text-Literal

% Expression

Text-EquateName

Description

Many preprocessing directives operate on sequences of raw text characters called Text-Arguments. A Text-Argumentmay be specified using any one of several methods:

• Specifying the text directly using a raw Text-Literal.
• Using the Text-Expansion-Operator to convert a numeric expression to its text representation.
• Using a Text-EquateName in those contexts where a Text-Argument is expected. In this case the preprocessor will automatically resolve the Text-EquateName and use its value as the Text-Argument.

Syntax

Text-Argument:

Text-Literal

% Expression

Text-EquateName

Conditional Assembly Directives

At assembly time, ALP evaluates conditional assembly directives, assembling if the conditions are true. You can use conditional assembly directives when you want to test for a specified condition and assemble a block of statements if the condition is true. The #IFxx and #ENDIF directives enclose the statements to be considered for conditional assembly. The optional #ELSEIFxx and #ELSE blocks follow the #IFxx directive. There are many forms of the #IFxx and #ELSEIFxx directives.

This section describes the following conditional assembly directives:

#IF

#IFB

#IFDEF

#IFDIF

#IFDIFI

#IFE

#IFIDN

#IFIDNI

#IFNB

#IFNDEF

#IF1

#IF2

#ELSE

#ENDIF

IFxx (Begin Primary Conditional Block)

You can use each IFxxconditional directive with the #ELSExx, #ELSE and #ENDIF directives to provide the statements to be considered for conditional assembly. ALP assembles the statements following the #IFxx directive only if this condition is true.

Syntax

IFxx   operand
   .
   .
   .
[ ELSEIFxx ]   ( optional )
   .
   .
   .
[ ELSE ]   ( optional )
   .
   .
   .
ENDIF

Remarks

The following directives are members of the IFxx family:

• IF
• IFB
• IFDEF
• IFDIF
• IFDIFI
• IFE
• IFIDN
• IFIDNI
• IFNB
• IFNDEF
• IF1
• IF2

You can nest the conditional directives to any level. They are not limited to use within a macro. The assembler must know any operand to a conditional on pass one to avoid errors and incorrect evaluation.

IF (If Expression is True)

IF starts a conditional assembly statement, which is ended by the corresponding #ENDIF conditional assembly directive. Each IF directive must be ended by a matching ENDIF directive.

Syntax

IF Expression 
    .
    .
    .
[ ELSEIFxx ]   (optional)
    . 
    . 
    .
[ ELSE ]   (optional)
    .
    .
    .
ENDIF

Remarks

If the #IFxx conditional assembly statement is not ended by an #ENDIF directive, an unterminated conditional message is produced by the assembler. An ENDIF without a matching IF causes an error. ENDIF does not have an operand.

Note: The conditional directives can be nested to any level. They are not limited to use within a macro. Any operand to a conditional must be known on pass 1 to avoid errors and incorrect evaluation.

Example

IF   debug
     EXTERN   dump:FAR
     EXTERN   trace:FAR
     EXTERN   breakpoint:FAR
ENDIF

IFB (If Argument is Blank)

This is true if #Text-Argument is blank (contains no characters).

Syntax

IFB Text-Argument

Remarks

A #Text-Argument must be specified, the contents of which are checked for the presence of characters. An error is generated if a Text-Argument is not supplied.

IFDEF (If Identifier is Defined)

This is true if #Identifier has been defined as a label, variable, or symbol.

Syntax

IFDEF Identifier

IFDIF (If Arguments Are Different)

This is true if #Text-Argument-1 and Text-Argument-2 are different in a case-sensitive comparison.

Syntax

IFDIF Text-Argument-1, Text-Argument-2

Remarks

Both Text-Argument arguments must be specified. An error is generated if a either argument is not supplied.

Example

In the following example:

IFDIF <EAGLES>,<Eagles>;
  value = 1
ENDIF

the condition would be true; the arguments are different because they are compared with a case-sensitive algorithm.

IFDIFI (If Arguments Are Spelled Differently)

This is true if #Text-Argument-1 and Text-Argument-2 are different in a case-insensitive comparison.

Syntax

IFDIFI Text-Argument-1, Text-Argument-2

Remarks

Both Text-Argument arguments must be specified. An error is generated if a either argument is not supplied.

Example

In the following example:

IFDIFI <EAGLES>, <Eagles>
  value = 1
ENDIF

the condition would be false; the arguments are not different because they are compared using a case-insensitive algorithm.

IFE (If Expression is Not True)

This is true if expression is 0.

Syntax

IFE   Expression 

IFIDN (If Arguments Are Identical)

This is true if #Text-Argument-1 and Text-Argument-2 are identical in a case -sensitive comparison.

Syntax

IFIDN   Text-Argument - 1, Text-Argument - 2

Remarks

Both Text-Argument arguments must be specified. An error is generated if a either argument is not supplied.

Example

In the following example:

IFIDN   <EAGLES>, <Eagles>; 
  value   =   1 
ENDIF

the condition would be false; the arguments are not identical because they are compared using a case-insensitive algorithm.

IFIDNI (If Arguments Are Spelled Identically)

This is true if #Text-Argument-1 and Text-Argument-2 are identical in a case -insensitive comparison.

Syntax

IFIDNI   Text-Argument - 1, Text-Argument - 2

Remarks

Both Text-Argument arguments must be specified. An error is generated if a either argument is not supplied.

Example

In the following example:

IFIDNI <EAGLES>, <Eagles>
  value = 1
ENDIF

the condition would be true; the arguments are identical because they are compared using a case-insensitive algorithm.

IFNB (If Argument is Not Blank)

This is true if Text-Argument is not blank (characters are present).

Syntax

IFNB Text-Argument

Remarks

A Text-Argument must be specified, the contents of which are checked for the presence of characters. An error is generated if a Text-Argument is not supplied.

IFNDEF (If Identifier is Not Defined)

This is true if symbol has not yet been defined as a label, variable, or symbol.

Syntax

IFNDEF symbol

IF1 (If Assembling On Pass 1)

This is true on pass one.

Syntax

IF1

Remarks

IF1 does not have an operand.

IF2 (If Assembling On Pass 2)

This is true on pass two.

Syntax

IF2 

Remarks

IF2does not have an operand.

ELSEIFxx/ELSE (Begin Alternate Conditional Block)

Each conditional directive can be used with the ELSE directive to provide the statements to be considered for conditional assembly. The ELSE directive allows the assembly of the statements following it when the #IFxx condition or intervening ELSEIFxx conditions are false.

Syntax

IFxx 
    .
    .
    . 
[ ELSEIFxx ]   ( optional ) 
    .
    .
    . 
[ ELSE ]   ( optional ) 
    .
    . 
    . 
ENDIF 

Remarks

There is a corresponding ELSEIFxx directive to match all forms of the #IFxx family of directives:

• #ELSEIF
• #ELSEIFB
• #ELSEIFDEF
• #ELSEIFDIF
• #ELSEIFDIFI
• #ELSEIFE
• #ELSEIFIDN
• #ELSEIFIDNI
• #ELSEIFNB
• #ELSEIFNDEF
• #ELSEIF1
• #ELSEIF2

For information about the meaning of the conditional tests performed by the ELSEIFxx directives, refer to the definitions for the corresponding #IFxx directives.

Any number of ELSEIFxx blocks may be used within a given IFxx statement. Only one ELSE block is permitted for a given IFxx. A conditional directive with more than one ELSE or an ELSE without a conditional directive causes an error. ELSE does not have an operand.

Note: The conditional directives can be nested to any level. They are not limited to use within a macro. Any operand to a conditional must be known on pass 1 to avoid errors and incorrect evaluation.

Example

IF DEFBUF
  BUF DB 100 DUP(0)
ELSE 
  EXTERN BUF:BYTE
ENDIF

ENDIF (End a Conditional Assembly Statement)

ENDIF ends the conditional assembly statement begun by the corresponding #IFxx conditional assembly directive. Each IFxx directive must be ended by a matching ENDIF directive.

Syntax

IFxx 
    .
    .
    .
[ ELSEIFxx ]   ( optional ) 
    .
    .
    .
[ ELSE ]   ( optional ) 
    .
    .
    .
ENDIF

Remarks

If the #IFxx conditional assembly statement is not ended by an ENDIF directive, an unterminated conditional message is produced by the assembler. An ENDIF without a matching IFxx causes an error. ENDIF does not have an operand.

Note: The conditional directives can be nested to any level. They are not limited to use within a macro. Any operand to a conditional must be known on pass 1 to avoid errors and incorrect evaluation.

Example

IF  debug
   EXTERN   dump:FAR
   EXTERN   trace:FAR
   EXTERN   breakpoint:FAR
ENDIF

Text Equate Directives

A Text Equate is a symbolic name you give to a series of characters. Text equates are used to expand text within a source statement. The directives described in this section create and manipulate text equates.

EQU
CATSTR
INSTR
SIZESTR
SUBSTR

CATSTR (Concatenate Strings)

CATSTR concatenates a list of text values specified by string into a single text value and assigns it to Name.

Syntax

Name CATSTR string[, string] ...

EQU Directive (Assign Text to a Symbolic Constant)

The EQU directive assigns the contents of a text literal to Name.

Syntax

Name EQU   Text - Literal

Remarks

The value of the Text-Literal is assigned to the Name entry. In normal contexts, subsequent references to Name will cause the preprocessor to replace Name with the value specified by the Text-Literal entry. This is a simple text substitution operation.

The Name entry is a globally-scoped Identifier that is converted to a Text-EquateName. The Name cannot have been previously defined as a different Identifier-Type. However, the Name entry can be redefined as many times as desired with different values for the Text-Literal entry.

See also #EQU and #=.

Example

A   EQU  < BP + >    ; explicit text literal, A is a text equate
A   EQU  < 3 >       ; redefinition of A with different value

INSTR (Search In String For Value)

INSTRsearches a specified String for an occurrence of a given Sub-String and assigns its position (1-based) to Name. The search is case sensitive. Startis the position in String to start the search for Sub-String. If Startis not given, it is assumed to be 1 (the start of the string). If Sub-String is not found, the position assigned to Name is 0.

Syntax

Name   INSTR   [ Start , ] String , Sub-String

Remarks

INSTRassigns the position value to a name as if it were a numeric equate.

Example

pos   INSTR   < person > , < son >

SIZESTR (Return Size Of String)

Assigns the number of characters given by the Text-Argument to Name.

Syntax

Name  SIZESTR  Text-Argument

SUBSTR (Extract a Sub-string From a String)

Assigns a substring of Text-Argument starting at Position to the symbol given by Name..

Syntax

Name SUBSTR Text-Argument,Position[,Length]

Remarks

The Position parameter indicates the starting character of the substring to extract from the Text-Argument, and must be 1 or greater. If specified, the Length parameter indicates how many characters are desired, otherwise the remainder of the string is extracted.

Macro Directives

A macro procedure or function, which is comprised of one or more statements.

Macro processing is text processing that is done sequentially at assembly time. By the end of assembly, ALP expands all macros and assembles the resulting text into object code.

This section describes the following types of macros:

• Macro procedures, which expand to one or more complete statements and can optionally take parameters
• Repeat blocks, which generate a group of statements a specified number of times or until a condition becomes true

This section describes the following macro directives:

ENDM

EXITM

FOR/IRP

FORC/IRPC

LOCAL

MACRO

PURGE

REPEAT/REPT

ENDM (End Current Macro Definition)

End each #MACRO, #REPEAT/REPT, #FOR/IRP, and #FORC/IRPC directive with the ENDMdirective.

Syntax

ENDM

Remarks

If the ENDM directive is not used with the #MACRO, #REPEAT/REPT, #FOR/IRP, and #FORC/IRPC directives, an error occurs. An unmatched ENDM also causes an error.

If the assembler produces an error message stating that it found the end-of -file on the source and cannot find an #END statement when there was an END, the likely cause is a missing ENDM or ENDIF statement. Without ENDM, the assembler treats the rest of the source as part of the #MACRO definition.

Note: The name field is not allowed. Do not confuse the ENDM directive with other ending directives that do require the name of the block being ended, such as ENDP or ENDS.

Example

addup   MACRO     ad1, ad2, ad3
        MOV       AX, ad1         ;; first parameter in AX
        ADD       AX, ad2         ;; add next two parameters 
        ADD       AX, ad3         ;; leave sum in AX
        ENDM

EXITM (End Current Macro Expansion)

Use the EXITM directive when a block contains a directive that tests for some condition and you want to end the current macro expansion when the test proves that the remainder of the expansion is not required. When an EXITM directive is run, the expansion is stopped immediately, and any remaining expansion or repetition is not produced.

Syntax

EXITM

Remarks

Only the block containing the EXITM directive is ended; outer levels of a nested macro expansion continue unaffected.

EXITM is executed at macro expansion time and is not a substitute for the #ENDM directive, which marks the end of the macro body and is recognized at macro definition time.

Example

DSEG   SEGMENT 
      .
      .
      .
SYM   =   0 
    REPEAT 16
; ; Check for paragraph boundary
      IF   ( $ - DSEG ) MOD 16 EQ 0
      EXITM   ; ; quit if padded to boundary
      ENDIF 
SYM = SYM + 1 
      DB   SYM   ; ; produce numbered padding
      ENDM 

FOR/IRP (Iterative Macro Expansion Using List of Arguments)

The FOR directive, used in combination with the #ENDM directive, designates a block of statements to be repeated, once for each argument in the list enclosed by angle brackets. Each repetition substitutes the next item in the <Argument-List> entry for every occurrence of Parameter in the block.

Syntax

FOR  Parameter , < Argument-List >
    .
    .
    .
ENDM

Remarks

The obsolete spelling for the FOR directive is IRP.

You must enclose the <Argument-List> entry in angle brackets. It has the following format:

< [ Argument   [ ,   Argument   . . . ] ] >

If an empty (<>) Argument is found in <Argument-List>, the Parameter name is replaced by a null value. If the argument list is empty, the FORdirective is ignored and no statements are copied. The assembler processes the block once for each Argumentin the <Argument-List>, replacing each occurrence of Parameterin the macro body with the current Argument value.

The #FOR/IRP-#ENDM block does not have to be within a macro definition.

Example

In this example, the assembler produces the code DB1 through DB10.

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

In the next example:

FOR      ARGUMENT , < " first   line " , 13 , 10 , 
" second   line " , 13 , 10 > 
DB      ARGUMENT 
ENDM 

The assembler produces the code:

DB     " first   line " 
DB     13 
DB     10 
DB     " second   line " 
DB     13 
DB     10 

FORC/IRPC (Iterative Macro Expansion Using List of Characters)

The assembler repeats the statements in the block once for each character in the string. Each repetition substitutes the next character in the string for every occurrence of Parameterin the block.

Syntax

FORC   Parameter ,  String ( or < String > ) 
    .
    .
    .
ENDM 

Remarks

The obsolete spelling for the FORCdirective is IRPC.

The FORCdirective is similar to the #FOR/IRP directive except that a String is used instead of <Argument-List>, and the angle brackets around the string are optional. The string should be enclosed with angle brackets (<>) if it contains spaces, commas, or other separating characters.

The FORC/IRPC-#ENDM block does not have to be within a macro definition.

Example

In this example, the assembler produces the code DB 1 through DB 8:

FORC      X, 12345678
DB        X
ENDM

LOCAL (Identify Names Local to a Macro Definition)

The LOCAL directive is used inside the body of a macro definition, and provides a method of automatically generating unique assembler labels each time the macro is expanded. The names appearing in the argument list of the LOCAL directive are known only to the enclosing macro, and each time they are referenced during a macro expansion a unique symbol is created. This prevents the assembler from issuing duplicate definition errors when the macro is expanded more than once and symbols contained therein are being used to create assembler labels.

Syntax

LOCAL Name [, Name .... ]

Remarks

The LOCAL directive is recognized only within the body of a macro given by a #MACRO, #FOR/IRP, #FORC/IRPC, or #REPEAT/REPT definition. The symbols created by the preprocessor are of the form ??nnnn, where nnnn is a hexadecimal number in the range 0000 through FFFF. You must avoid using identifiers of this form for your own purposes, because doing so can cause duplicate definition errors.

To insure that they have the proper effect, LOCAL statements should appear in the body of the macro before any other directives are used. It is acceptable for blank lines or comments to precede any LOCAL statements.

You can use multiple LOCAL statements if the argument list is too long to fit on one line, or if you want a vertical list of LOCAL symbols.

Example

DISPLAY MACRO TT 

; Blank lines and comments are ok here
      LOCAL AGAIN 

;; DOS macro to display message addressed by BX TT times
      MOV     CX, TT
      MOV     AH, 9
      MOV     DX, BX
; Generate a unique label for AGAIN
AGAIN:
      INT     21H 
      LOOP    AGAIN 
      ENDM

MACRO (Assign a Body of Text to a Name)

This directive produces a given sequence of statements from various places in your program, even though different parameters may be required each time you call the sequence.

Macro processing consists of two separate and distinct phases: #Macro Definition and #Macro Expansion.

Macro Definition

A macro definition consists of three essential parts:

• The MACRO directive, defining the Name and the Parameter-List
• The body of the macro, containing the prototypes of statements to produce when you invoke the macro for expansion.
• The #ENDM directive, ending the definition of the macro.

Syntax

Name MACRO [Parameter [, Parameter ...]]
  .
  .
  .
ENDM

Remarks

The Name field must be a valid preprocessor identifier and specifies the symbolic name that the user will refer to when invoking the macro for expansion. If Name is already defined, it must be that of a previous macro definition, otherwise an error message is issued. Macros may be redefined to have a different Parameter-Lists or macro body text; doing so causes the previous definition to be lost.

The optional Parameter-List is the complete comma-separated list of all Parameter valuess given in the macro definition statement. A parameter must be a valid symbol name according to the rules for naming preprocessor and assembler identifiers. Each parameter becomes a symbol that is local to the macro being defined and is recognized during macro expansion prior to searching the global name space. Thus, macro parameters need not have names unique from identifiers defined elsewhere in the program.

Macro Expansion

To expand the macro, the macro Name (defined in the Name field of the MACRO definition statement) is coded as you would any other assembler directive, followed by the list of arguments (if any) that you want to pass to the macro.

Syntax

Name [Argument [, Argument ...]]

Remarks

The Name field must be the name of a macro defined previously with a MACRO directive.

Each Argument field denotes a text value that you want to pass to the macro. The relative positions of the elements are important, because each Argument is associated in left-to-right fashion with the corresponding Parameter as defined in the Parameter-List during the macro definition.

The number of Argument entries given when the macro is invoked need not be the same as the number of Parameter entries. If you pass extra Arguments to the macro, they are ignored; if too few are supplied, empty text values are associated with the remaining Parameters. You may also associate an empty text value with a Parameter by passing an explicitly empty text literal <> as an Argument.

Commas are normally used to separate arguments, although blanks or tabs are also considered to be argument separators. For this reason, any argument that must contain an argument separator character (commas, blanks, or tabs) should be enclosed in angle brackets <>. For example:

PUSHVEC   MACRO   PARM1, PARM2
          MOV     AX, PARM1
          PUSH    AX
          MOV     AX, PARM2
          PUSH    AX
          ENDM
          .
          .
          .
          PUSHVEC   DS, <OFFSET VARNAME>
 ; PUSH DWORD VECTOR OF VARNAME ONTO STACK

You can also use angle brackets to produce variable lengths of results. For example:

STRING   MACRO     NUMBERS
         DB        NUMBERS
         ENDM
           .
           .
           .
         STRING   <1,2,3,4>
         ; PRODUCE 4 BYTES OF INTEGER NUMBERS

Remarks

Each time a macro is invoked (expanded) by specifying its name, the preprocessor emits the statements contained in the body of the macro and passes them to the assembler for processing. During the expansion process, any replacement parameters encountered in the macro body (as named in the Parameter-List of the macro definition) are replaced with the corresponding Argument (if any) passed through the argument-list at the time the macro was invoked.

Example

GEN   MACRO   XX, YY, ZZ
      MOV     AX, XX
      ADD     AX, YY
      MOV     ZZ, AX
      ENDM

When the call is made, for example:

GEN   ED, KISER, SUM

The assembler produces the following code:

MOV     AX, ED
ADD     AX, KISER 
MOV     SUM, AX

PURGE (Remove Macro Definition)

The PURGE directive deletes the definition of a specified macro entry, letting you reuse space.

Syntax

PURGE Macro-Name [, ...]

Remarks

It is not necessary to purge a macro before redefining it. You may use PURGE to recover memory during assembly by deleting the contents of unreferenced macros. An Out of Memory condition can occur if a large, general-purpose macro library is included.

Example

The directive:

PURGE     MACRONAME

performs the same function as redefining the macro with no contents, as in:

MACRONAME MACRO
          ENDM

In the following example, assume that MAC1 is a macro included in MACRO.LIB:

INCLUDE   MACRO.LIB
PURGE     MAC1
MAC1      ; Calls the purged macro
          ; but produces nothing

REPEAT/REPT (Iterative Macro Expansion Using a Count Expression)

REPEAT specifies the number of times to generate the statements inside the macro.

Syntax

REPEAT Expression
 Statements
ENDM

Remarks

The Expression field must evaluate to an Absolute-ExpressionType (it cannot contain forward references). Because the repeat block will be expanded at assembler time, the number of iterations must be known then.

ECHO Directive (Display Message on Standard Output Device)

The ECHO directive displays progress through a long assembly or displays the value of conditional assembly parameters.

Syntax

ECHO Text

Remarks

The assembler lists the Text entry on the standard output device during assembly when the assembler encounters the ECHO directive.

ECHO is not available under MASM 5.10 emulation; you must use %OUT, which is the obsolete spelling for the ECHO directive.

Example

Example 1:

IF IBM
  ECHO IBM VERSION
ENDIF 

IF2
  ECHO STARTING SECOND PASS
   .
   .
   .
  ENDIF

Example 2:

INNER   MACRO    TEXT, VAL
        ECHO     TEXT  VAL 
        ENDM
        .
        .
        .
HERE    =  $ - CSEG 
        INNER <CURRENT LOCATION>,%HERE 

INCLUDE Directive (Insert File Contents into Input Stream)

The INCLUDE directive "stacks" the current source file and begins reading tokens from the source file given by the FileName argument. If you use the INCLUDE directive, you need not repeat a sequence of statements that are common to several source files.

Syntax

INCLUDE FileName

Remarks

The assembler uses the following search order when attempting to open the INCLUDE file:

1. If the FileName argument contains a fully qualified path name (one that begins with a back slash or forward slash), then the assembler attempts to open the file exactly as specified, and no other search is performed if the file is not found.
2. If the FileName begins with a relative path name or contains no path information, the assembler begins searching for the INCLUDE file by looking in the directory of the source file that issued the INCLUDE directive.
3. The assembler searches for FileName in the list of directories given by any #-Fdi or #-I options found on the command line.
4. The assembler searches for FileName in the list of directories given by the <BaseEXE>_INCLUDE environment variable.
5. The assembler searches for FileName in the list of directories given by the INCLUDE environment variable.
6. Lastly, the assembler searches for FileName in the current directory. If the named file is not found, the assembler issues a fatal error message and the assembler is ended.

In no case does the assembler strip relative path information from the FileName when performing search steps 2 through 6.

When the file named in the INCLUDE directive is located, the assembler opens it and assembles all of the statements contained therein until the end of the file is reached. The file is then closed and assembler resumes in the original module at the line following the INCLUDE directive.

An INCLUDE file should not contain an #END assembler directive to denote the end of the included module; the assembler closes the included module when its physical end of file is reached.

INCLUDE files may be nested to any reasonable level, and is limited only by the operating system's ability to provide the necessary resources.

Example

INCLUDE OS2.INC

COMMENT Directive (Program Information Block)

COMMENT lets you enter comments about your program without having to enter semicolons (;) for each line.

Syntax

COMMENT   Delimiter   Text   Delimiter

Remarks

The first non-blank character after COMMENT is the first delimiter. The COMMENT directive causes the assembler to treat all Text between Delimiter and Delimiter as a comment. The text must not contain the delimiter character. This directive is used for multiple-line comments. A COMMENT defined in the body of a macro does not appear unless .LALL is requested.

Example

COMMENT *You can enter as many lines
of text between the delimiters
   .
   .
   .
as you need to describe your program.*

• Assembler Directives
• Processor Reference

• Assembler Messages

Return Codes

When ALP completes, it passes a return code back to the program that invoked it. This return code shows whether ALP completed successfully or with an error. The return codes are:

• 0 Normal program completion.
• 1 User-specified file not found.
• 2 Unexpected system error.
• 3 Terminated by user or operating system.
• 4 Syntax errors in input file.
• 5 Command line usage error.
• 6 Internal sanity check failure.
• 7 Error accessing ALP messages file.

Notices

October 1997

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS". WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM authorized reseller or IBM marketing representative. (C) Copyright International Business Machines Corporation 1995-1997. All rights reserved. Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

The #Processor Reference portion of this manual contains information reprinted with permission from Intel Corporation.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood NY 10594, U.S.A.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries:

IBM

Operating System/2

OS/2

Presentation Manager

The following terms are trademarks of other companies:

Microsoft - Microsoft Corporation

Pentium - Intel Corporation Pentium Pro - Intel Corporation

UNIX - UNIX System Laboratories, Inc.