README.DOC File

             Release Notes for the Microsoft(R) Macro Assembler
                Professional Development System, Version 6.0b

                  (C) Copyright Microsoft Corporation, 1992
     This document contains release notes for version 6.0b of the
     Microsoft Macro Assembler Professional Development System for
     MS-DOS(R) and the Microsoft Operating System/2 (MS(R) OS/2). The
     information in this document and in the Microsoft Advisor (online
     help) is more up-to-date than that in the manuals.
     Microsoft improves its languages documentation at the time of
     reprinting, so some of the information in this file may already be
     included in your manuals.

================================< Contents >================================

     This file has 9 parts:
               Part     Contents
               ----     --------
               1        Updated Files in MASM 6.0b

               2        Assembler Update Notes

               3        Information for MASM 5.1 Programmers

               4        Notes on "Installing and Using"

               5        Notes on "MASM 6.0 Reference"

               6        Notes on "MASM 6.0 Programmer's Guide"

               7        Using the DOS-Extended Assembler

               8        Changes to CMACROS.INC

               9        Known Assembler Bugs

======================< Part 1: Updated Files in MASM 6.0b >================

     Below is a list of the files that have changed in this release of
     the Macro Assembler:

        ML.EXE         DOS-hosted assembler
        ML.EXE         OS/2-hosted assembler
        ML.ERR         Error text file for both DOS and OS/2 assemblers
        MLX.EXE        DOS-extended driver for DOS-hosted assembler
        MASM.EXE       MASM 5.1 compatibility driver
        H2INC.EXE      C header file to MASM include-file translator
        H2INC.ERR      Error text file for H2INC.EXE
        CREF.EXE       Source Browser based cross-reference utility. (NEW)
        PROLOGUE.INC   Predefined function prologues and epilogues
        DOS.INC        Predefined DOS function macros
        CMACROS.INC    C-styled assembly macros (MASM 5.1 compatible)
        CMACROS.NEW    Same as CMACROS.INC, but uses MASM 6.0 features (NEW)
        BELL.C         TSR example program
        BELL.MAK       TSR example program
        SNAP.ASM       TSR example program
        QPEX.ASM       QuickPascal mixed-language example
        OS2.LIB        OS/2 development libraries
        API.LIB        OS/2 development libraries
        APILMR.OBJ     OS/2 development libraries
        SMARTDRV.EXE   DOS-hosted disk caching software
        SMARTDRV.DOC   SMARTDRV.EXE Documentation
        RAMDRIVE.SYS   DOS-hosted memory resident disk emulator
        HIMEM.SYS      Memory expansion software
        MOUSE.COM      DOS-hosted mouse driver program

====================< Part 2: Assembler Update Notes > =====================

     Corrections Made in MASM 6.0b

     - The high-level CALL directive INVOKE can now be used as the
       first statement of a procedure.

     - MASM.EXE can now invoke MLX.EXE by using the /Q command-line
       option.  MASM.EXE still invokes ML.EXE when the /Q option is
       not used.

     - Code and data alignment problems are corrected.

          - If the ALIGN directive was used with a value greater than
            2, the bytes representing the instructions that were
            generated for the padding (mov ax, ax) were reversed.

          - If an ALIGN directive immediately followed any composite data
            declaration (i.e. DUP, STRUCT, etc.) the results of the ALIGN
            directive would be incorrect.

     - Structure padding is now correct.

     - Improvements were made to the MLX.EXE DOS Extender.

     - Increased CodeView(R) information capacity is now available.

     - COMM directive syntax corrections were made.

     - ORG $ + X, where X is a constant, no longer effects ORG directives
       found later in the source file.

     - Miscellaneous problems in listing files are corrected.

     Calling Convention Changes
     Changes were made to the STDCALL calling convention after MASM 6.0
     was shipped.  These changes are reflected in MASM 6.0b.  To maintain
     the previous use of STDCALL, use the new OPTION directive:


     Below is a chart describing all of the calling conventions found in
     MASM 6.0b.

        For the procedure func(a1,a2, ... an), the following chart
        describes the results when used with the calling convention
        found on the left side.

                                  for Stack        Argument     VARARG
        Convention     Name        Cleanup        Push Order    Allowed
        ----------     -----     -----------    -------------   -------
        C              _func     caller         right-to-left     Yes

        BASIC          FUNC      callee         left-to-right     No

        SYSCALL        func      callee         right-to-left     Yes

        STDCALL (16)   _func@N   callee         left-to-right     No

        STDCALL (32)   _func@N   callee         right-to-left     No

        OLDSTDCALL     _func     caller/callee* right-to-left     Yes

          STDCALL Naming Note
          In addition to the prefixed underscore, STDCALL also adds
          the suffix, @N, where N is the total number of bytes that
          will be pushed onto the stack.

          Also, note that argument push order differs between
          16-bit and 32-bit procedures.

          The responsibility for cleaning the stack is always on the
          callee, unless the procedure uses VARARG's, in which case
          the caller is responsible for cleaning the stack.

     MASM 6.0 did not include the cross-reference CREF.EXE, because the
     Programmer's Workbench included the Source Browser (a more full-featured
     cross-reference utility).  However, many MASM programmers need the
     features available in CREF.  To that end, we have included a new
     release of CREF.EXE.  This new CREF uses the same files that are used
     by the Source Browser and produces reports very similar to those
     created by previous releases.

     For more information, read the text file CREF.DOC, located in
     the same directory as CREF.EXE (default directory is \MASM600\BINB).

===============< Part 3: Information for MASM 5.1 Programmers >=============

     "Quick Start" booklet

     If you have programs that assemble with previous versions of MASM,
     this booklet will help you use MASM 6.0.

=================< Part 4: Notes on "Installing and Using" >================

     Installation Program Notes

        - Make sure that your TMP environment variable is set to a
          fully qualified path (such as C:\TMP) before running SETUP.

        - Use "SETUP /M" if you are using a monochrome display adapter
          as your primary display.

        - Under OS/2, if you are already running QuickHelp as a keyboard
          monitor, disable it before running SETUP so that it can copy
          new versions of QuickHelp and MSHELP.DLL to your hard disk.

     Configuring Extended Memory for the CodeView Debugger

     When creating a .PIF file for CodeView, make sure you specify
     the following command-line options:

        Mode       Option
        ----       ------
        Real       /d
        Standard   /d
        Enhanced   /d (or /e if expanded memory is available)

     Page    Note
     ----    ----

     26      The file type indicator for MASM source code in Table 3.1
             is incorrect. Rather than "ASM", the indicator should be

     56      The code fragment in the Section "Debugging HELLO.EXE", should

                    MOV ah, 0ffh     ;The register was ax, and is now ah
                    int 21h

==================< Part 5: Notes on "MASM 6.0 Reference" >=================

     Page    Note
     ----    ----

     16      MASM /D Option
             The /D Option is translated as follows:

             /D        Creates a Pass 1 listing. Translated to /Fl /Sf.

     17      ML /VM Option
             /VM       Enables virtual memory under MS-DOS.

     33      EXITM Directive
             The EXITM directive takes an optional textitem, not an

     152     XCHG Instruction
             The second example line should be as follows:

             xchg  dl, dh

==============< Part 6: Notes on "MASM 6.0 Programmer's Guide" >============

     Reserved Words

     Add this paragraph to the description of reserved words in Section
     1.21, "Reserved Words," and Appendix D, "MASM Reserved Words":

     With the /Zm command-line option or 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
     when using processor selection directives less than .386.

     Structure Example

     Change the example in Section, "Indirect Operands with 16-
     and 32-bit Registers" to read:

           mov     bx, OFFSET students
           mov     ax, 4
           mov     di, SIZE STUDENT
           mul     di
           mov     di, ax
           mov     al, (STUDENT PTR[bx+di]).year

     Scaling Register Example

     Change this example line in Section, "Indirect Memory Operands
     with 32-bit Registers":

           mov     eax,[ebp*2]     ; EBP base (only - seg SS)

     should be:

           mov     eax,[ebp*2]     ; no base (scaled - seg DS)

     Data Type Size

     The data type table in Section 4.1.1, "Allocating Memory for Integer
     Variables" should show that the size of a variable defined with the
     DWORD or SDWORD initializer is 4 bytes.

     Stack Variable Labels

     In Section, "Saving Operands on the Stack," brackets
     are missing in the argument in the last sentence. Change
     this paragraph:

     If you use these stack values often in your program, you may
     want to give them labels. For example, you can use TEXTEQU to
     create a label such as "count TEXTEQU <bp-6>".

     to this:

     If you use these stack values often in your program, you may
     want to give them labels.  For example, you can use TEXTEQU to
     create a label such as "count TEXTEQU <[bp-6]>".

     ALIGN, EVEN, and ORG in Structures and Unions

     Add this paragraph to Section 5.2, "Structures and Unions":

     The ALIGN, EVEN, and ORG directives can be used during structure
     definition to modify how offsets of elements are defined. The EVEN
     and ALIGN directives will round the current field offset up to the
     specified align value by inserting padding bytes into the skipped
     space. The ORG directive may be used to change the current field
     offset to a new value, either positive or negative. If the ORG
     directive is used in a structure definition, you cannot create an
     instance of the structure.

     Nested Structure Example

     Change this line in the first example of Section 5.2.2, "Defining 
     Structure and Union Variables":

           ITYPE     UNION

     should be:

           UNION     ITYPE

     Indirect Operands Example

     In Section, "Indirect Operands," the line:

           jmp ebx     ; FAR32 jump

     should be:

           jmp ebx     ; NEAR32 jump

     Decision Directives Example

     In Section, "Decision Directives," the line:

           .IF  cx = 20

     should be:

           .IF  cx == 20

     VARARG Example

     In Section, "Using VARARG," the line:

            dec    arg1           ;Point to next argument

     should be:

            dec    argcount       ;Point to next argument

     Indirect Procedure Invocation Example

     Part of the first example in Section, "Invoking Procedures
     Indirectly," is incorrect. Here is the corrected code:

           mov      bx, pFunc                  ; pFunc is the function table
           mov      si, Num                    ; Num contains 0 or 2
           INVOKE   FUNCPTR PTR [bx+si], 1, 1  ; Selects proc1 or proc2

     The sentence that says:

           You can also use ASSUME to accomplish the same task. The ASSUME
           statement associates the type PFUNC with the BX register.

     should be:

           You can also use ASSUME to accomplish the same task. In the
           sample below, the ASSUME statement associates the type FUNCPTR
           with the BX register.

     In the example that follows, add the following line after the ASSUME:

           mov      bx, pFunc

     Also, change the INVOKE line to read:

           INVOKE   [bx+si], 1, 1

     DOS Interrupt Example

     In Section 7.4.1, "Calling DOS and ROM-BIOS Interrupts," the line:

           msg      BYTE    "This writes to the screen",$

     should be:

           msg      BYTE    "This writes to the screen$"

     DOS Interrupt Redefinition

     In Section 7.4.2, "Replacing or Redefining Interrupt Routines,"
     the numbers 25 and 35 should be replaced by 25h and 35h respectively.

     In the following example, the line:

           .MODEL   LARGE, C, DOS

     should be:

           .MODEL   LARGE, C, OS_DOS

     EXTERNDEF Diagram

     In Figure 8.1, "Using EXTERNDEF for Variables," the line:

           mov    ax, array1[12]

     should be:

           mov    al, array1[12]

     Public and EXTERN Diagram

     In Figure 8.3, "Using PUBLIC and EXTERN," the example file MOD2.ASM
     should be:

           .MODEL small, Pascal
           EXTERN var:BYTE, BuildTable:NEAR

            mov   al, Var
            call  BuildTable

     EXTERN Library Example

     In Section 8.4.2, "Using EXTERN with Library Routines," the line:

           EXTERN init(dummy)

     should be:

           EXTERN init(dummy):PROC

     Expansion Operator (%)

     The last paragraph of Section, "The Expansion Operator with
     Constants" is incorrect.  Macro arguments cannot be expanded
     constants alone; they must be enclosed in angle brackets (<>).

     FOR Loops

     In Section 9.4.3, "FOR Loops and Variable-Length Parameters," the

           FOR    arg, arglist

     should be:

           %FOR   arg, arglist

     SIZESTR Result

     The description of the SIZESTR directive in Section 9.5, "String
     Directives and Predefined Functions" should say that SIZESTR
     assigns a numeric value, rather than a string.

     String Directive Example

     In Section 9.5, "String Directives and Predefined Functions," the
     RestoreRegs macro should be:

           RestoreRegs MACRO
              LOCAL regs
               %FOR regs,regpushed      ;;Pop each register
                 pop regs


     The table in Section 9.7.2, "Testing for Argument Type and 
     Environment" should be as follows:

     Option     Description
     ------     -----------
     ASSUMES    Saves segment register information
     LISTING    Saves listing and CREF information
     CPU        Saves current CPU and processor
     RADIX      Saves current default radix
     ALL        All of the above

     LINK Wildcards

     In Section, "Wild Cards," the example description block
     should be:

           project.exe : *.obj
              LINK $**;

     New Anonymous Bit-Field Syntax
     Add these paragraphs to Section 16.3.5, "Bit Fields":

     H2INC translates anonymous bit fields by padding with a tag
     corresponding to the bit position.

     For example,

          struct s
             int :8;
             int j:8;


          s      RECORD  j@s:8,

     Basic/MASM Far Externs

     Add these paragraphs to Section 20.3.3, "The Basic/MASM Interface":

     When interfacing with Basic, all EXTERNs that are far must be
     declared outside of a code or data segment.

     This is incorrect:

            .MODEL     medium
            EXTERN     StringAddress:FAR

     This is correct:

            .MODEL     medium
            EXTERN     StringAddress:FAR

     New Command-line Options

     Add these paragraphs to Appendix C, "Generating and Reading Assembly

     With the PAGE directive, the default page length is 0 (infinite), and
     the default page width is 0 (infinite). The allowable value ranges are
     0 and 60-255 for page width, 0 and 10-255 for page length.

     With the /Sf option, a first-pass listing will be generated even if
     a fatal error occurs. The symbol table will be appended onto the end
     of the listing file unless you give the /Sn option.

     The first-pass listing is controlled by the same set of commands that
     are used with the final listing.

     Additional Error Messages

     Add these new or changed error messages to Appendix F, "Error

     MASM fatal error A1006

     invalid command-line option: 'option'

     ML did not recognize the given parameter as an option.

     This error is generally caused when there is a syntax error on the
     command line. It can also be generated by trying to assemble multiple
     assembly-language files on the MLX driver command line.

     MASM fatal error A1017

     out of near memory

     There was insufficient memory to assemble the program.

     One of the following may be a solution:

        - If you are using the NMAKE utility, try using NMK or
          assembling outside of NMAKE.

        - in PWB, try exiting and assembling using ML.

        - In OS/2, try increasing the swap space.

        - In DOS, remove terminate-and-stay-resident (TSR) software.

        - If you have extended memory available, use the MLX.EXE driver.

        - Change CONFIG.SYS to specify a lower number of buffers (the
          BUFFERS= command) and fewer drives (the LASTDRIVE= command).

        - Eliminate unnecessary INCLUDE directives.

     MASM fatal error A1019

     invocation failed : retry command line with /VM option

     ML tried to restart itself with the /VM option but failed.

     Enter the ML command line again, but add the /VM virtual-memory
     option explicitly.

     MASM error A2007

     non-benign record redefinition

     A RECORD definition conflicted with a previous definition.

     One of the following occurred:

        - There were different numbers of fields.

        - There were different numbers of bits in a field.

        - There was a different label.

        - There were different initializers.

     MASM error A2202

     illegal use of segment register

     You cannot use segment overrides for the FS or GS segment registers
     when generating floating-point emulation instructions with the /FPi
     command-line option or OPTION EMULATOR.

     MASM error A2203

     cannot declare scoped code label as PUBLIC

     A code label defined with the "label:" syntax was declared PUBLIC.

     Use the "label::" syntax, the LABEL directive, or OPTION NOSCOPED
     to eliminate this error.

     MASM error A2204

     .MSFLOAT directive is obsolete : ignored

     The Microsoft Binary Format is no longer supported.

     You should convert your code to the IEEE numeric standard, which is
     used in the 80x87-series coprocessors.

     MASM error A2205

     ESC instruction is obsolete : ignored

     The ESC (Escape) instruction is no longer supported. All numeric
     coprocessor instructions are now supported directly by the assembler.

     MASM warning A4005

     unknown default prologue argument

     An unknown argument was passed to the default prologue.

     The default prologue understands only the FORCEFRAME and LOADDS

     MASM warning A4013

     line number information for segment without class 'CODE'

     There were instructions in a segment that did not have a class
     name that ends with "CODE". The assembler did not generate
     CodeView information for these instructions.

     CodeView cannot process modules with code in segments with
     class names that do not end with "CODE".

     MASM warning A4014

     instructions and initialized data not supported in AT segments

     An instruction or initialized data was found in a segment defined
     with the AT attribute. The code or data will not be loaded at run

     Data in AT segments must be declared with the ? initializer.

     MASM warning A4015

     /VM ignored in Windows enhanced mode; use MLX.EXE for extra capacity

     The /VM virtual memory command-line option was used explicitly or 
     implicitly inside an enhanced-mode DOS box. The /VM option was

     Use the MLX DOS-extended assembler to assemble large .ASM files
     from a DOS box.

     MASM warning A6004

     procedure argument or local not referenced

     You passed a procedure argument or created a variable with the LOCAL
     directive that was not used in the procedure body.

     Unnecessary parameters and locals waste code and stack space.

     MASM warning A6005

     IF condition may be pass-dependent

     Under the /Zm command-line option or the OPTION M510 directive,
     the value of an IF condition changed between passes.

     This error message may indicate that the code is pass-dependent and
     must be rewritten.

     H2INC fatal error HI1801

     incomplete model specification

     Only part of a custom memory-model specification was specified on
     the command line.

     When you specify a custom memory model with the /A command-line
     option, you must specify code pointer distance, data pointer distance,
     and DS register setup. This error is equivalent to the D2013 error
     message for CL.

=================< Part 7: Using the DOS-Extended Assembler >===============

     MLX: The DOS-Extended Assembler

     There is a new DOS-extended driver for ML called MLX. MLX loads
     ML.EXE into high memory so that the assembler takes up very little
     space in the first 640K of memory.

     MLX uses extended memory to run ML in protected mode. If you have
     multiple extended memory drivers available, MLX will select the
     driver to use in this order:

       - DPMI
       - VCPI
       - XMS

     The HIMEM.SYS XMS driver is included in the MASM 6.0 package and
     is automatically copied by setup into the real-mode executables
     directory as MLX.EXE. To use HIMEM.SYS, put the following line
     into your CONFIG.SYS file:

       DEVICE = <path>HIMEM.SYS

     where <path> is the path to the location of HIMEM.SYS.

     Use MLX only if running ML with the /VM virtual-memory option fails
     due to an out-of-memory error. Because it runs in real mode, ML
     with the /VM command-line option can run significantly faster than

     MLX Requirements

     MLX requires an active DPMI, VCPI or XMS driver and at least 384K
     of available extended memory to operate.

     Differences between ML and MLX

     The MLX DOS-extended driver can assemble only one source file at
     a time. You must split multiple-file assemblies into several
     invocations of MLX.

     If you want to use MLX from the PWB command line, you must manually
     change your makefile to reflect the name of the MLX driver. Change
     the line:

           ASM = ML


           ASM = MLX

     MLX and EMM386.EXE

     If you are using EMM386.EXE with the NOEMS option, the MLX driver
     reports error R6921 - DOSX16 no expanded memory under VCPI host. To
     use MLX with EMM386, replace "NOEMS" with "512 RAM". For example:

     REM Old EMM386 statement
     DEVICE=C:\WINDOWS\EMM386.EXE x=D800-DFFF noems

     REM Replacement EMM386 statement

     Note: The EMM386 options apply only if you are running MLX outside
     of Windows. If you are running MLX in a Windows DOS Box, MLX uses
     the Windows DPMI server.

======================< Part 8: Changes to CMACROS.INC >====================

     Using CMACROS.INC

     There is a new MASM 6.0-compatible version of CMACROS.INC included
     with the assembler. If you work with the Windows 3.0 Software
     Development Kit, or the C 6.0 or FORTRAN 5.0 startup code, use the 
     new version of CMACROS.INC.

     C and FORTRAN Startup Sources

     To build the C or FORTRAN startup sources, change the ASMFLAGS line
     of MAKEFILE from:

           ASMFLAGS= -Mx -Dmem_$(MODEL) -I$(INC)


           ASMFLAGS= -Mx -Dmem_$(MODEL) -I$(INC) -DMS_STARTUP

=====================< Part 9: Known Assembler Bugs >===================

     Ambiguous Radix Characters

     The assembler accepts numeric characters outside the range of the
     current radix.  These characters are given their appropriate
     values but are handled under the current radix.  For example,

            .RADIX 10
            mov    ax, 1F
            mov    bx, 1Fh

     loads ax with 25 (10 from the tens digit and 15 from the ones digit).
     The bx register is loaded properly.

     Structure Members with Decision Directives

     When using pointers to structures in a decision directive (such as
     .IF or .WHILE), you must simplify the expression with a type
     definition.  For example,

           .WHILE (MyStruct PTR [bx]).Member1 != 4096

     should be rewritten as:

           StructPointer TYPEDEF PTR MyStruct
           ASSUME BX:StructPointer
           .WHILE [bx].Member1 != 4096

     SIZEOF and LENGTHOF Operators with Structure Members

     Expressions applying SIZEOF and LENGTHOF to structure members can
     have problems when another SIZEOF or LENGTHOF expression follows.
     There are two ways to avoid the error:

     - Place the SIZEOF (or LENGTHOF) 'structmember' expression at the
       end of the line.

     - Separate the expression through the use of an equate.

     The following example illustrates both the circumstances that can
     cause this problem and the workaround:

     .model small


     ; Define a struct
     MyStruct   struct
     aa         byte    ?
     bb         byte    ?
     MyStruct   ends

     xx         db      ?
     yy         db      ?

     cMyStruct equ sizeof MyStruct.aa

     ; problem cases
             mov     al,sizeof MyStruct.aa + sizeof yy
             mov     al,sizeof MyStruct.aa + sizeof MyStruct.bb

     ; solution cases
             mov     al,sizeof yy + sizeof MyStruct.aa
             mov     al,cMyStruct + sizeof MyStruct.bb


     The solution cases are rewrites of the problem cases. The first
     solution works because SIZEOF appears at the end of the line. The
     second solution is a case where the size of two structure members
     must be obtained, precluding the first kind of solution. In such a
     case, use an equate for all but the last SIZEOF or LENGTHOF in the

     Address Spans as Constants

     Offset calculations may differ between passes, so comparisons with
     constants should be avoided.  For more information, see Section
     A.2.1.3, "Code Requiring Two-Pass Assembly," in the Programmer's 
     Guide manual.

     Virtual-Memory Assembly in a Windows DOS box

     The /VM virtual memory command-line option is not allowed when 
     running in a Windows enhanced-mode DOS box.  Use MLX.EXE if you
     need more assembler capacity.