1
Topic:  CPU Type Equate

  Syntax:   @Cpu

  Description:

     Predefined equate returning the type of processor selected by the
     previous processor directive (8086 is the default). Bits are set
     for each group of instructions supported by the processor. For
     example, when the .286 and .287 directives are in effect, bits 0,
     1, 2, 8, and 10 will be set.

     The .486 directive sets bits in @Cpu as if the .387 directive were
     used.

       15                          8    7                           0
     ┌───┬───┬───┬───┬───┬───┬───┬───┐┌───┬───┬───┬───┬───┬───┬───┬───┐
     │   │   │   │   │387│287│   │87 ││Prv│   │   │486│386│286│186│86 │
     │   │   │   │   │   │   │   │   ││   │   │   │   │   │   │188│88 │
     └───┴───┴───┴───┴───┴───┴───┴───┘└───┴───┴───┴───┴───┴───┴───┴───┘

     Bit     Processor Compatibility

      0      8086/8088
      1      80186/80188
      2      80286
      3      80386
      4      80486
      7      Privileged instructions enabled
      8      8087
     10      80287
     11      80387

     All other bits are reserved, and their values are undefined.
                                    --

Topic:  Code Segment Text Macro

  Syntax:   @code

  Description:

     Text macro representing the segment name defined by .CODE. Can be
     used in ASSUME statements or any place a segment name would be
     valid. Under the TINY memory model, @code expands to DGROUP.
                                    --

Topic:  Code Size Equate

  Syntax:   @CodeSize

  Description:

     Predefined equate giving a value of 0 for tiny, small, compact, and
     flat models, or 1 for medium, large, and huge models. The .MODEL
     directive must precede references to this equate. Useful in
     conditional assembly.
                                    --

Topic:  Current Segment Name Macro

  Syntax:   @CurSeg

  Description:

     Text macro returning the name of the current segment. Useful for
     ASSUME statements and segment overrides (especially inside
     macros), as well as for ending the current segment when mixing
     simplified and full segments. @CurSeg allows you to terminate
     segments started in include files so that the segment will close
     before the next include. Returns <> (blank) when not in a segment.
                                    --

Topic:  Pointer to DATA/DATA?/CONST/STACK

  Syntax:   @data

  Description:

     Predefined equate representing DGROUP, which contains all near
     data segments that are defined by the .DATA, .DATA?, .CONST, and
     .STACK directives. To access data in any of these segments, DS
     must contain the value @data (under DOS, the .STARTUP directive
     automatically initializes DS). This equate can be used with the
     ASSUME directive or other directives that require segment names.

     The .MODEL directive must precede this equate.
                                    --

Topic:  Data Size Equate

  Syntax:   @DataSize

  Description:

     Predefined equate giving a value of 0 for tiny, small, medium, and
     flat models, 1 for compact and large models, and 2 for huge model.
     This equate is often used in conditional assembly blocks.

     The .MODEL directive must precede this directive.
                                    --

Topic:  Current Date and Time Text Macros

  Syntax:   @Date

            @Time

  Description:

     @Date is a text macro returning the system date at the time of
     assembly in mm/dd/yy format. The @Time text macro returns the system
     time at assembly in hh:mm:ss 24-hour format. These macros are useful
     for time-stamping assembler output.
                                    --

Topic:  Environment Variable Macro

  Syntax:   @Environ(envvar)

  Description:

     Returns the value of environment variable <envvar>. Returns a
     blank if <envvar> is not defined.
                                    --

Topic:  Far Data Location Macro

  Syntax:   @fardata

            @fardata?

  Description:

     Predefined text macro returning the name of the segment defined by
     the last .FARDATA or .FARDATA? directive. This macro normally
     equals FAR_DATA or FAR_BSS.
                                    --

Topic:  Current Source Filename Macros

  Syntax:   @FileCur

            @FileName

  Description:

     @FileCur is a text macro returning the name of the current source
     or include file, including any necessary relative or absolute path.
     The @FileName text macro returns the base name of the current
     assembly file; if in an include file, it returns the name of the
     calling source file. This macro is useful for any situation in which
     you want a name to change whenever the name of the file or include
     file changes.
                                    --

Topic:  Current Source Filename Macro

  Syntax:   @Interface

  Description:

     Predefined equate returning a byte-size bit flag describing the
     current language and operating-system types.

       Bits 0-2          Bit 7

       000   Reserved     0   MS-DOS or Windows
       001   C            1   OS/2
       010   SYSCALL
       011   STDCALL
       100   Pascal
       101   FORTRAN
       110   Basic
       111   Reserved

     All other bits are reserved for future use, and their values are
     undefined.
                                    --

Topic:  Current Line-Number Macro

  Syntax:   @Line

  Description:

     Predefined equate returning the current line number in the module.
     If in an include file, returns the line number relative to the
     include file. If in a macro, returns the line number relative to
     the beginning of the source file. Useful for showing the line
     number of a programmer-defined error.

  Example:

     IFNDEF   Country
              .ERR       <Country code expected at line @Line>
     ENDIF
                                    --

Topic:  Model Equate

  Syntax:   @Model

  Description:

     A predefined equate that returns one of the following values,
     depending on memory model previously defined with the .MODEL
     directive:

      Value   Memory model

        1     TINY
        2     SMALL
        3     COMPACT
        4     MEDIUM
        5     LARGE
        6     HUGE
        7     FLAT

     The @Model equate is the only way of identifying the TINY and FLAT
     memory models. This equate is often used in conditional assembly
     blocks. The @Model equate is defined only after a .MODEL directive.
                                    --

Topic:  Stack Location Macro

  Syntax:   @stack

  Description:

     Predefined equate returning the name of the group containing the
     stack segment. This equate expands to DGROUP for NEARSTACK and to
     STACK for FARSTACK, as defined in a preceding .MODEL statement.
                                    --

Topic:  Assembler Version Equate

  Syntax:   @Version

  Description:

     Prefined equate returning a three-digit string giving the current
     version number of the assembler. Returns 600 for this version
     of the assembler, 520 for QuickAssembler, and 510 for MASM 5.1. It
     is undefined for MASM version 5.0 and earlier.
                                    --

Topic:  Word Size Equate

  Syntax:   @WordSize

  Description:

     Predefined equate returning the size of a word. In default 16-bit
     mode, @WordSize returns 2. On 80386/486 processors in a 32-bit
     segment (such as the FLAT model), @WordSize returns 4.

     Outside of a segment this equate returns the default word size as
     set by a processor selection directive or the OPTION SEGMENT:
     directive.
                                    --

Topic:  Align Data and Code

  Syntax:   ALIGN [number]

            EVEN

  Description:

     ALIGN aligns the next variable or instruction on an offset address
     that is a multiple of <expression>. The <number> parameter must be
     a power of 2 (1,2,4,8,...) less than or equal to the alignment of
     the current segment. If <number> is omitted, the alignment is
     determined by the align field of the preceding SEGMENT directive.

     In a segment containing no instructions, the assembler pads each
     skipped byte with nulls (00h). In a code segment, the assembler
     inserts a no-operation sequence (not necessarily NOP instructions)
     to fill the gap.

     This directive is useful for optimizing data and instruction
     fetches on processors with 16- or 32-bit data paths.

     EVEN is a synonym for ALIGN 2.
                                    --

Topic:  Define Segment Ordering

  Syntax:  .SEQ

           .DOSSEG

           .ALPHA

  Description:

     The .SEQ directive outputs segments to the object file in the same
     order they appear in the source code. The .ALPHA directive outputs
     segments to the object file in alphabetical order by segment name.
     The .DOSSEG directive orders segments according to the standard
     DOS convention used by other Microsoft languages:

        ■ CODE segments
        ■ Other non-DGROUP segments
        ■ DGROUP segments
             ■ Segments not in BSS or STACK
             ■ BSS class segments
             ■ STACK class segments

     When other Microsoft languages are linked with MASM modules, the
     linker automatically uses the .DOSSEG ordering.

     The .SEQ directive is in effect by default.

     The .DOSSEG directive also causes the linker to generate two
     special symbols, _end and _edata. Do not use these names for your
     own symbols.
                                    --

Topic:  Register Assumptions

  Syntax:   ASSUME segregister:seglocation [, segregister:seglocation]...

            ASSUME dataregister:qualifiedtype
            [, dataregister:qualifiedtype]...

            ASSUME register:ERROR [, register:ERROR]...

            ASSUME [register:]NOTHING [, register:NOTHING]...

  Description:

     A general-purpose directive that allows the assembler to
     determine offsets, select the correct segment register, and verify
     certain register use assumptions at assembly.

     The "ASSUME segregister:seglocation" syntax is used to inform the
     assembler of the current value of <segregister>. The assembler
     uses this information to calculate offsets correctly and to guard
     against segment selection errors. This directive does not generate
     code to change the value of <segregister>. The ASSUME directive is
     not necessary for the CS register, since CS is assumed to the
     current segment or group automatically. The <seglocation> can be any
     segment or group name, or an equivalent expression.

     The "ASSUME dataregister:type" syntax informs the assembler that
     <dataregister> is subject to the constraints of <type>. If an
     assumed register is used incorrectly, the assembler generates an
     error. The <type> parameter must be the same size as
     <dataregister>.

       ASSUME   bx:WORD
       mov      ax, [bx]        ;Error--cannot dereference non-pointer
       ASSUME   bx:PTR WORD
       mov      [bx], 10h       ;Assumes operand size is WORD
       mov      [bx], al        ;Error--cannot move byte into word memory
       ASSUME   al:WORD         ;Error--al is only byte-sized
       ASSUME   bx:BYTE         ;Error--bx is word-sized

     The "ASSUME register:ERROR" syntax causes the assembler to
     generate an error if <register> is later used explictly or
     implicitly. The OPATTR, .TYPE, and TYPE directives do not cause
     errors when referring to registers assumed to ERROR.

     The "ASSUME register:NOTHING" syntax causes the assembler to
     remove all assumptions about <register>. ASSUME NOTHING removes
     all assumptions about all registers.

     Use an ASSUME statement each time you load a known value into a
     segment register. Although not required, the ASSUME directive
     helps the assembler safeguard against segment selection errors and
     determine offsets. You may need to use instructions to initialize
     segment registers properly at run time.

     If you use the ASSUME directive to set assumptions about a data
     register, it will override any assumptions for its subregisters.
     For example, ASSUME EDX:DGROUP will override assumptions for DL,
     DH, and DX.

     Parameter      Description

     segregister    CS, DS, ES, FS, GS, or SS. The assembler
                    automatically maintains assumptions for the CS
                    segment register.

     seglocation    A segment address, another segment register, a
                    group, or FLAT. You can find the segment address
                    of a label by using the SEG operator. FLAT is
                    the label of the single FLAT segment.

     dataregister   Any byte, word, or 32-bit register.

     qualifiedtype  Any qualified type that will fit in
                    <dataregister>.

     register       Any segment or data register.
                                    --

Topic:  Concatenate Strings

  Syntax:   @CatStr(string[, string...])

            name CATSTR [textitem[, textitem...]]

  Description:

     The @CatStr macro function concatenates one or more text items.
     The result can be used anywhere a text item is appropriate. The
     @CatStr function will not expand macros or expressions unless
     you use the expression operator (%).

     The CATSTR directive concatenates strings and assigns the result
     to <name>. These two lines are equivalent:

          language   TEXTEQU  @CatStr (<Quick>, <Pascal>)
          language   CATSTR   <Quick>, <Pascal>

     The <name> is a unique symbolic name, <string> is a text string,
     and <textitem> is a text item.
                                    --

Topic:  Start Code Segment

  Syntax:   .CODE [name]

  Description:

     Starts a code segment (with segment name <name>, if given)
     and ends the previous segment, if any. Aligns the segment on a
     2-byte boundary (.8086, .186, .286) or a 4-byte boundary (.386,
     .486). The .MODEL directive must precede this directive.

     Segment name <name> is an optional parameter that overrides the
     default segment name. If <name> is not specified, the assembler
     generates a segment called _TEXT (tiny, small, compact, and flat
     models) or <modulename>_TEXT (medium, large, and huge models).
                                    --

Topic:  Create Communal Variables

  Syntax:   COMM [langtype] [NEAR│FAR] label:type[:count]
            [,[langtype] [[NEAR│FAR] label:type[:count]]...

  Description:

     Creates one or more communal variables. Communal variables are
     uninitialized, public, and allocated by the linker. The assembler
     has no control over the order, position, or initial value of
     communal variables. Communal variables are usually declared in
     include files. Use EXTERNDEF to include data variables from other
     languages.

     Parameter      Description

     NEAR│FAR       Communal variable distance. PROC is interpreted
                    as NEAR or FAR depending on the memory model
                    chosen.

     langtype       Any language type. Determines how the linker
                    outputs variable names.

     label          Name of the variable.

     type           Type specifier (BYTE, WORD, etc.), constant, or
                    structure name.

     count          Specifies the number of data objects in an array
                    (1 is the default).
                                    --

Topic:  Multiline Comments

  Syntax:   COMMENT delimiter [text]
              [text]
            [text] delimiter [text]

  Description:

     Ignores all text between delimiters or on the same line as a
     delimiter. The two comment delimiters can be on the same or
     different physical lines.

     In the following code segment, the text inside the asterisks and
     the MOV instruction are ignored:

          COMMENT *  This text is ignored
          by the assembler *  mov    ax, 10h

     Parameter      Description

     delimiter      First nonblank character following the COMMENT
                    directive

     text           All text up to and including the line containing
                    the next occurrence of the delimiter.
                                    --

Topic:  Start a Constant Data Block

  Syntax:   .CONST

  Description:

     Starts a constant data segment (called CONST in DGROUP) and ends
     the previous segment, if any. For consistency with other
     languages, this segment should contain all strings, real numbers,
     and other constant data accessed by a high-level language. The
     CONST segment has the READONLY attribute.

     The .MODEL directive must precede this directive.
                                    --

Topic:  Turn On/Off Symbol Cross-Referencing

  Syntax:   .CREF

            .NOCREF [name[, name]...]

  Description:

     The .CREF directive enables collection of information for all
     symbols. These symbols will appear in the symbol table at the end
     of a listing file. If you generate a source-browser file with the
     /FR or /Fr command-line option, the browser will be able to access
     cross-reference information for these symbols. This directive is
     in effect by default.

     The .NOCREF directive turns off cross-referencing for all symbols.
     Any references to symbols while .NOCREF is in effect are omitted
     from the cross-reference listing. If the <name> parameter is given
     with this directive, only the cross-reference information for the
     symbols specified by <name> is omitted.

     .XCREF is a synonym for .NOCREF and is provided for compatibility
     with previous versions of the assembler.
                                    --

Topic:  Start a Data Segment

  Syntax:   .DATA

            .DATA?

  Description:

     The .DATA directive starts the initialized data segment (with
     segment name _DATA) and ends the previous segment, if any. The
     .DATA segment should contain all global data that have initial
     values.

     The .DATA? directive starts the uninitialized data segment (with
     segment name _BSS) and ends the previous segment, if any. Place all
     uninitialized data in the .DATA? segment.

     Although uninitialized data can be placed in the .DATA segment by
     declaring data with the ? operator, use the .DATA? directive to
     minimize the size of the .EXE file and to maximize compatibility
     with other languages.

     The .MODEL directive must precede these directives. It generates a
     GROUP statement that places _DATA and _BSS in DGROUP.
                                    --

Topic:  Declare Variables

  Syntax:   [name] [S]BYTE initializer [, initializer]...

            [name] [S]WORD initializer [, initializer]...

            [name] [S]DWORD initializer [, initializer]...

            [name] FWORD initializer [, initializer]...

            [name] QWORD initializer [, initializer]...

            [name] TBYTE initializer [, initializer]...

            [name] REAL4 initializer [, initializer]...

            [name] REAL8 initializer [, initializer]...

            [name] REAL10 initializer [, initializer]...

  Description:

                            Integer
    Type    Abbr  Size      Range        Types Allowed
  ┌───────┬─────┬─────────┬────────────┬──────────────────────────────────┐
  │ BYTE  │ DB  │ 1 byte  │ -128 to    │ Character, String                │
  │       │     │         │ +255       │                                  │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ WORD  │ DW  │ 2 bytes │ -32,768 to │ 16-bit near ptr, 2 characters,   │
  │       │     │         │ +65,535    │ double-byte character            │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ DWORD │ DD  │ 4 bytes │ -2Gig to   │ 16-bit far ptr, 32-bit near ptr, │
  │       │     │         │ +4Gig-1    │ 32-bit long word                 │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ FWORD │ DF  │ 6 bytes │    ──      │ 32-bit far pointer               │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ QWORD │ DQ  │ 8 bytes │    ──      │ 64-bit long word                 │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ TBYTE │ DT  │10 bytes │    ──      │ BCD, 10-byte binary numbers      │
  └───────┴─────┴─────────┴────────────┴──────────────────────────────────┘
  ┌───────┬─────┬─────────┬────────────┬──────────────────────────────────┐
  │ REAL4 │ DD  │ 4 bytes │    ──      │ Single-precision floating point  │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ REAL8 │ DQ  │ 8 bytes │    ──      │ Double-precision floating point  │
  ├───────┼─────┼─────────┼────────────┼──────────────────────────────────┤
  │ REAL10│ DT  │10 bytes │    ──      │ 10-byte floating point           │
  └───────┴─────┴─────────┴────────────┴──────────────────────────────────┘

     These directives allocate and optionally initialize one or
     more bytes of global data. The S prefix indicates signed data,
     but this information is used internally by the assembler for
     comparisons used by control-flow directives and
     argument passing in INVOKE statements. CodeView also uses this
     information to specify the data format.

     The abbreviations (such as DB, DD) are limited forms of the
     data-declaration directives; they cannot be used as types. They
     are included for compatibility with previous versions of the
     assembler.

     String initializers, available with the BYTE directive, allocate
     a byte for each character of the string. The characters are stored
     with the leftmost character in the lowest memory location so that

          BYTE   "WASHINGTON"

     would be assembled to

          57 41 53 48 49 4E 47 54 4F 4E    "WASHINGTON"

     Character initializers, however, are stored with the leftmost
     character in the highest memory location. They are also limited
     to the current expression size so that under the default
     OPTION EXPR32

          DWORD        "WASH"

     would be assembled to

          48 53 41 57  "HSAW"

     and under OPTION EXPR16

          WORD         "WA"

     would be assembled to

          41 57        "AW"

     Use the REAL4, REAL8, and REAL10 data types for floating-point
     data. They inform CodeView that the data is in floating-point
     format and cause the assembler to perform more stringent type
     checking.

     Parameter    Description

     name         Symbol name assigned to the variable. If no name is
                  assigned, the memory space is allocated, but the
                  starting address of the variable has no symbolic
                  name.

     initializer  A type shown in the table above, constant integer
                  expression, ?, or DUP expression. Separate multiple
                  values with commas or use the DUP operator.
                                    --

Topic:  Display Message during Assembly

  Syntax:   ECHO message

  Description:

     Displays message during assembly. The message is usually output to
     the screen, but you can redirect it to a file or another device.
     This directive can help show which statements were assembled. %OUT
     is a synonym for ECHO and is included for compatibility.

     The <message> is any line of ASCII characters up to but not
     including any comment on the line. If angle brackets are used to
     enclose <message>, the angle brackets are not displayed. To perform
     macro substitution, put the macro substitution operator (%) at the
     beginning of the line. Use a separate ECHO directive for each line.

     To output the time and date of assembly, insert this line in your
     source code:

        % ECHO       Assembled on @Date at @Time
                                    --

Topic:  End Source File

  Syntax:   END [address]

  Description:

     Marks the end of a source file and optionally indicates the
     program load address. The optional <address> is a label or
     expression identifying where program execution begins. You can
     define <address> only once in a program, usually in the main
     module.

     You cannot specify <address> if you have used the .STARTUP
     directive, which automatically sets a start address. If you are
     linking with a high-level language, the start address is
     typically set by that language's compiler.

     END also closes the last segment in the source file.
                                    --

Topic:  End Macro and Iterative Blocks

  Syntax:   ENDM

  Description:

     Terminates macro and iterative blocks.
                                    --

Topic:  End Segment and Structure Blocks

  Syntax:   name ENDS

  Description:

     Marks the end of a segment or a structure definition previously
     started with SEGMENT, STRUCT, or UNION. To end a simplified segment
     (such as one started with .DATA), use the line

          @CurSeg   ENDS          ;End current segment

     A single .STACK statement opens and closes the stack segment,
     so you should not include an additional ENDS statement.
                                    --

Topic:  Numeric and String Equate

  Syntax:   name EQU expression

            name EQU <text>

            name TEXTEQU textmacro

            name TEXTEQU %expression

  Description:

     The EQU directive assigns <expression> or <text> to <name>. Angle
     brackets indicate that <text> should not be evaluated as an
     expression.

     EQU evaluates the numeric value of <expression> and assigns
     the resulting constant value to <name>. Unlike =, EQU does not
     allow numeric equates to be redefined. If <expression> cannot be
     evaluated, EQU treats <expression> as text.

     The TEXTEQU directive acts like the EQU directive with text
     equates but performs macro substitution at assembly and does not
     require angle brackets. The TEXTEQU directive will also resolve
     the value of an expression preceded by a percent sign (%). The EQU
     directive does not perform macro substitution or expression
     evaluation for strings.

     Text equates are limited to 255 characters. Text equates can be
     redefined to another value but not to a different type of symbol.

     Parameter      Description

     name           Symbolic name for <expression> or <text>

     expression     Variable or constant numeric expression (not a
                    memory expression)

     text           String enclosed in angle brackets (<>)

     textmacro      A text macro (such as @Date) or a string enclosed in
                    angle brackets (<>).

     expression     An expression preceded by a %.

  Example:

       MASM    EQU      5.1 + 0.9        ;Evaluates to 6.0
       Msft    EQU      <Microsoft>      ;String equate
       libpath TEXTEQU  @Environ(<LIB>)  ;Text Macro Equate
       endstr  TEXTEQU  %(endadr-staradr);String equate to numeric value
                                    --

Topic:  Generate Severe Error

  Syntax:   .ERR [message]

  Description:

     Generates an A2052 error message when assembled. Generally, this
     directive occurs in a conditional-assembly block and is used to
     indicate some error condition discovered at assembly time.
     This directive can be useful for verifying that the program
     assembled correctly and that user-defined bounds were not exceeded.

     If <message> is given, it will be displayed with the standard
     assembler error messages. The <message> parameter is any text item
                                    --

Topic:  Generate Error for Missing Argument

  Syntax:   .ERRB <textitem> [,message]

            .ERRNB <textitem> [,message]

  Description:

     The .ERRB directive generates an A2057 error if <textitem> is
     blank. The .ERRNB directive generates an A2058 error if <textitem>
     is not blank.

     These directives are usually used within macro definitions; a
     macro parameter is replaced by an empty string if you call the
     macro and do not give a corresponding argument. These directives
     let you write macros that generate an assembly-time error if the
     wrong number of arguments is used in the macro call. However, the
     :REQ parameter attribute or the variable argument feature often
     provides the same functionality in a more straightforward way.

     Parameter      Description

     textitem       Item to be tested, any text item.

     message        Programmer-supplied error message, any text item.
                                    --

Topic:  Generate Error for Undefined Symbol

  Syntax:   .ERRDEF name [,message]

            .ERRNDEF name [,message]

  Description:

     The .ERRDEF directive generates an A2056 error message if <name>
     is a previously defined symbol. The .ERRNDEF directive generates
     an A2055 error message if <name> has not been previously
     defined.

     One of the most common uses of the .ERRNDEF directive is to ensure
     that a symbol has been defined before you attempt to use it. This
     situation can occur if the source code depends on the command-line
     /D option to define a symbol.

     If <message> is given, it will be displayed with the standard
     assembler error messages. The <message> parameter is any text item.
                                    --

Topic:  Generate Error If Arguments Are Same/Different

  Syntax:   .ERRDIF[I] <textitem1>, <textitem2> [,message]

            .ERRIDN[I] <textitem1>, <textitem2> [,message]

  Description:

     The .ERRDIF directive generates an A2060 error if <textitem1> and
     <textitem2> are different. .ERRIDN generates an A2059 error if the
     arguments are identical. These directives are commonly used inside
     macros to test for bad values passed as parameters. The .ERRDIFI
     and .ERRIDNI directives act the same as the .ERRDIF and .ERRIDN
     directives but perform case-insensitive comparisons.

     The <textitem1> and <textitem2> parameters are text items.

     If <message> is given, it will be displayed with the standard
     assembler error messages. The <message> parameter is any text item.
                                    --

Topic:  Generate Error If Argument Is Zero/Nonzero

  Syntax:   .ERRE expression [,message]

            .ERRNZ expression [,message]

  Description:

     Tests value of <expression> and generates an error depending on
     the resulting value. The .ERRE directive generates an A2053 error
     if <expression> evaluates to false (zero). .ERRNZ generates an
     A2054 error if <expression> evaluates to true (nonzero). If
     <message> is given, it will be displayed with the standard
     assembler error message.

     Parameter      Description

     expression     Expression that evaluates to true, false, or a
                    numeric constant. The expression cannot contain
                    forward references.

     message        Programmer-supplied error message, any text item.
                                    --

Topic:  End Macro and Repeat Blocks

  Syntax:   EXITM [textitem]

  Description:

     Terminates expansion of the current macro or repeat block and
     begins assembly of the next statement outside the block. If the
     EXITM directive is encountered in a nested macro block, the
     assembler returns to expanding the previous block level.

     The <textitem> parameter is a text item that is returned to the
     calling statement. The <textitem> field is valid only with an
     EXITM directive at the end of a MACRO block.
                                    --

Topic:  Define External Variables, Labels, and Symbols

  Syntax:   EXTERNDEF [langtype] name:qualifiedtype
            [, [langtype] name:qualifiedtype]...

            EXTERN [langtype] name[(altID)]:qualifiedtype
            [, [langtype] name[(altID)]:qualifiedtype]...

  Description:

     The EXTERNDEF directive tells the assembler that one or more
     variables, symbols, data structures, or labels are defined in
     other modules. The behavior of the EXTERNDEF directive is
     determined by its context:

        ■ If <name> is used in the current module but is not defined,
          <name> is made external.
        ■ If <name> is defined in the current module, it is made
          PUBLIC.
        ■ If <name> is neither used nor defined, the directive is
          ignored.

     The EXTERNDEF directive allows you to put global data declarations
     in an include file without forcing the linker to pull in unneeded
     modules. Usually, you define <name> in one module and put the
     EXTERNDEF directive in a file that is included in all program
     modules. The PROTO directive automatically generates an EXTERNDEF
     for its related procedure.

     EXTERN is a less flexible version of EXTERNDEF. It declares
     <name> as external whether or not it is used in the module.
     EXTRN is a synonym for EXTERN and is included for compatibility
     with previous versions of the assembler.

     With the EXTERN directive, <name> can be followed by (altID),
     which allows the linker to select an alternate resolution for
     <name>. This is useful when creating library files.

     Parameter     Description

     langtype      A language type appropriate to <name>.

     name          A unique global symbolic name. Case mapping is
                   overridden by OPTION CASEMAP.

     qualifiedtype The qualified type to be given to <name>. Can
                   also be ABS, which causes <name> to be imported
                   as a constant. Does not have to match type given
                   to <name> in original definition.

     altID         A unique global symbolic name to use as an alternate
                   for <name>. Must be of the same type as <name>. The
                   <altID> parameter cannot be declared as a <name>
                   with an altID in an EXTERN statement in this or any
                   other module.
                                    --

Topic:  Start a Far Data Segment

  Syntax:   .FARDATA [name]

            .FARDATA? [name]

  Description:

     The .FARDATA directive starts a far data segment for initialized
     data (segment name FAR_DATA or <name>, if given), ending any
     previous segment. The .FARDATA? directive starts a far data
     segment for uninitialized data (segment name FAR_BSS or
     <segmentname>, if given), ending any previous segment.

     Data in segments defined with .FARDATA and .FARDATA? are not
     placed in a group or combined with far data segments for other
     source modules. Using <name> allows you to create multiple far
     data segments in one source module. The .MODEL directive must
     precede these directives.

     Putting uninitialized arrays and buffers into a segment created
     by .FARDATA? rather than .FARDATA can decrease the size of object
     files and libraries.

     Normally, you cannot access far data segments by name, because
     there may be multiple PRIVATE segments with the same name. Use
     SEG expressions instead.
                                    --

Topic:  Iterative Macro

  Syntax:   FOR parameter[:REQ│:=default], <argument [,argument]...>
              statements
            ENDM

  Description:

     Repeats <statements> once for each argument specified. The current
     argument replaces <parameter> in each iteration. IRP is a synonym
     for FOR and is included for compatibility with previous versions
     of the assembler.

     Parameter      Description

     parameter      A valid symbol name. If parameter appears in
                    statements, it is replaced by a different argument
                    in each iteration.

     :REQ           Optional tag for <parameter> causing an assembler
                    error if <parameter> is given a blank argument.

     :=default      Optional tag for <parameter> causing <parameter> to
                    be assigned <default> if given a blank argument.

     argument       Text, symbol, string, or numeric constant. Separate
                    multiple iterations with commas. Angle brackets are
                    required if a string <argument> includes spaces or
                    commas. Leading spaces of string arguments are
                    ignored.

     statements     Any valid assembler statements.
                                    --

Topic:  Iterative Macro (for Character)

  Syntax:   FORC parameter, <string>
              statements
            ENDM

  Description:

     Repeats <statements> once for each character in the string. The
     character replaces <parameter> in each repetition. IRPC is a synonym
     for FORC and is included for compatibility with previous versions
     of the assembler.

     Parameter      Description

     parameter      A valid symbol name. If <parameter> appears in
                    statements, then it is replaced by a different
                    character each iteration.

     string         A literal string or a symbol defined with a string
                    equate. All spaces are counted as characters. Angle
                    brackets are required.

     statements     Any valid assembler statements.
                                    --

Topic:  Skip to Label

  Syntax:   GOTO macrolabel

  Description:

     Causes assembler to skip to <macrolabel>. The GOTO directive is
     only allowed inside a MACRO, FOR, FORC, REPEAT, or WHILE block.
     The <macrolabel> is only visible within the block.

  Example:

     MACRO     Instruments
               IFNDEF    Cymbal
                         GOTO     Crash
               ENDIF
               ¨
               ¨
               ¨
               :Crash
                         .ERR     <Undefined symbol.>
               ¨
               ¨
               ¨
     ENDM
                                    --

Topic:  Combine Segments

  Syntax:   name GROUP segment [,segment]...

  Description:

     Adds the <segment> parameters to a group called <name>. Creates
     group <name> if it does not exist. This causes the linker to
     combine the given logical segments into one physical segment, so
     that the logical segments share a common physical segment address.
     Under the FLAT memory model, all segments are automatically
     assigned to a common group called FLAT.

     All logical segments in a group must have the same WordSize
     attribute. If they are 16-bit segments, their total size cannot
     exceed 64K bytes. If they are 32-bit segments (allowed on
     80386/486 processors), groups can be up to 4 gigabytes.

     The <name> is a unique symbolic name or previously defined group.
     If the same group name appears in more than one GROUP statement,
     the effect is cumulative; the new segments are added to the group.
     The <segment> is a segment name defined with the SEGMENT directive.
                                    --

Topic:  IF Block Syntax

  Syntax:   IFcond expression
              ifstatements
            [ELSEIFcond expression
              elseifstatements]
              ¨
              ¨
              ¨
            [ELSE
              elsestatements]
            ENDIF

  Description:

     The IF block format can be used to create a source file that will
     generate a variety of programs, depending on constants or
     environment variables. For example, you can create a single source
     file that generates code for different memory models and operating
     environments. IF blocks can be nested up to 20 levels but cannot
     span include files or structure, union, or macro definitions.

     The statements following the ELSE directive are assembled only if
     the preceding IF directive was found to be false (zero). Only one
     ELSE statement is allowed in each IF block, although there can be
     several ELSEIF statements.

     IFcond is one of the conditional assembly directives beginning
     with "IF" (such as IF, IFE, and IFB). There is an optional
     ELSEIFcond corresponding to each IFcond.

     The <ifstatements>, <elseifstatements>, and <elsestatements> are
     each a series of one or more assembly-code statements. The
     respective conditions determine which block is assembled, if any.
     The ELSE and ELSEIF blocks are optional.
                                    --

Topic:  IF/IFE/ELSEIF/ELSEIFE Directives

  Syntax:   [ELSE]IF expression

            [ELSE]IFE expression

  Description:

     IF causes assembly of a block of statements if expression is true
     (nonzero). IFE causes assembly of a block of statements if
     expression is false (zero).

     The <expression> must resolve to a constant and contain no forward
     references.
                                    --

Topic:  IFB/IFNB/ELSEIFB/ELSEIFNB Directives

  Syntax:   [ELSE]IFB expression

            [ELSE]IFNB expression

  Description:

     IFB causes assembly of a block of statements if <expression> is
     blank. IFNB causes assembly of a block of statements if <expression>
     is not blank. The <expression> field is any name, number, or
     expression; typically, it is the name of a parameter of a macro.

     Within a macro, a parameter name is replaced by an empty string if
     you call the macro without giving a corresponding argument. IFB
     and IFNB let you define default behavior when an argument is
     missing, but the :REQ and :=default MACRO parameters are preferred.
                                    --

Topic:  IFDEF/IFNDEF/ELSEIFDEF/ELSEIFNDEF Directives

  Syntax:   [ELSE]IFDEF name

            [ELSE]IFNDEF name

  Description:

     IFDEF causes assembly of a block of statements if <name> is a
     previously defined symbol. IFNDEF causes assembly of a block of
     statements if name has not been defined.

     Use of this feature with the IFDEF and IFNDEF directives lets you
     control which statements are assembled from the command line.
                                    --

Topic:  IFDIF/ELSEIFDIF Variations

  Syntax:   [ELSE]IFDIF[I] textitem1, textitem2

            [ELSE]IFIDN[I] textitem1, textitem2

  Description:

     Causes assembly of a block of statements depending on whether two
     textitems are different or identical. IFDIF assembles the block if
     <textitem1> and <textitem2> are different. IFIDN assembles the block
     if they are the same. IFDIFI and IFIDNI do the same actions but are
     not case sensitive.

     The <textitem1> and <textitem2> parameters are text items.
                                    --

Topic:  Insert Source Code

  Syntax:   INCLUDE filename

            INCLUDE <filename>

  Description:

     Inserts source code from <filename> into the current source file
     during assembly. If <filename> does not include a fully-specified
     path, the assembler searches the directory of the current file,
     the /I command-line include path, and then the INCLUDE environment
     variable. Nested INCLUDE directives are allowed.

     The <filename> parameter is an existing file containing valid
     assembly-language statements and directives. No default file
     extension is assumed. Angle brackets are required if the filename
     or path includes a backslash, semicolon, greater-than, less-than,
     single quotation marks, or double quotation marks.
                                    --

Topic:  Link with LIB File

  Syntax:   INCLUDELIB libraryname

            INCLUDELIB <libraryname>

  Description:

     Informs the linker that the current module should be linked with
     the <libraryname>. If <path> is not given, the linker searches the
     current working directory, directories given in the ML or LINK
     library field, and then the LIB environment variable from the
     TOOLS.INI file.

     A common use of INCLUDELIB is to specify OS2.LIB, which is
     required for all system calls under OS/2.

     The <libraryname> parameter is an existing file containing code in
     LIB format. If no extension is specified, the default extension
     .LIB is assumed. Angle brackets are required if the libraryname
     or path includes a backslash, semicolon, greater-than, less-than,
     single quotation marks, or double quotation marks.
                                    --

Topic:  Search for String

  Syntax:   @InStr([position], string1, string2)

            name INSTR [position,] textitem1, textitem2

  Description:

     The @InStr macro function searches for the first occurrence of
     <string2> inside <string1> and returns the position of the
     first character of the match. The search begins at <position>,
     if you give that parameter. The @InStr function will not expand
     macros or expressions unless you use the expression operator (%).

     The first character is indexed as 1. @InStr returns 0 if
     <string1> is not found.

     The INSTR directive performs the same function as @InStr but
     assigns the result to <name>. These two lines are equivalent:

          develop    TEXTEQU    @InStr (2, <MikeBobMichaelJim>, <Mi>)
          develop    INSTR      2, <MikeBobMichaelJim>, <Mi>
                                ;develop is now 8

     Parameter      Description

     name           Name of the resulting constant.

     position       Starting character position of the search
                    (default 1). Must be a positive integer.

     string1        String being searched; any text.

     string2        String to search for; any text.

     textitem1      String being searched; any text item.

     textitem2      String to search for; any text item.
                                    --

Topic:  Call Stack-Based Procedures

  Syntax:   INVOKE expression [,arguments]

  Description:

     Automates the call interface to stack-based procedures. Handles all
     pushing of parameters onto the stack. Cleans up the stack when the
     procedure returns.

     The <invokelist> is passed to the procedure according to the types
     given in that procedure's prototype. If necessary, the assembler
     will generate code to convert the elements of <invokelist> to the
     types specified in the prototype.

     Parameter      Description

     expression     Expression yielding address or label of procedure
                    to be called. Must resolve to a valid address and
                    cannot include any forward references.

     arguments      Sequential list of parameters passed. Can be
                    register::register (for a register pair), expression,
                    or ADDR label. ADDR label passes the address of
                    <label> (segment and offset if DWORD, segment only
                    if WORD) to the procedure.
                                    --

Topic:  Create Label

  Syntax:   name LABEL qualifiedtype

  Description:

     Creates a new label of a given type at a specified location by
     assigning the current location-counter value and the given type to
     <name>. The <qualifiedtype> parameter determines the type of data
     or call distance for the label. This directive does not allocate
     data.

     Parameter      Description

     name           Symbol assigned to the label.

     qualifiedtype  Any qualified type.
                                    --

Topic:  List Source Statements to .LST File

  Syntax:   .LIST

  Description:

     Enables listing of all source statements to the .LST file. The
     .LST file must first be enabled with the /Fl command-line option.
     This directive is in effect by default.
                                    --

Topic:  List All Statements to .LST File

  Syntax:   .LISTALL

  Description:

     Enables listing of all statements to the .LST file. The .LST file
     must first be enabled with the /Fl command-line option. This
     directive is equivalent to the combination of the .LIST, .LISTIF,
     and .LISTMACROALL directives.
                                    --

Topic:  List Statements in Conditional Blocks

  Syntax:   .LISTIF

  Description:

     Enables listing of all statements in conditional blocks, even
     those in false blocks. This directive is in effect by default. The
     .LFCOND directive is a synonym of .LISTIF and is included for
     compatibility with previous versions of the assembler.
                                    --

Topic:  Enable Assembly Listing File

  Syntax:   .LISTMACRO

  Description:

     Enables an assembly listing file that includes macro expansion
     statements that generate code or data. Comments, equates, and
     segment definitions are not listed. This directive is in effect by
     default. The .LFCOND directive is a synonym of .LISTMACRO and is
     included for compatibility with previous versions of the
     assembler.
                                    --

Topic:  List Source Statements in Macro Expansion

  Syntax:   .LISTMACROALL

  Description:

     Enables listing of all source statements in a macro expansion,
     including normal comments but excluding macro comments. The .LALL
     directive is a synonym of .LISTMACROALL and is included for
     compatibility with previous versions of the assembler.
                                    --

Topic:  Local Variables in Procedures

  Syntax:   LOCAL name [[count]][:qualifiedtype] [, name [[count]]
            [:qualifiedtype]]...

  Description:

     Generates code to create one or more stack (automatic) variables,
     which can be accessed only within the current procedure. The
     assembler uses the same method used by high-level languages to
     create local variables.

     The <name> parameter is the name of the variable, and <count> is
     an optional expression (which must appear in square brackets)
     indicating the number of elements to allocate. The <qualifiedtype>
     parameter is any qualified type appropriate to <name>. The default
     <qualifiedtype> is WORD in a 16-bit segment and DWORD in a 32-bit
     segment.

     Once declared in a LOCAL statement, local variables can be
     referred to by name. The assembler translates references to these
     variables into references to their actual location on the stack
     using the BP indirect addressing mode.

     The assembler will generate an error if you have already defined
     <name> as a label.

  Example:

     LOCAL     array[20]:BYTE
                                    --

Topic:  Local Variables in Macros

  Syntax:   LOCAL localname [,localname]...

  Description:

     Declares a label or symbol for local use within a macro or
     iterative block. The assembler generates a different internal name
     for the symbol each time it expands the macro. The LOCAL directive
     allows you to call a macro that contains local jump statements and
     variable definitions without generating the same label each time
     the macro is expanded.

     The <localname> parameter is the name of a label or symbol inside
     the macro. Inside the macro expansion, <localname> takes precedence
     over a global label or symbol with the same name.
                                    --

Topic:  Macro Block

  Syntax:   name MACRO [parameter[:tag]] [,parameter[:tag]]...]
              [LOCAL varlist]
              statements
            ENDM [value]

  Description:

     Marks the beginning of a macro definition called <name> and takes
     optional parameters. The assembler generates the statements in the
     macro block each time the macro is called in source code. Macro
     procedures and macro functions can be nested up to 40 levels. Text
     macros may be nested up to 20 levels.

     Macro procedures can be redefined at any time. The new definition
     affects any subsequent calls to this macro. Macro functions can
     only be redefined, if they have not been called yet.

  Example:

     mymacro MACRO     value:REQ, reg:=<AX>, options:VARARG
             LOCAL     returnval
             ¨
             ¨
             ¨
             ENDM      returnval

     Parameter      Description

     name           A unique symbol name. It can appear later in source
                    code, to call the macro.

     parameter      A valid symbol name. Each parameter can appear in
                    the statements and is replaced by the corresponding
                    item in the argument list whenever the macro is
                    called.

     :tag           Either :REQ, :=default, or :VARARG. :REQ causes an
                    assembler error if the parameter is given a blank
                    argument. :=default causes <parameter> to be
                    assigned <default> if given a null argument.
                    :VARARG allows a variable number of arguments to be
                    passed as a comma-separated list to <parameter>. If
                    :VARARG is used, it must be applied only to the
                    last parameter of the MACRO directive.

     statements     Any valid assembler statements.

     value          Optional return value for macro function.
                                    --

Topic:  Initialize Memory Model

  Syntax:   .MODEL memorymodel [,langtype] [,ostype] [,stackoption]

  Description:

     Initializes the program memory model. Must be placed at the
     beginning of the source file before any other simplified segment
     directive. Generates ASSUME and GROUP statements used by the
     specified memory model. Also creates the predefined equates for
     the various simplified segments. The .MODEL directive can occur
     only once in a program.

     If you use the langtype argument with .MODEL, nested procedures
     are not allowed.

     Parameter      Description

     memorymodel    TINY, SMALL, COMPACT, MEDIUM, LARGE, HUGE, or
                    FLAT. If you are writing an assembler routine for
                    a high-level language, this option should match
                    the memory model used by the compiler or
                    interpreter. FLAT is valid only in .386 or .486
                    mode. You must use the /AT command-line option or
                    /TINY linker option to assemble tiny-model programs.

     langtype       Any language type. Instructs the assembler to
                    follow the naming, calling, and return conventions
                    for the indicated language. This affects the
                    PUBLIC, EXTERN, PROC, PROTO, and INVOKE
                    directives.

     ostype         OS_DOS or OS_OS2. Determines the behavior of the
                    .STARTUP and .EXIT commands for compatibility with
                    these operating systems. DOS is the default.

     stackoption    NEARSTACK (if SS equals DS) or FARSTACK (if SS is
                    not equal to DS). NEARSTACK is the default. The
                    stack is not part of DGROUP with the FARSTACK
                    option. This affects the code generated by the
                    .STARTUP directive.
                                    --

Topic:  Suppress Program Listing

  Syntax:   .NOLIST

  Description:

     Suppresses program listing. Use in conjunction with .LIST to
     prevent a particular section of a source file from being listed.
     The .XLIST directive is a synonym for .NOLIST and is included for
     compatibility with previous versions of the assembler.
                                    --

Topic:  Turn off List

  Syntax:   .NOLISTIF

  Description:

     Turns off the listing of the lines in subsequent conditional blocks
     whose condition is false. The .SFCOND directive is a synonym for
     .NOLISTIF and is included for compatibility with previous versions
     of the assembler.
                                    --

Topic:  Suppress Macro Listing

  Syntax:   .NOLISTMACRO

  Description:

     Suppresses listing of macro expansions in a listing file. Macro
     calls are listed, but the source code generated by the call is
     not. The .SALL directive is a synonym for .NOLISTMACRO and is
     included for compatibility with previous versions of the
     assembler.
                                    --

Topic:  Set Assembler Options

  Syntax:   OPTION optionlist

  Description:

    Modifies the behavior of certain features of the assembler. The
    <optionlist> is a list of one or more of the following options.
    Separate options with commas. These options affect the module from
    the point they are used onward and override corresponding command-line
    options:

     Option                        Default

     CASEMAP:maptype               NOTPUBLIC
     DOTNAME│NODOTNAME             NODOTNAME
     EMULATOR│NOEMULATOR           NOEMULATOR
     EPILOGUE:macroid              Depends on OS and processor type
     EXPR16│EXPR32                 Depends on processor
     LANGUAGE:langtype             -none-
     LJMP│NOLJMP                   LJMP
     M510│NOM510                   NOM510
     NOKEYWORD:<keywordlist>       -none-
     NOSIGNEXTEND                  Off
     OFFSET:offsettype             GROUP
     OLDMACROS│NOOLDMACROS         NOOLDMACROS
     OLDSTRUCTS│NOOLDSTRUCTS       NOOLDSTRUCTS
     PROC:visibility               PUBLIC
     PROLOGUE:macrofuncid          Depends on OS and processor type
     READONLY│NOREADONLY           NOREADONLY
     SCOPED│NOSCOPED               SCOPED
     SEGMENT:segmentsize           USE16
                                    --

Topic:  Maximize Compatibility with MASM 5.1

  Syntax:   OPTION M510

            OPTION NOM510

  Description:

     The M510 option sets all options to maximize compatibility with
     MASM 5.10. Enables the following:

     OLDMACROS
     OLDSTRUCTS
     DOTNAME
     CASEMAP:ALL
     EXPR16

     The M510 option enables OPTION SCOPED if a language type is specified
     in a .MODEL statement. Otherwise OPTION NOSCOPED is used.

     Using OPTION M510 also changes the default for OFFSET to GROUP if a
     .MODEL directive is in effect and to SEGMENT otherwise.

     With OPTION M510, keywords and instructions that are not available
     in the current CPU mode (such as ENTER under .8086) are not treated as
     keywords. The USE32, FLAT, FAR32, and NEAR32 segment types and the
     80386/486 registers are not keywords with processor selection
     directives less than .386.

     NOM510 is the default.
                                    --

Topic:  OLDMACROS│NOOLDMACROS Option

  Syntax:   OPTION OLDMACROS

            OPTION NOOLDMACROS

  Description:

     The OLDMACROS option enables MASM 5.1-compatible macros and
     parameter substitution. NOOLDMACROS is the default. The OLDMACROS
     option is enabled with the M510 option.
                                    --

Topic:  OLDSTRUCTS│NOOLDSTRUCTS Option

  Syntax:   OPTION OLDSTRUCTS

            OPTION NOOLDSTRUCTS

  Description:

     The OLDSTRUCTS option enables MASM 5.1-compatible scoping of
     structure members. This option causes all structure members to
     have the same scope as the structure name and prevents a label and
     a member name from having the same name. This option also causes
     the dot operator to act exactly like a plus.

     NOOLDSTRUCTS is the default. The OLDSTRUCTS option is enabled with
     the M510 option.
                                    --

Topic:  Automatic Conditional Jump Lengthening

  Syntax:   OPTION LJMP

            OPTION NOLJMP

  Description:

     The LJMP option enables automatic conditional-jump lengthening.
     LJMP is the default.

     Enabling LJMP allows the assembler to generate code that emulates
     a conditional jump of greater than -128 to +127 bytes. If the jump
     is within this range, no special code is generated. It does not
     affect unconditional jumps or the control-flow directives.

     The assembler will generate an A6003 warning for a lengthened jump
     so that you can identify it for later optimization.
                                    --

Topic:  Enable/Disable Dot Labels

  Syntax:   OPTION DOTNAME

            OPTION NODOTNAME

  Description:

     The DOTNAME option enables the use of the period (.) as the leading
     character in variable, label, macro, struct, union, and member names.
     NODOTNAME is the default. The DOTNAME option is enabled with the M510
     option, since previous versions of the assembler recognized names
     with period prefixes.

     The DOTNAME option does not have any effect on any of the reserved
     words. The use of the period in names is discouraged, as it can be
     confused with the field offset and structure operators.
                                    --

Topic:  Make Code Segment Read-Only

  Syntax:   OPTION READONLY

            OPTION NOREADONLY

  Description:

     The READONLY option sets the READONLY attribute for subsequent code
     segments. Enables checking for instructions that explicitly modify
     segments or groups containing code. Useful for detecting self-
     modifying code. NOREADONLY is the default.

     This option replaces the command-line /P option from previous
     versions of the assembler. Segments can be also be made read-
     only with the READONLY parameter of the SEGMENT directive.
                                    --

Topic:  Localize Label

  Syntax:   OPTION SCOPED

            OPTION NOSCOPED

  Description:

     The SCOPED option causes a label (defined with the "label:" syntax)
     to be local to the procedure in which it is defined. Labels defined
     with the LABEL directive or the "label::" syntax are not affected by
     this option.

     Using NOSCOPED will cause all labels to be global to the module.
     SCOPED is the default. The NOSCOPED option is enabled with the
     M510 option, since previous versions of the assembler did not have
     scoped labels.
                                    --

Topic:  Specify Default Language Type

  Syntax:   OPTION LANGUAGE:langtype

  Description:

     Specifies the default language type to be used with many
     directives. The most recent OPTION LANGUAGE: or .MODEL directive
     determines the current language type. The <langtype> parameter is
     any language type.
                                    --

Topic:  Control Case Mapping

  Syntax:   OPTION CASEMAP:maptype

  Description:

     Controls the mapping of characters to uppercase. The <maptype>
     parameter can be ALL, NONE, or NOTPUBLIC, which correspond to the
     /Cu, /Cp, and /Cx command-line options. You can use this option
     only once per source file. The current language type, if any, will
     override <maptype>.

     CASEMAP:NOTPUBLIC is the default. The CASEMAP option is set to ALL
     with the M510 option.
                                    --

Topic:  Floating-Point Code Generation

  Syntax:   OPTION EMULATOR
            OPTION NOEMULATOR

  Description:

     Controls how floating-point instructions are generated. NOEMULATOR,
     the default, generates the coprocessor instructions directly.
     EMULATOR generates instructions as well as special fixup records
     for the linker so that the floating-point emulator can be used. This
     option is definable only once per source file.

     To use this option, you must link your assembly-language module with
     an emulator library from a Microsoft high-level language.

     OPTION EMULATOR is equivalent to the /FPi command-line option.
                                    --

Topic:  Offset Relative to Segment/Group

  Syntax:   OPTION OFFSET:offsettype

  Description:

     Controls whether the OFFSET operator returns offsets relative to
     the current segment or group. OPTION OFFSET:GROUP causes OFFSET
     to return a group-relative offset if the label is in a segment
     that is part of a group. OPTION OFFSET:SEGMENT causes OFFSET
     to return a segment-relative offset. OPTION OFFSET:GROUP is the
     default.

     The FLAT option causes fixups to be relative to the FLAT group.

     OPTION M510 sets OPTION OFFSET:GROUP if a .MODEL directive has been
     used and OPTION OFFSET:SEGMENT otherwise. With previous versions of
     the assembler, the OFFSET type was SEGMENT with complete segment
     directives and GROUP with simplified segment directives.

     The <offsettype> can be GROUP, SEGMENT, or FLAT.
                                    --

Topic:  Register Macro as Prologue or Epilogue

  Syntax:   OPTION PROLOGUE:macroname

            OPTION EPILOGUE:macroname

  Description:

     PROLOGUE registers <macroname> as the macro function to be called
     when a prologue needs to be generated. EPILOGUE registers
     <macroname> as the macro procedure to be called when a RET or IRET
     instruction is encountered.

     You can revert to the default prologue or epilogue by specifying
     PrologueDef or EpilogueDef as <macroname>. EPILOGUE code is
     generated only if the RET or IRET instruction terminating the PROC
     block has no operand. The RETN, RETF, and IRETF instructions do not
     cause the assembler to generate epilogue code.

     To suppress generation of the prologue or epilogue code, give NONE
     as the <macroname>.

     The assembler expects a macro definition of this form:

     macroname MACRO procname, flags, argbytes, localbytes, <reglist>,
                     userparms:VARARG

     Parameter      Description

     procname       Macro name for the procedure or NONE.

     flags          Word-size bit flag: (1=On, 0=Off)
                    Bits    Description
                    0-2     Language type:
                              000     Not specified
                              001     C
                              010     SYSCALL
                              011     STDCALL
                              100     Pascal
                              101     Fortran
                              110     Basic
                              111     Reserved
                    3       Reserved
                    4       Caller restores stack
                    5       FAR procedure
                    6       PRIVATE procedure
                    7       EXPORT procedure
                    8       Epilogue caused by IRET instruction

                    All other bits are reserved for future use.

     argbytes       The total number of bytes used by PROC arguments.

     localbytes     The total number of bytes used by variables defined
                    with the LOCAL directive inside the PROC block.

     reglist        Comma-delimited list of registers from the PROC
                    directive USE option. This list is reversed in
                    in the EPILOGUE directive. Angle brackets are
                    passed.

     userparms      Passed the optional macroarglist from the PROC
                    directive.
                                    --

Topic:  Disable/Enable Keyword Recognition

  Syntax:   OPTION NOKEYWORD:<keywordlist>

  Description:

     Disables the recognition of the reserved words in <keywordlist>
     for the current module. The listed keywords can then be used as
     user-defined symbols. Keywords disabled with this directive cannot
     be reenabled. The <keywordlist> is a space-delimited list of
     reserved words; literal operands and predefined symbols are not
     allowed. The list of keywords must be enclosed in angle brackets (<>).

     You can use this option to disable privileged instruction names
     or obsolete synonyms so they are free to be used as labels and
     variables. For example:

               OPTION  NOKEYWORD: <STR EXTRN IRPC>
          STR  BYTE    10 DUP (?)
                                    --

Topic:  Select 16- or 32-Bit Expressions

  Syntax:   OPTION EXPR16

            OPTION EXPR32

  Description:

     The EXPR32 option selects 32-bit expressions and arithmetic. The
     EXPR16 option selects 16-bit expressions and arithmetic. The
     default is EXPR32. The expression word size cannot be changed once
     it has been explicitly set.

     Under OPTION M510, EXPR16 is the default unless the module contains
     a .386 or greater processor-selection directive.

     These options do not affect the processor type, segment size, or
     registers used.
                                    --

Topic:  Select Segment Size

  Syntax:   OPTION SEGMENT:segmentsize

  Description:

     The SEGMENT:USE16 option selects 16-bit segments. The SEGMENT:USE32
     option selects 32-bit segments. The SEGMENT:FLAT option selects
     the 32-bit flat segment. This option overrides the segment size set
     optionally set by the SEGMENT and .MODEL directives.

     The default segment size is selected by the following rules:

     ■ A .386 or higher processor selection directive selects USE32.

     ■ A .MODEL FLAT statement selects FLAT. All other memory models select
       USE16.

     ■ The OPTION SEGMENT: directive will override any other defaults.

     ■ In all other cases, the default is USE16.
                                    --

Topic:  Disable Byte Sign-Extended Opcode

  Syntax:   OPTION NOSIGNEXTEND

  Description:

     The NOSIGNEXTEND option disables the generation of the sign-
     extended form (83h) of the AND, OR, and XOR instructions. The NEC
     V25 and V35 microprocessors do not support this opcode.
                                    --

Topic:  Select Default PROC Visibility

  Syntax:   OPTION PROC:visibility

  Description:

  Sets the default procedure visibilty. The <visibility> parameter can
  be PRIVATE, PUBLIC, or EXPORT. If you do not use this option, the
  the default visibility will be PUBLIC.

  With OPTION M510, the default <visibility> with no defined language type
  is PRIVATE. If you specify a language type in a .MODEL or OPTION LANGUAGE
  statement, the default <visibility> is PUBLIC.
                                    --

Topic:  Specify Assembly Start Address

  Syntax:   ORG expression

            ORG $+expression

  Description:

     Sets the location counter to a specific address, given by <expression>.
     The assembler implements this directive by adjusting the
     location counter.

     ORG $+expression causes the assembler add <expression> bytes to
     the location counter. The <expression> must evaluate to a constant
     without forward references.

     Inside a STRUCT block, the <expression> parameter is relative to
     the beginning of the structure. This can be used to create
     structure elements that refer to bytes lower in memory than the
     beginning of the structure.
                                    --

Topic:  Set Page Size

  Syntax:   PAGE [[length], width]

  Description:

     Sets maximum number of lines per page (length) and maximum number
     of characters per line (width) for listing files. Generates a page
     break if no arguments are given. A zero for <width> means that the
     assembler does not generate line breaks. A zero for <length> means
     that the assembler does not generate page breaks.

     The <length> parameter is a number between 10 to 255 lines (default
     is 0). The <width> parameter is a number between 60 to 255
     characters (default is 0). To specify width without changing the
     default length, omit the length parameter and precede <width> with
     a comma.
                                    --

Topic:  Cause a Page Break

  Syntax:   PAGE +

  Description:

     Causes a page break by inserting an ASCII form-feed character
     (0Ch), increments the section number, and resets the page number
     to 1. This directive is useful only with printer listings.

     Program-listing page numbers use the following format:
     section-page, where section is the section number within the
     module, and page is the page number within the section. By
     default, section and page numbers begin with 1-1.
                                    --

Topic:  Define Procedure

  Syntax:   label PROC [distance] [langtype] [visibility]
            [<prologuearg>]
            [USES reglist] [,parameter [:tag]]...
                    [LOCAL varlist]
                    statements
            label ENDP

  Description:

     Defines a procedure called <label>. To use <parameter>, you must
     have previously specified a language type or used the <langtype>
     parameter. You should use a PROTO prototype before each procedure
     defined with the PROC directive. This ensures proper type checking
     and allows you to call the procedure with the INVOKE directive.

     Procedures usually end with the RET instruction. You can remove
     data from the stack by specifying the number of bytes as a
     parameter of the RET instruction.

     The assembler automatically generates PROLOGUE and EPILOGUE code
     to pass stack arguments properly to the procedure and clean up the
     stack after completion of the procedure. You can override the
     default prologue and epilogue code with user-defined macros by
     using the OPTION PROLOGUE: and OPTION EPILOGUE: directives.
     The RETF or IRETF instructions do not cause the assembler to
     generate epilogue code.

     Procedures can be nested if they do not have parameters, local
     variables or the USES parameter and do not generate a new segment
     or group. You can avoid having to nest procedures by using the RETN
     and RETF instructions.

     Local variables must be declared (using the LOCAL directive)
     before any instructions. There can be several LOCAL statements in
     a procedure.

     Parameter      Description

     label          Defines name for the procedure. Follows naming
                    convention of <langtype>.

     prologuearg    Arguments to pass to the prologue procedure. With
                    the default PROLOGUE and EPILOGUE, the FORCEFRAME
                    argument generates a stack segment, even if one is
                    not necessary. LOADDS causes the DS register to be
                    saved in the PROLOGUE and restored in the EPILOGUE.
                    Parameters must be separated by commas. Angle brackets
                    are required but not passed.

     distance       NEAR, FAR, NEAR16, NEAR32, FAR16, or FAR32. Indicates
                    the call distance of this procedure. If you choose
                    NEAR or FAR, the assembler will select 16- or 32-bit
                    NEAR or FAR depending on the current segment size. If
                    you do not specify this option, the assembler
                    determines the distance from the memory model and
                    processor type. NEAR is the default if you do not use
                    the .MODEL directive.

     langtype       Any valid language type. Determines naming style
                    and calling convention.

     visibility     PRIVATE, PUBLIC, or EXPORT. Determines how the
                    procedure is made available to other modules. PUBLIC
                    is the standard default, but the default can be reset
                    with the OPTION PROC directive. EXPORT implies PUBLIC
                    and FAR and informs the linker that the procedure
                    should be placed in the export entry table.

     reglist        List of registers that the prologue preserves on the
                    stack and the epilogue restores on exit. Separate
                    multiple registers with spaces.

     parameter      Procedure parameter. The assembler translates
                    argument references into a direct reference to the
                    stack location. Separate multiple arguments with
                    commas.

     tag            Either a qualified type or VARARG. VARARG allows a
                    variable number of arguments to be passed as a
                    comma separated list to <argument>. If VARARG is
                    used, it must be applied to the last parameter of
                    the PROC directive. VARARG is only allowed with
                    the C, SYSCALL, and STDCALL language types. If <tag>
                    is omitted, the assembler defaults to WORD in a 16-bit
                    segment or DWORD in a 32-bit segment.

     statements     Assembly-language statements and directives.
                                    --

Topic:  Define a Procedure Prototype

  Syntax:   label PROTO [distance] [langtype] [, [parameter]:tag]...

  Description:

     Defines a prototype for a subsequent procedure. Informs the
     assembler about how many and what kind of arguments should be
     expected in a procedure definition. This allows the assembler
     to perform type checking on arguments.

     If you define a prototype for all stack-based procedures defined
     with the PROC directive, you can place procedure prototypes in a
     separate include file. This is recommended when using procedures
     in a library file.

     Parameter      Description

     label          Defines name for the procedure. Must exactly match
                    <label> in PROC definition.

     distance       NEAR, FAR, NEAR16, NEAR32, FAR16, or FAR32.
                    Indicates the call distance of this procedure.
                    If you choose NEAR or FAR, the assembler will
                    select 16- or 32-bit NEAR and FAR depending on
                    the processor directive in effect. If you do not
                    specify this option, the assembler determines the
                    distance from the memory model and processor type.
                    NEAR is the default if you do not use the .MODEL
                    directive.

     langtype       Any valid language type. Determines naming style
                    and calling convention.

     parameter      Procedure parameter. The assembler translates
                    argument references into a direct reference to the
                    stack location. Separate multiple arguments with
                    commas.

     tag            Either a qualified type or VARARG. VARARG
                    allows a variable number of arguments to be passed
                    as a comma separated list to <argument>. If VARARG
                    is used, it must be applied to the last parameter
                    of the PROC directive. VARARG is only allowed with
                    the C, SYSCALL, and STDCALL language types.
                                    --

Topic:  Make Variable Public

  Syntax:   PUBLIC [langtype] name [,[langtype] name]...

  Description:

     Makes one or more variables available to other modules in the
     program. PUBLIC names can be forward referenced.

     The following can be made PUBLIC:

        ■ NEAR and FAR code labels and procedures
        ■ Data created with user-defined types, BYTE, WORD, and other
          types
        ■ Data created with user-defined structures, unions, and records
        ■ Labels created with the LABEL directive
        ■ Symbolic constants created with EQU or =

     The PUBLIC directive is normally used with the EXTERN directive.
     The EXTERNDEF and COMM directives allow more flexibility in
     global data declaration than the PUBLIC and EXTERN directives.

     Parameter      Description

     langtype       Any language type. Used to control what format
                    label names are sent to the linker.

     name           The name of a variable, label, or numeric equate
                    defined within the current source file
                                    --

Topic:  Delete Macros from Memory

  Syntax:   PURGE macroname [, macroname]...

  Description:

     Deletes one or more currently defined macros from memory. Use this
     directive if your system does not have enough memory to keep all
     the macros needed for a source file in memory at the same time.
     The macro skeleton will remain, but it will not expand.

     A macro can remove itself if PURGE is on the last line of the
     macro. Redefining a macro automatically purges the previous
     definition. Calling a purged macro is legal, but the macro will
     act like a blank macro.
                                    --

Topic:  Push/Pop Assembler Settings

  Syntax:   PUSHCONTEXT context

            POPCONTEXT context

  Description:

     PUSHCONTEXT stores the context information indicated in <context>.
     POPCONTEXT restores the context information indicated in <context>.
     You can nest PUSHCONTEXT directives up to 10 levels.

     You can use these directives to save and restore the state of the
     assembler in include files and procedures.

     <context>         Items Saved

     ASSUMES           Register assumptions
     RADIX             Current default radix
     LISTING           Listing and cref flags
     CPU               CPU and coprocessor directives
     ALL               All of the above
                                    --

Topic:  Set Default Radix (Number Base)

  Syntax:   .RADIX expression

  Description:

     Sets the default radix (base) for integer constants to the value
     of <expression>. The default radix at the start of assembly is 10.

     The .RADIX directive does not affect floating-point constants or
     numbers that have explicit radix overrride tags:

     Tag        Base
     H          hexadecimal
     O or Q     octal
     T          decimal
     Y          binary
     R          floating point

     With a radix of 10 or below, you can use the characters B (b) and D
     (d) as the radix override characters for base 2 and base 10,
     respectively.

     The <expression> must evaluate to a decimal number in the range 2
     to 16 and cannot contain forward references.
                                    --

Topic:  Declare Record

  Syntax:   recordname RECORD field [, field]...

  Description:

     Declares a record template of one or more specified bit fields
     but does not allocate storage for the template. Separate multiple
     fields with a comma.

     Records can be used as constants or expressions. They are treated
     as a BYTE or WORD with 16-bit expressions and as a BYTE, WORD, or
     DWORD with 32-bit expressions. The sum of the widths for all fields
     must not exceed the expression width.

     Once a record template is declared, you can use it to define
     record variables or constants, in which each field not initialized
     assumes the default value. Records are defined with the following
     syntaxes:

       [name1]   recordname   {[initializer1] [, initializer2]...}
       [name1]   recordname   <[initializer1] [, initializer2]...>

     Use of <recordname> is similar to the other variable definition
     directives (such as BYTE and WORD). Curly braces or angle brackets
     are required even if no initializers are given.

     If a record constant appears as part of an expression in a control
     flow directive (such as .IF or .WHILE), you must use curly braces
     instead of angle brackets to enclose the fields.

     The assembler will treat the name of a record field without the
     MASK or WIDTH operators as the bit number of the first bit of the
     record field.

     Parameter      Description

     recordname     A unique symbolic name.

     field          Each field is in the form

                         fieldname:width[= expression]

                    where <width> is a constant giving the width of the
                    field (in bits) and <expression> optionally sets an
                    initial or default value.
                                    --

Topic:  Repeat Assembly of Block

  Syntax:   REPEAT expression
              statements
            ENDM

  Description:

     Assembles a block of statements <expression> times. REPT is a
     synonym for REPEAT and is included for compatibility with previous
     versions of the assembler.



     The <expression> parameter must evaluate to a numeric constant. This
     constant is evaluated during the first pass. The <statements> are
     any valid assembler statements.
                                    --

Topic:  Define Segment

  Syntax:   name SEGMENT [align] [READONLY] [combine] [use] ['class']
              statements
            name ENDS

  Description:

     Defines a program segment called <SegName> with optional segment
     attributes: align, READONLY, combine, use, and class. These
     attributes give the linker and assembler information on how to set
     up, combine, and refer to segments. A segment can be reopened within
     a module by specifying the same <name> in a later SEGMENT statement.

     The SEGMENT directive automatically saves any segment definition
     that is already in effect. When the assembler encounters a closing
     ENDS, it restores the saved segment definition.

     Parameter      Description

     name           Name of the segment being defined. You can use the
                    @CurSeg macro function with the ENDS directive to
                    terminate the current segment.

     align          BYTE, WORD (2 bytes), DWORD (4), PARA (16), or PAGE
                    (256). Aligns segment to boundary. PARA is the
                    default.

     combine        PRIVATE, PUBLIC, STACK, COMMON, MEMORY, or AT
                    address. Defines how the linker combines segments.
                    PRIVATE is the default.

     use            USE16, USE32, or FLAT. Selects the segment word size.

     READONLY       Makes segment read-only. The assembler will generate
                    an error if an instruction explicitly modifies a
                    segment marked with the READONLY attribute. Useful
                    for protected-mode code segments and segments in ROM.

     class          A class name (such as CODE or DATA). Must be enclosed
                    in quotation marks. Used to associate segments with
                    different names and to control segment order. Code
                    segments should have class 'CODE'.
                                    --

Topic:  Find String Length

  Syntax:   @SizeStr(string)

            name SIZESTR textitem

  Description:

     The @SizeStr macro function returns the length of a text item in
     characters. The @SizeStr function will not expand macros or
     expressions unless you use the expression operator (%). A zero
     indicates a null (empty) string.

     The SIZESTR directive performs the same function but assigns the
     result to <name>. These two lines are equivalent:

          namelength   TEXTEQU     @SizeStr(<Denise>)
          namelength   SIZESTR     <Denise>
                                   ;namelength is 6

     The <name> is a unique symbolic name, <string> is a string, and
     <textitem> must be a text item.
                                    --

Topic:  Start Stack Segment

  Syntax:   .STACK [size]

  Description:

     Creates the program stack segment (with segment name STACK) nested
     inside the current segment, if any. The .MODEL directive must
     precede this directive. The .MODEL directive generates a GROUP
     statement that places the STACK segment in DGROUP unless the
     FARSTACK attribute is given.

     A single .STACK statement opens and closes the stack segment,
     so you should not include an additional ENDS statement.

     The <size> parameter specifies size of the stack in bytes (default
     1024).
                                    --

Topic:  Generate Start-Up/Exit Code

  Syntax:   .STARTUP

            .EXIT [expression]

  Description:

     The .STARTUP directive generates start-up code for the given CPU
     type and the memory model, operating system, and stack type
     defined by the .MODEL directive. Defines a start-address label,
     so that you don't need to give a start address with END. .STARTUP
     initializes DS, SS, and SP under DOS.

     The .EXIT directive generates code that terminates the program and
     returns control to the operating system or calling program. Use of
     the <expression> parameter returns a numeric exit code to the
     operating system or calling program.

     The <expression> parameter is an optional return code that can be
     read by the calling program or by a batch file. It can be a byte-
     sized register (word-sized under OS_OS2), memory location, or
     constant.

     With the TINY model, the .STARTUP directive also generates an
     ORG 100h.

     The .MODEL directive must precede these directives. The default
     OSType is DOS.

     To use the .EXIT directive under OS/2, you must link with OS2.LIB
     or a library that provides a termination procedure with a
     prototype such as:

       DosExit  PROTO   terminate: WORD,   ; This is the prototype in
                        exitcode:  WORD    ;  OS2.INC
                                    --

Topic:  Declare Structure Data Type

  Syntax:   name STRUCT [alignment] [, NONUNIQUE]
              fielddeclarations
            name ENDS

  Description:

     Declares a structure as a new data type. STRUC is a synonym for
     STRUCT and is included for compatibility.

     Once a structure name is declared, you can use it to define
     variables in which each field not initialized assumes the default
     value:

        [name]  structname  <[initializer [, initializer]...]>
     or
        [name]  structname  { \
                                [initializer] \
                                [, initializer]... \
                                               }
     or
        [name]  structname  constant DUP ({[initializer[, initializer]...]})

     Curly braces or angle brackets are required even if no initializers
     are given. The DUP operator can be used to make duplicate
     initializations. Structures may be nested.

     You must refer to structure members in the format
     structurename.membername or with a pointer to a structure followed
     by the .membername tag. You can use multiple sequential membernames
     to specify elements of nested structures.

     The NONUNIQUE parameter requies elements of the structure to be
     accessed only by their fully specified names.

     The ORG directive has a special meaning inside a STRUCT block.

     Parameter         Description

     name              A unique symbolic name for the structure.

     alignment         1, 2, or 4. Byte boundary to align structure
                       fields. The default is 1.

     fielddeclarations Any valid data definitions (using BYTE, WORD,
                       etc.) with initial values. Can also be another
                       previously defined structure or a user-defined
                       type. Field names do not need to be unique; you
                       can reuse the same name in multiple structures.
                       Some other directives are allowed in this field;
                       see the BNF Appendix in the MASM Programmer's
                       Guide.

     initializer       Data initializer for structure field.
                                    --

Topic:  Extract Characters from String

  Syntax:   @SubStr(string, start [,length])

            name SUBSTR textitem, start [,length]

  Description:

     The @SubStr macro function extracts specified characters from a
     text item. If <length> is not given, the function will return all
     characters to the right of (and including) the character pointed
     to by <start>. The @SubStr function will not expand macros or
     expressions unless you use the expression operator (%).

     The SUBSTR directive performs the same function but assigns the
     result to <name>. These two lines are equivalent:

       country    TEXTEQU     @SUBSTR (<AndorraMonacoLuxembourg>,8,6)
       country    SUBSTR      <AndorraMonacoLuxembourg>,8,6
                              ;country is <Monaco>

     Parameter      Description

     name           A unique symbolic name.

     string         A string to extract characters from.

     textitem       A text item to extract characters from.

     start          Starting position of substring; the first character
                    is indexed as 1. Must be a positive integer constant.

     length         Number of characters to extract. Must be a positive
                    integer constant.
                                    --

Topic:  Toggle .LISTIF/.NOLISTIF

  Syntax:   .TFCOND

  Description:

     Toggles the state of the assembler between .LISTIF and .NOLISTIF,
     determining whether or not false conditional blocks are included
     in assembler listings.
                                    --

Topic:  Specify Title/Subtitle

  Syntax:   TITLE text

            SUBTITLE text

  Description:

     The TITLE directive specifies the title to be used on each page
     of assembly listings. The <text> is printed flush left on the
     second line of every page of the listing. Only one TITLE directive
     per module is allowed.

     The SUBTITLE directive specifies the subtitle to be used on each
     page of assembly listings. The <text> is printed flush left on the
     third line of every page of the listing. Each new SUBTITLE
     statement replaces the current subtitle; the change will be
     displayed on the next page of the output. SUBTTL is a synonym of
     SUBTITLE and is included for compatibility with previous versions
     of the assembler.

     The <text> is any combination of characters up to 60 characters.
                                    --

Topic:  Define Type Symbol

  Syntax:   name TYPEDEF qualifiedtype

            name TYPEDEF PROTO prototypelist

  Description:

     Defines a new type or creates a synonym for an already defined
     type. The TYPEDEF directive associates <name> with a type, and,
     once defined, the symbol can be used anywhere a type can be used
     or as a data declaration directive. The <qualifiedtype> parameter
     can specify a pointer to a qualified type. The TYPEDEF PROTO
     syntax defines a prototype type.

     Once a type is defined, you can use it to define variables. Use is
     similar to the other variable definition directives (like BYTE and
     WORD).

     Parameter      Description

     qualifiedtype     Any qualified type. Can include a type
                       previously defined by a TYPEDEF directive, but
                       recursive definitions are not allowed.

     prototypelist     List of parameters for procedure prototype. Uses
                       the same syntax as the PROTO directive.
                                    --

Topic:  Declare Union as Data Type

  Syntax:   name UNION [alignment] [, NONUNIQUE]
              fielddeclarations
            [name] ENDS

  Description:

     Declares a union as a new data type. Allows the same memory
     locations to be overlapped with different types. Identical to
     STRUCT except that each member has a 0 offset. The size of the
     union is the size of the largest member of the union.

     Unions can be used to store one type of data in some circumstances
     and another type in a different situation. Unions also allow you
     to store data as one data type and then read it as another. Unions
     are initialized by using the union name as a data declaration
     directive. You only need to initialize a union for one data type.

     You must refer to union members by their member names. The LABEL
     directive allows you to refer to the entire union as a unit.

     The first-level definition of a union must include the <name>
     label preceding the ENDS. In nested unions, terminate the block
     with a ENDS statement without the <name> label.

     The <alignment> field determines the byte alignment of any
     structures. This field can be 1, 2, or 4. The default is 1, unless
     overridden by the /Zp command-line option or the
     ALIGN or EVEN directives.

     The NONUNIQUE parameter allows elements of the union to be
     accessed only by their fully specified names.

     Some directives are allowed in the <fielddeclarations> field;
     see the BNF Appendix in the MASM Programmer's Guide.

  Example:

     EXTENDCHAR  UNION
                 ascii       BYTE    ?      ;Define a union of byte and
                 kanji       WORD    ?      ; word
     EXTENDCHAR  ENDS
     initial     EXTENDCHAR  <J>            ;Create a union variable
     mov         al, initial.ascii          ;Move byte-length data
     mov         bx, initial.kanji          ;Move word-length data
                                    --

Topic:  Assemble While Expression is True

  Syntax:   WHILE expression
              statements
            ENDM

  Description:

     Marks a block of statements to be assembled repeatedly until
     <expression> is false (zero). The <expression> is a constant
     expression whose value is computed at assembly time.
                                    --

Topic:  Labeling Punctuation (:/::)

  Syntax:   label:

            label::

            :macrolabel

            register::register

  Description:

     Gives name <label> to the memory location of the next instruction
     or piece of data. Can be target of loop, branch, jump, load, or
     any instruction or directive that requires a memory location.

     The register::register syntax is independent of this definition. In
     this case, the double-colon is used as a delimiter for a register
     pair passed with the INVOKE directive.

     With the single colon, <label> has global scope within its
     module under the default OPTION NOSCOPED. Under OPTION SCOPED,
     <label> is LOCAL inside a PROC block and is global elsewhere.
     The <label> cannot be declared public.

     The double colon acts the same as the single colon except that
     <label> has global scope within its module, independent of OPTION
     SCOPED, and can be declared PUBLIC.

     The :macrolabel labeling syntax is used exclusively inside MACRO,
     FOR, FORC, REPEAT, and WHILE blocks. It can be used only as the
     destination of the GOTO directive.
                                    --

Topic:  Segment Override Operator (:)

  Syntax:   segment:expression

  Description:

     Overrides the default segment of <expression> with <segment>.
     Forces the address of the variable or label to be computed
     relative to the specified segment.

     Parameter      Description

     segment        A segment register (CS, DS, SS, ES, FS, or GS),
                    group name, segment name, or segment expression.

     expression     A memory expression.
                                    --

Topic:  Structure Field Reference (.)

  Syntax:   expression.field[.field]...

            expression2.structtype.field[.field]...

  Description:

     Returns the offset of <expression> plus the value of <field>. This
     operator is usually used to access a field of data within a structure
     or union variable. You can use several dot operators to access nested
     structures.

     Parameter      Description

     expression1    An expression for which the qualified type is a
                    structure

     expression2    An arbitrary expression.

     structtype     A defined structure type.

     field          A field within a previously defined structure type.
                    Each field has an offset relative to the beginning
                    of the structure.

  Example:

     DPSTRUCT   STRUCT                          ; Memory-mapped dsp
                ctrlreg         WORD    ?       ;  data structure
                addrreg         DWORD   ?
     DPSTRUCT   ENDS

     IOSTRUCT   STRUCT                          ; Set up nested structure
                vio             VIDEOSTRUCT <>  ;  for I/O
                dsp             DPSTRUCT <>     ;
     IOSTRUCT   ENDS

     ioInst     IOSTRUCT        <>              ; Instance of IOSTRUCT

     lea        ax, (IOSTRUCT PTR [bx]).\       ; Loads offset of
                dsp.ctrlreg                     ;  ctrlreg element of I/O
                                                ;  structure pointed to
                                                ;  by the bx register

     assume     bx:PTR IOSTRUCT
     lea        ax, [bx].dsp.ctrlreg            ; Same as above code line

     mov        ioInst.dsp.ctrlreg, 10h         ; Set control register to 10
                                    --

Topic:  Index ([])

  Syntax:   expression1[expression2]

  Description:

     The brackets (also called the "index operator") return the sum of
     <expression1> and <expression2>. If <expression2> is a register,
     the brackets indicate an indirect memory operand rather than a
     register-direct operand.

     In the syntax above, the brackets are literal and must be
     included. The expression outside the brackets is optional. You
     cannot add two direct memory operands.
                                    --

Topic:  String Delimiters ("/')

  Syntax:   "text"

            'text'

  Description:

     Treats <text> as a string. You can use single or double quotation
     marks, but the quotation marks on both sides of <text> must be
     identical. A string can be up to 255 characters long and must be
     on a single physical line. You can use a quotation mark inside a
     string by repeating it twice in a row ("" or ''). The left-hand
     single quotation mark (`) is not allowed as a delimiter.

  Example:

     quote1      BYTE     "This was called by 'int 23h'"
     quote2      BYTE     'This was called by "int 23h"'
     quote3      BYTE     "Use the ""ASSUME"" directive"
     quote4      BYTE     'Use the ''ASSUME'' directive'
                                    --

Topic:  Literal Text Operator (<>)

  Syntax:   <text>

  Description:

     Treats <text> as a single literal string.

     Angle brackets are often used in macro calls and with the FOR
     directive to ensure that values in a parameter list are treated as
     a single parameter. For example,

       MyMacro   <one, two, three>       ;Passes one argument to
                                         ;MyMacro

       MyMacro   one, two, three         ;Passes three arguments to
                                         ;MyMacro

     The assembler removes one set of angle brackets each time it
     inserts an argument into a macro expansion.

     The <text> is any name, number, or expression. It can contain
     commas, spaces, tabs, or semicolons. The exclamation point (!) is
     an escape character that allows you to include special characters
     such as the semicolon, ampersand, and quotation marks.
                                    --

Topic:  Literal Character Operator (!)

  Syntax:   !character

  Description:

     Treats <character> as a literal character rather than as an
     operator or a symbol. Used with special characters (<, >, ", ', %,
     ;, and comma) when the usual assembly language meaning of the
     character must be suppressed. A double exclamation point (!!) is
     treated as a single exclamation point. The escape character does
     not apply to strings in quotation marks or to backslashes at the
     end of a line.

     For example:

      <I!'m afraid I can!'t do that!!>
                                    --

Topic:  Comment Delimiter (;/;;)

  Syntax:   ;text
            ;;text

  Description:

     The single semicolon treats <text> to the end of the line as a
     comment. The double semicolon treats <text> to the end of the
     line as a macro comment. In a listing file, macro comments appear
     with the macro definition, not with the macro expansion.

     Comments must follow all other fields in a statement line.
                                    --

Topic:  Expression Operator (%)

  Syntax:   %expression

  Description:

     Computes the value of <expression> and treats it as a text string.
     Use in macro calls when you need to pass the result of an
     expression rather than the actual expression to a macro. The
     <expression> can also be a text macro or a macro function.

     When placed at the beginning of the line, % causes the
     calculation and substitution of all text macros on that line,
     including those inside angle brackets (<>). Macro function calls
     inside angle brackets (<>) are not expanded unless precedes by a
     %.
                                    --

Topic:  Substitution Operator (&)

  Syntax:   ¶meter&

  Description:

     Operator used within a macro or a repeat block; enables parameter
     substitution for <parameter>. Two parameters can be joined to form
     one symbol. You can join any number of parameters with the
     ampersand operator.

     You can also use this operator to force parameter substitution in
     a quoted string. For this reason, if you want an ampersand to be
     included in a string, you must use the string escape character (!)
     before the &.

     Use ampersands (&) only around macro parameters, in quoted strings,
     and inside angle brackets (<>). Each parameter to be substituted
     must have one ampersand on the left and right. If an ampersand is
     adjacent to white space, it can be omitted as long as one
     ampersand is next to each parameter to be substituted.

  Example:

     Guard    MACRO     Prisonernum:REQ, Prisonername:=Anonymous
                        ECHO    <Number &Prisonernum has arrived at &@Time.>
              EXITM     Prisonernum&&Prisonername
              ENDM

     Badge    Guard     2
                                    --

Topic:  Repeat Declaration Operator

  Syntax:   count DUP (initialvalue [,initialvalue]...)

  Description:

     Specifies <count> declarations of <initialvalue>. You can define
     arrays, buffers, and other data structures consisting of multiple
     data objects of the same size with the DUP operator. The
     <initialvalue> parameters must be inside parentheses. This
     operator can be used with data definition directives.

     The <count> parameter is the number of declarations of
     <initialvalue>. This parameter cannot be negative or
     forward-referenced. The <initialvalue> parameter is either the
     undefined data symbol (?), a string, a constant expression, or
     another DUP operator. The value or values of <initialvalue> are
     evaluated once before duplication. Separate multiple initial
     values with commas.
                                    --

Topic:  High/Low-Order Byte

  Syntax:   HIGH expression
            LOW expression

  Description:

     The HIGH operator returns the high-order (most significant) byte
     of <expression> in two's-complement form. The LOW operator returns
     the low-order (least significant) byte of <expression> in two's-
     complement form. The <expression> must resolve to a constant or
     an OFFSET expression.
                                    --

Topic:  High/Low-Order Word

  Syntax:   HIGHWORD expression
            LOWWORD expression

  Description:

     The HIGHWORD operator returns the high-order (most significant)
     word of <expression> in two's-complement form. The LOW operator
     returns the low-order (least significant) word of <expression> in
     two's- complement form. The <expression> must resolve to a constant
     or an OFFSET expression.
                                    --

Topic:  Variable Length

  Syntax:   LENGTHOF variable

            SIZEOF variable

            SIZEOF type

            LENGTH expression

            SIZE expression

  Description:

     The LENGTHOF operator returns the number of data items allocated
     for <variable>. The SIZEOF operator returns the total number of
     bytes allocated for <variable> or the size of <type> in bytes. For
     variables, SIZEOF is equal to the value of LENGTHOF times the
     number of bytes in each element.

     The LENGTH and SIZE operators are allowed for compatibility with
     previous versions of the assembler. When applied to a data label,
     the LENGTH operator returns the number of elements created by the
     DUP operator; otherwise it returns 1. When applied to a data
     label, the SIZE operator returns the number of bytes allocated by
     the first initializer at the <variable> label.
                                    --

Topic:  Bit Mask

  Syntax:   MASK record

            MASK recordfieldname

  Description:

     Returns a bit mask for the bit positions in a record or record
     field. A bit in the mask contains a 1 if that bit corresponds to
     a field bit. All other bits contain 0.

     The <record> parameter is the name of any record. The
     <recordfieldname> parameter is the name of any field in a record.
                                    --

Topic:  Offset Address

  Syntax:   OFFSET expression

  Description:

     Returns offset address of <expression> (usually a variable). The
     value returned by the OFFSET operator is an immediate operand.
     OFFSET can be applied to any immediate or memory expression
     except a register or segment.

     The offset returned is relative to either the current group
     or segment. If there is both a current group and a current
     segment, the offset will have a group-relative default offset.
     This default can be changed with the M510 and OFFSET: options.

     The OFFSET operator can accept an expression specifying a segment.
     In this case, the OFFSET operator returns the offset of the last
     byte of the given segment, relative to that segment's group.  This
     value reflects the size of the given segment when the OFFSET
     operator is assembled.

     The <expression> is any label, variable, segment, or other direct
     memory operand.
                                    --

Topic:  Loader-Resolved Offset

  Syntax:   LROFFSET expression

  Description:

     Similar to OFFSET, but causes the offset to be resolved by the
     loader at run time. LROFFSET is usually applied to the offset of
     a function pointer. This run-time resolution allows Microsoft
     Windows to relocate code segments in real mode.

     The <expression> is any label, variable, or other direct memory
     operand.

  Example:

     INVOKE     CreateRoutine, LROFFSET MyFunc, 0
                                    --

Topic:  Specify Type for Expression

  Syntax:   qualifiedtype PTR expression
            PTR qualifiedtype

  Description:

     The first syntax treats <expression> as having the specified type.
     Type casting can be used with forward references or unlabeled
     addresses to specify a reference size, type, or distance.

     The second syntax is used in defining qualified types.

     The PTR keyword can also appear in qualified types to indicate
     that the type is a pointer variable.

     The <qualifiedtype> can be any qualified type. The <expression>
     can be any valid expression. If <qualifiedtype> is a distance,
     <expression> cannot be a memory expresssion or a data label.

  Example:

     mov        ax, (MyStruct PTR [bx]).Username
     fld        TBYTE PTR MaxConvolution
     INVOKE     MyRoutine, PTR TempValue
                                    --

Topic:  Return Segment or Group of Expression

  Syntax:   SEG expression

  Description:

     Returns the segment or group of <expression>. If <expression> does
     not have an explicit segment or group, SEG returns the segment or
     group of the SEG expression itself. If the SEG expression has no
     segment or group, SEG returns the value of <expression>.

     The <expression> is any label, variable, group name, or other
     memory operand; it cannot be a constant.
                                    --

Topic:  Force Label Type to SHORT

  Syntax:   SHORT label

  Description:

     Forces <label> type to SHORT. Normally, the assembler selects
     short jumps and branches when possible, but SHORT can be used to
     generate an error if a short jump to <label> is not possible. It
     disables any automatic conditional-jump lengthening (OPTION LJMP).

     Short labels can be used in JMP instructions when the distance is
     less than 128 bytes from the start of the next instruction. This
     saves a byte of memory and reduces the number of clock cycles used.
                                    --

Topic:  Specify Same Operand Type

  Syntax:   THIS qualifiedtype

  Description:

     Returns an operand of <qualifiedtype> with offset and segment
     values equal to the current location-counter value. THIS can be
     used with EQU or = to create labels and variables. THIS NEAR is
     equivalent to $.

     These two lines are equivalent:

       tag1     EQU      THIS BYTE
       tag1     LABEL    BYTE

     The <qualifiedtype> can be any qualified type.
                                    --

Topic:  Return Expression Attributes

  Syntax:   TYPE expression

  Description:

     The TYPE operator returns a value and size and distance attributes
     appropriate to <expression>. You can use the constant returned by
     TYPE directly or use the attributes returned by TYPE. For example,
     you can use the returned attribute to specify a type for PTR.

     <expression>    Returns

     Variable        Number of bytes allocated for each element
     Structure       Total number of bytes in the structure
     Constant        0
     Code label      Distance
     Register        Size of register in bytes
                                    --

Topic:  OPATTR Operator

  Syntax:   OPATTR expression

            .TYPE expression

  Description:

     The OPATTR operator returns a one-word constant defining the mode
     and scope of expression. If <expression> is not valid or is forward-
     referenced, OPATTR returns a 0. If <expression> is valid, a
     nonrelocatable word is returned. The .TYPE operator returns only the
     low byte (bits 0-7) of the OPATTR operator and is included for
     compatibility with previous versions of the assembler.

     Bit          Set If
     Position     <expression>

     0            References a code label
     1            Is a memory expression or has a relocatable data
                  label
     2            Is an immediate expression
     3            Uses direct memory addressing
     4            Is a register expression
     5            References no undefined symbols and is without error
     6            Is an SS-relative memory expression
     7            References an external label
     8-11         Language type:

                  Bits     Language

                  000      No language type
                  001      C
                  010      SYSCALL
                  011      STDCALL
                  100      Pascal
                  101      FORTRAN
                  110      Basic

     All other bits are undefined and reserved for future expansion.
                                    --

Topic:  Record/Record-Field Width

  Syntax:   WIDTH {recordfieldname│record}

  Description:

     Returns width (in bits) allocated for a record or record field.

     The <recordfieldname> is the name of any field defined in any
     record. The <record> is the name of any defined record.
                                    --

Topic:  Local Code Labels

  Syntax:   [instruction] @F
                .
                .
                .
            @@: [statement]
                .
                .
                .
                [instruction] @B

  Description:

     The @@: label defines a local code label, which is in effect until
     the next instance of @@:. The @F and @B operands can be used in
     conditional and unconditional jump statements to jump to the next
     and previous @@: label respectively.

     The @@: label is useful for defining a nearby jump point where a
     full label is not appropriate.

  Example:

           cmp     ax, 18h
           jg      @F
           ¨                  ;Less than or equal
           ¨
           ¨
     @@:                      ;Greater than


           mov     cx, 640    ;Set count

     @@:
           ¨                  ;Loop statements
           ¨
           ¨
           loop    @B         ;Loop back
                                    --

Topic:  Line-Continuation (\) Operator

  Syntax:   text \
            text

  Description:

     Enables an assembly-language statement to continue on the next
     line, ignoring the line break. You can join any number of physical
     lines with this method. A backslash occurring inside a comment
     or string is not considered to be a line-continuation character.
     Logical lines cannot exceed a total of 512 characters.

     Comments can appear to the right of the \. A backslash is not
     required on a line ending with a comma.
                                    --

Topic:  Redefinable Numeric Equate

  Syntax:   name = expression

  Description:

     Creates or redefines a constant symbol by assigning the numeric
     value of <expression> to <name>. This equate can be used in
     subsequent statements as a symbolic constant and can be redefined
     at any time.

     The <name> field must be either a unique name or one previously
     defined with =. The <expression> fieldis any valid constant
     expression. Resolved at definition by the assembler.
                                    --

Topic:  Current Offset ($) Value

  Syntax:   $

  Description:

     Equates to the current value of the location counter (current
     offset address). Equivalent to THIS NEAR.

  Example:

     title    BYTE     "Space Mutants II"
     level    WORD     0
     hiscore  BYTE     20 DUP (?)
     tablelen EQU      $-title             ;tablelen = 38
                                    --

Topic:  Uninitialized Value (?)

  Syntax:   ?

  Description:

     Used as an initializer in data declarations; indicates a value
     that the assembler allocates but does not initialize. Can be used
     alone or with DUP, as in the following examples:

     Extension  WORD     ?           ; Allocate 1 uninitialized word
     Initials   BYTE     ?,?,?       ; Allocate 3 uninitialized bytes
     Fullname   BYTE     20 DUP (?)  ; Allocate 20 uninitialized bytes

     To minimize the size of executable files, use the .DATA? or .FARDATA?
     directives to define an undefined data segment. Put undefined data
     in these segments.
                                    --

Topic:  Arithmetic Operators

        Unary   Binary  Scaling
       ┌───────┬───────┬───────┐
    +  │   X   │   X   │       │
       ├───────┼───────┼───────┤
    -  │   X   │   X   │       │
       ├───────┼───────┼───────┤
    *  │       │   X   │   X   │
       ├───────┼───────┼───────┤
    /  │       │   X   │       │
       ├───────┼───────┼───────┤
   MOD │       │   X   │       │
       └───────┴───────┴───────┘

  Description:

     All of these operators can be used with two operands to calculate
     a numeric result. The minus (-) operator can be placed in front of
     an expression to negate its value. The plus (+) operator can also
     be placed before an expression, but it has no effect. The modulus
     (MOD) operator can only operate on integer expressions. The
     multiplication (*) operator can be used to scale index registers
     on 80386/486 processors. For example:

       .386
       movzx   eax, 10
               mov     bx, base [eax*2]
               ¨
               ¨
               ¨
               inc     eax
                                    --

Topic:  Logical and Shift Operators

  Syntax:   expression1 AND expression2

            expression1 OR expression2

            expression1 XOR expression2

            NOT expression

            expression SHL count

            expression SHR count

  Description:

     These operators perform logical manipulations of constant integer
     expressions. They return expressions of the size determined by the
     current expression size. Use the LOW and LOWWORD operators to
     return expressions of smaller sizes.

     These operators should not be confused with their instruction
     counterparts. Operators cannot act on registers or memory.

     Operand        Description

     expression     Any constant integer expression in any valid radix.

     count          The number of bits to be shifted. Must be a
                    constant positive integer. Bits shifted in are
                    always 0.
                                    --

Topic:  Relational Operators

  Syntax:   expression1 EQ expression2

            expression1 NE expression2

            expression1 GT expression2

            expression1 LT expression2

            expression1 GE expression2

            expression1 LE expression2

  Description:

     The EQ, NE, GT, LT, GE, and LE relational operators determine if
     two constant expressions or data labels (in the same segment)
     are equal, not equal, greater than, less than, greater than or
     equal, or less than or equal to each other. The comparison returns
     true (-1) or false (0).

     These operators work only with assembler symbols and constants;
     they cannot be used to evaluate registers or memory locations.
                                    --
 1:1