APPENDIX A

For the many users who come to version 6.1 of the Microsoft Macro Assembler directly from the popular MASM 5.1, this appendix describes the differences between the two versions. Version 6.1 contains significant changes, including:

u An integrated development environment called Programmer’s WorkBench (PWB) from which you can write, edit, debug, and execute code.

u Expanded functionality for structures, unions, and type definitions.

u New directives for generating loops and decision statements, and for declaring and calling procedures.

u Simplified methods for applying public attributes to variables and routines in multiple-module programs.

u Enhancements for writing and using macros.

u Flat-model support for Windows NT and new instructions for the 80486 processor.

The OPTION M510 directive (or the /Zm command-line switch) assures nearly complete compatibility between MASM 6.1 and MASM 5.1. However, to take full advantage of the enhancements in MASM 6.1, you will need to rewrite some code written for MASM 5.1.

The first section of this appendix describes the new or enhanced features in MASM 6.1. The second section, "Compatibility Between MASM 5.1 and 6.1," explains how to:

u Minimize the number of required changes with the OPTION directive.

u Rewrite your existing assembly code, if necessary, to take advantage of the assembler’s enhancements.

This section gives an overview of the new features of MASM 6.1 and provides references to more detailed information elsewhere in the documentation. For full explanations and coding examples, see the documentation listed in the cross-references.

Most of the executable files provided with MASM 6.1 are new or revised. For a complete list of these files, read the PACKING.TXT file on the distribution disk. The book Getting Started also provides information about setting up the environment, assembler, and Help system.

The macro assembler, named ML.EXE, can assemble and link in one step. Its new 32-bit operation gives ML.EXE the ability to handle much larger source files than MASM 5.1. The command-line options are new. For example, the /Fl and /Sc options generate instruction timings in the listing file. Command-line options are case-sensitive and must be separated by spaces.

For backward compatibility with MASM 5.1 makefiles, MASM 6.1 includes the MASM.EXE utility. MASM.EXE translates MASM 5.1 command-line options to the new MASM 6.1 command-line options and calls ML.EXE. See the Reference book for details.

H2INC converts C include files to MASM include files. It translates data structures and declarations but does not translate executable code. For more information, see Chapter 20 of Environment and Tools.

NMAKE replaces the MAKE utility. NMAKE provides new functions for evaluating target files and more flexibility with macros and command-line options. For more information, see Environment and Tools.

PWB is an integrated development environment for writing, developing, and debugging programs. For information on PWB and the CodeView debugging application, see Environment and Tools.

MASM 6.1 incorporates the Microsoft Advisor Help system. Help provides a vast database of online help about all aspects of MASM, including the syntax and timings for processor and coprocessor instructions, directives, command-line options, and support programs such as LINK and PWB.

For information on how to set up the help system, see Getting Started. You can invoke the help system from within PWB or from the QuickHelp program (QH).

You can use the HELPMAKE utility to create additional help files from ASCII text files, allowing you to customize the online help system. For more information, see Environment and Tools.

MASM 6.1 contains the most recent versions of LINK, LIB, BIND, CodeView, and the mouse driver. The CREF program is not included in MASM 6.1. The Source Browser provides the information that CREF provided under MASM 5.1. For more information on the Source Browser, see Chapter 5 of Environment and Tools or Help.

This section lists the changes and additions to memory-model support and directives that relate to memory model.

The following predefined symbols (also called predefined equates) provide information about simplified segments:

For more information about predefined symbols, see "Predefined Symbols" in Chapter 1.

MASM automatically generates ASSUME values for the code segment register (CS). It is no longer necessary to include lines such as

in your programs. In addition, the ASSUME directive can include ERROR, FLAT, or register:type. MASM 6.1 issues a warning when you specify ASSUME values for CS other than the current segment or group.

For more information, see "Setting the ASSUME Directive for Segment Registers" in Chapter 2 and "Defining Register Types with ASSUME" in Chapter 3.

For compatibility with applications for Windows, the LROFFSET operator can calculate a relocatable offset, which is resolved by the loader at run time. See Help for details.

MASM 6.1 supports the flat-memory model of Windows NT, which allows segments as large as 4 gigabytes. All other memory models limit segment size to 64K for MS-DOS and Windows. For more information about memory models, see "Defining Basic Attributes with .MODEL" in Chapter 2.

MASM 6.1 supports an improved data typing. This section summarizes the improved forms of data declarations in MASM 6.1.

You can now use the type names as directives to define variables. Initializers are unsigned by default. The following example lines are equivalent:

You can use the SBYTE, SWORD, and SDWORD directives to declare signed data. For more information about these directives, see "Allocating Memory for Integer Variables" in Chapter 4.

MASM 6.1 provides the REAL4, REAL8, and REAL10 directives for declaring floating-point variables. For information on these type directives, see "Declaring Floating-Point Variables and Constants" in Chapter 6 .

Type definitions can now include distance and language type attributes. Procedures, procedure prototypes, and external declarations let you specify the type as a qualified type. A complete description of qualified types is provided in the section "Data Types" in Chapter 1.

u Structures can be nested.

u The names of structure fields need not be unique. As a result, you must qualify references to field names.

u Initialization of structure variables can continue over multiple lines provided the last character in the line before the comment field is a comma.

u Curly braces and angle brackets are equivalent.

SCORE STRUCT
team1 BYTE 10 DUP (?)
score1 BYTE ?
team2 BYTE 10 DUP (?)
score2 BYTE ?
SCORE ENDS

first SCORE {"BEARS", 20, ; This comment is allowed.
"CUBS", 10 }

mov al, [bx].score.team1 ; Field name must be qualified
; with structure name.

You can use OPTION OLDSTRUCTS or OPTION M510 to enable MASM 5.1 behavior for structures. See "Compatibility between MASM 5.1 and 6.1," later in this appendix. For more information on structures and unions, see "Structures and Unions" in Chapter 5.

MASM 6.1 allows the definition of unions with the UNION directive. Unions differ from structures in that all fields within a union occupy the same data space. For more information, see "Structures and Unions" in Chapter 5.

The TYPEDEF directive defines a type for use later in the program. It is most useful for defining pointer types. For more information on defining types, see "Data Types" in Chapter 1, and "Defining Pointer Types with TYPEDEF" in Chapter 3.

MASM 6.1 accepts identifier names up to 247 characters long. All characters are significant, whereas under MASM 5.1, names are significant to 31 characters only. For more information on identifiers, see "Identifiers" in Chapter 1.

In MASM 6.1, a comma at the end of a line (except in the comment field) implies that the line continues. For example, the following code is legal in MASM 6.1:

longstring BYTE "This string ",
"continues over two lines."
bitmasks BYTE 80h, 40h, 20h, 10h,
08h, 04h, 02h, 01h

MASM 5.1 allows a backslash ( \ ) as the line-continuation character if it is the last nonspace character in the line. MASM 6.1 permits a comment to follow the backslash.

The LENGTHOF operator returns the number of data items allocated for a data label. MASM 6.1 also provides the SIZEOF operator. When applied to a type, SIZEOF returns the size attribute of the type expression. When applied to a data label, SIZEOF returns the number of bytes used by the initializer in the label’s definition. In this case, SIZEOF for a variable equals the number of bytes in the type multiplied by LENGTHOF for the variable.

MASM 6.1 recognizes the LENGTH and SIZE operators for backward compatibility. For a description of the behavior of SIZE under OPTION M510, see "Length and Size of Labels with OPTION M510," later in this appendix. For obsolete behavior with the LENGTH operator, see also "LENGTH Operator Applied to Record Types," page 356.

For information on LENGTHOF and SIZEOF, see the following sections in
chapter 5: "Declaring and Referencing Arrays," "Declaring and Initializing Strings," "Declaring Structure and Union Variables," and "Defining Record Variables."

These operators return the high and low words for a given 32-bit operand. They are similar to the HIGH and LOW operators of MASM 5.1 except that HIGHWORD and LOWWORD can take only constants as operands, not relocatables (labels).

Under MASM 5.1, applying the PTR operator to a data initializer determines the size of the data displayed by CodeView. You can still use PTR in this manner in MASM 6.1, but it does not affect CodeView typing. Defining pointers with the TYPEDEF directive allows CodeView to generate correct information. See "Defining Pointer Types with TYPEDEF" in Chapter 3.

With its significant improvements for procedure and jump handling, MASM 6.1 closely resembles high-level - language implementations of procedure calls. MASM 6.1 generates the code to correctly handle argument passing, check type compatibility between parameters and arguments, and process a variable number of arguments. MASM 6.1 can also automatically recast jump instructions to correct for insufficient jump distance.

The PROTO directive lets you prototype procedures in the same way as high-level languages. PROTO enables type-checking and type conversion of arguments when calling the procedure with INVOKE. For more information, see "Declaring Procedure Prototypes" in Chapter 7.

The INVOKE directive sets up code to call a procedure and correctly pass arguments according to the prototype. MASM 6.1 also provides the VARARG keyword to pass a variable number of arguments to a procedure with INVOKE. For more information about INVOKE and VARARG, see "Calling Procedures with INVOKE" and "Declaring Parameters with the PROC Directive" in
Chapter 7.

The ADDR keyword is new since MASM 5.1. When used with INVOKE, it provides the address of a variable, in the same way as the address-of operator (&) in C. This lets you conveniently pass an argument by reference rather than value. See "Calling Procedures with INVOKE" in Chapter 7.

MASM 6.1 contains several directives that generate code for loops and decisions depending on the status of a conditional statement. The conditions are tested at run time rather than at assembly time.

Directives new since MASM 5.1 include .IF, .ELSE, .ELSEIF, .REPEAT, .UNTIL, .UNTILCXZ, .WHILE, and .ENDW. MASM 6.1 also provides the associated .BREAK and .CONTINUE directives for loops and IF statements.
For more information, see "Loops" in Chapter 7 and "Decision Directives" on
page 171.

MASM 6.1 automatically determines the smallest encoding for direct unconditional jumps. See "Unconditional Jumps" in Chapter 7.

If a conditional jump cannot reach its target destination, MASM automatically recasts the code to use an unconditional jump to the target. See "Jump Extending," page 169.

The prologue code generated immediately after a PROC statement sets up the stack for parameters and local variables. The epilogue code handles stack cleanup. MASM 6.1 allows user-defined prologues and epilogues, as described in "Generating Prologue and Epilogue Code" in Chapter 7.

MASM 6.1 simplifies the sharing of code and data among modules and makes the use of include files more efficient.

MASM 5.1 requires that you declare public and external all data and routines used in more than one module. With MASM 6.1, a single EXTERNDEF directive accomplishes the same task. EXTERNDEF lets you put global data declarations within an include file, making the data visible to all source files that include the file. For more information, see "Using EXTERNDEF" in Chapter 8.

MASM 6.1 searches for include files in the directory of the main source file rather than in the current directory. Similarly, it searches for nested include files in the directory of the include file. You can specify additional paths to search with the /I command-line option. For more information on include files, see "Organizing Modules" in Chapter 8.

In MASM 5.1, sensitivity to case is influenced only by command-line options such as /MX, not the language type given with the .MODEL directive. In MASM 6.1, the language type takes precedence over the command-line options in specifying case sensitivity.

The syntax for EXTERN allows you to specify an alternate symbol name, which the linker can use to resolve an external reference to an unused symbol. This prevents linkage with unneeded library code, as explained in "Using EXTERN with Library Routines," Chapter 8.

Several directives in MASM 6.1 enable or disable various aspects of the assembler control. These include 80486 coprocessor instructions and use of compatibility options.

The new OPTION directive allows you to selectively define the assembler’s behavior, including its compatibility with MASM 5.1. See "Using the OPTION Directive" in Chapter 1 and "Compatibility between MASM 5.1 and 6.1," later in this appendix.

The .NO87 directive disables all coprocessor instructions. For more information, see Help.

MASM 6.1 can assemble instructions specific to the 80486, enabled with the .486 directive. The .486P directive enables 80486 instructions at the highest privilege level (recommended for systems-level programs only). For more information, see Help.

The directive PUSHCONTEXT saves the assembly environment, and POPCONTEXT restores it. The environment includes the segment register assumes, the radix, the listing and CREF flags, and the current processor and coprocessor. Note that .NOCREF (the MASM 6.1 equivalent to .XCREF) still determines whether information for a given symbol will be added to Browser information and to the symbol table in the listing file. For more information on listing files, see Appendix C or Help.

Although MASM 6.1 still supports the old names in MASM 5.1, the following directives have been renamed for language consistency:

MASM 6.1 supports all instructions that work with the extended 32-bit registers of the 80386/486. For certain instructions, you can override the default operand size with the W (word) and the D (doubleword) suffixes. For details, see the Reference or Help.

There are significant enhancements to macro functions in MASM 6.1. Directives provide for a variable number of arguments, loop constructions, definitions of text equates, and macro functions.

MASM 5.1 ignores extra arguments passed to macros. In MASM 6.1, you can pass a variable number of arguments to a macro by appending the VARARG keyword to the last macro parameter in the macro definition. The macro can then reference additional arguments relative to the last declared parameter. This procedure is explained in "Returning Values with Macro Functions" in Chapter 9.

With MASM 6.1, you can use REQ or the := operator to specify required or default arguments. See "Specifying Required and Default Parameters" in
Chapter 9.

Within a macro definition, WHILE repeats assembly as long as a condition remains true. Other macro loop directives, IRP, IRPC, and REPT, have been renamed FOR, FORC, and REPEAT. For more information, see "Defining Repeat Blocks with Loop Directives" in Chapter 9.

The EQU directive retains its old functionality, but MASM 6.1 also incorporates a TEXTEQU directive for defining text macros. TEXTEQU allows greater flexibility than EQU. For example, TEXTEQU can assign to a label the value calculated by a macro function. For more information, see "Text Macros" in Chapter 9.

Within a macro definition, GOTO transfers assembly to a line labeled with a leading colon(:). For more information on GOTO, see Help.

At assembly time, macro functions can determine and return a text value using EXITM. Predefined macro string functions concatenate strings, return the size of a string, and return the position of a substring within a string. For information on writing your own macro functions, see "Returning Values with Macro Functions" in Chapter 9.

For more information on predefined macros, see "String Directives and Predefined Functions" in Chapter 9.

MASM 6.1 provides many features that make it easier for you to write assembly code. If you are familiar with MASM 5.1 programming, you may find it helpful to adopt the following list of new programming practices for programming with MASM 6.1. The list summarizes many of the changes covered in the following section, "Compatibility Between MASM 5.1 and 6.1."

u Select identifier names that do not begin with the dot operator (.).

u Use the dot operator (.) only to reference structure fields, and the plus operator (+) when not referencing structures.

u Different structures can have the same field names. However, the assembler does not allow ambiguous references. You must include the structure type when referring to field names common to two or more structures.

u Separate macro arguments with commas, not spaces.

u Avoid adding extra ampersands in macros. For a list of the new rules about using ampersands in macros, see "Substitution Operator" in Chapter 9 and "OPTION OLDMACROS," page 372.

u By default, code labels defined with a colon are local. Place two colons after code labels if you want to reference the label outside the procedure.

MASM 6.1 provides a "compatibility mode," making it easy for you to transfer existing MASM 5.1 code to the new version. You invoke the compatibility mode through the OPTION M510 directive or the /Zm command-line switch. This section explains the changes you may need to make to get your MASM 5.1 code to run under MASM 6.1 in compatibility mode.

In some cases, MASM 6.1 with OPTION M510 does not support MASM 5.1 behavior. In several cases, this is because bugs in MASM 5.1 were corrected. To update your code to MASM 6.1, use the instructions in this section. This usually requires only minor changes.

Many of the topics listed here will not apply to your code. This section discusses topics in order of likelihood, beginning with the most common. In addition, you may have conflicts between identifier names and new reserved words. OPTION NOKEYWORD resolves errors generated from the use of reserved words as identifiers. See "OPTION NOKEYWORD," page 376, for more information.

This section lists the differences between MASM 5.1 and MASM 6.1 due to bug corrections since MASM 5.1.

Except in compatibility mode, MASM 6.1 flags illegal uses of the instruction prefixes LOCK, REPNE, and REPNZ. The error generated for invalid uses of the LOCK, REPNE, and REPNZ prefixes is error A2068:

Table A.1 summarizes the correct use of the instruction prefixes. It lists each string instruction with the type of repeat prefix it uses, and indicates whether the instruction works on a source, a destination, or both.

In MASM 5.1, you can use both single and double quotation marks (' and ") to begin strings in macro arguments. The assembler does not generate an error or warning if the string does not end with quotation marks on a macro call. Instead, MASM 5.1 considers the remainder of the line to be part of the macro argument containing the opening quote, as if there were a closing quotation mark at the end of the line.

To correct such errors in MASM 6.1, either end the string with a closing quotation mark as shown in the following example, or use the macro escape character (!) to treat the quotation mark literally.

; MASM 5.1 code
MyMacro "all this in one argument

; Default MASM 6.1 code
MyMacro "all this in one argument"

MASM 5.1 considers code labels defined with a single colon inside a procedure to be local to that procedure if the module contains a .MODEL directive with a language type. Although the label is local, MASM 5.1 does not generate an error if it is also declared PUBLIC. MASM 6.1 generates error A2203:

If you want to make a label PUBLIC, it must not be local. You can use the double colon operator to define a non-scoped label, as shown in this example:

MASM 5.1 allows a byte argument for the 80386 bit-test instructions, but encodes it as a word argument. The byte form is not supported by the processor.

In MASM 5.1, default values for record fields can range down to -2n, where n is the number of bits in the field. This results in the loss of the sign bit.

MASM 6.1 allows a range of -2n-1 to 2n-1 for default values. Illegal initializers generate error A2071:

MASM 6.1 includes design changes that make the language more consistent. These changes are not affected by the OPTION directive, discussed later in this appendix. Therefore, the changes require revisions in your code. In most cases, the necessary revisions are minor and the circumstances requiring changes are rare.

MASM 5.1 does not require operands to agree in size, as the following code illustrates:

The operands for the MOV instruction do not match in size, yet the instruction assembles correctly. It places the contents of AL into var1 and AH into var2, moving a word of data in one step. If the code defined var1 as a word value, the instruction

would also assemble correctly, copying AL into the low byte of var1 while leaving the high byte unaffected. Except at warning level 0, MASM 5.1 issues a warning to inform you of the size mismatch, but both scenarios are legal.

MASM 6.1 does not accept instructions with operands that do not agree in size. You must specifically "coerce" the size of the memory operand, like this:

MASM 5.1 allows you to declare two or more structures with the same name. Each declaration replaces the previous declaration. However, the field names from previous declarations still remain in the assembler’s list of declared values.

MASM 6.1 does not allow conflicting declarations of a structure. It generates errors A2160 through A2165 for each conflicting declaration. The errors note a specific conflict, such as conflicting number of fields, conflicting names of fields, or conflicting initializers.

MASM 5.1 allows forward references to text macros in specialized cases. MASM 6.1 with OPTION M510 also permits forward references, but only when the text macro is referenced in an expression. To revise your code, place all macro definitions at the beginning of the file.

In some cases, MASM 5.1 accepts HIGH and LOW applied to relocatable memory expressions. For example, MASM 5.1 allows this code sequence:

; MASM 5.1 code
EXTRN var1:WORD
var2 DW 0
mov al, LOW var1 ; These two instructions yield the
mov ah, HIGH var1 ; same as mov ax, OFFSET var1