
                               README.TXT File

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

     (C) Copyright 1993, Microsoft Corporation.  All rights reserved.
                                          
     This document contains release notes for version 6.11 of the
     Microsoft Macro Assembler Professional Development System for
     Microsoft Windows NT(TM) and MS-DOS(R).  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.



===========================< Table of Contents >==========================

     Part 1: Documentation Errata
     ----------------------------

     Part 2: Information on Microsoft CodeView
     -----------------------------------------
             - CV.TXT File
             - CodeView and 32-bit Registers
             - CodeView and .COM Files

     Part 3: Error Messages
     ----------------------
             - 32-Bit Linker Errors
             - ML Error Messages
             - MS-DOS Extender Errors

     Part 4: Pentium Information
     ---------------------------
             - .586 and .586P Directives
             - PENTIUM.TXT File

     Part 5: Tips for Using MASM 6.1x
     --------------------------------
             - ALIAS directive
             - Assembling Files Generated by Compiler
             - CD-ROM Not a Valid Target
             - CMP Instruction Encoding
             - .FPO Directive
             - INVOKE Command
             - LINK and System Resources
             - MOUSE.COM
             - MS-DOS and Windows NT File Compatibility
             - NMAKE and NMAKER
             - Response Files
             - SAMPLES.TXT and NTSAMPLE.TXT
             - Using Control-C to Halt Operation of MASM
             - Using MASM 6.x Structures
             - Using the 32-bit Linker
             - Visual C++ 1.0/Fortran Powerstation 1.0 Compatibility
             -  /WIN32 Switch for H2INC
             - Working with MASM 5.1 Code
             - Working With Microsoft BASIC Far Strings

     Part 6: Known Assembler Bugs
     ----------------------------
             - Exiting from MS-DOS Critical Errors
             - Expression Order in High-Level Conditionals
             - Initializing Nested Structures
             - Span-Dependent Expressions used in Macros
             - Span-Dependent Equates in Macros and EXTERNDEF ABS
             - Span-Dependent Text Equates
             - Using The /link /nologo Command Line Options
             - RET n Does Not Generate Epilogue



====================< Part 1: Documentation Errata >======================


     Environment and Tools, Page 582: LIB Command Line Sample
     --------------------------------------------------------
     The following example, as it appears on page 582, is incorrect:

     LIB FIRST +SECOND, , THIRD

     It should instead read:

     LIB THIRD +FIRST +SECOND


     Environment and Tools, Page 819: Error Message A2156
     ----------------------------------------------------
     The value range given for the first parameter of the PAGE directive
     is incorrect; "...either 0 or a value in the range of 10-255" should
     read "...either 0 or a value in the range of 14-255."
     
     
     Reference, Page 98: LEA is no longer optimized
     ----------------------------------------------
     The MASM 6.1 Reference indicates that the LEA instruction is
     encoded as a MOV when the source operand is a direct memory address.

     In response to programmer requests, MASM 6.1x no longer performs this 
     optimization automatically.  The optimization can be performed by 
     using the OPATTR operator, as shown in the following macro:

          MOVLEA MACRO Dest, Symbol
          IF (OPATTR(Symbol)) AND 08h
               MOV Dest, OFFSET Symbol
          ELSE
               LEA Dest, Symbol
          ENDIF
          ENDM


     Programmer's Guide, Page 156: Using an Emulator Library
     -------------------------------------------------------
     The sample code demonstrating floating-point instructions served
     by an emulator contains the directive .STARTUP. This directive
     should be removed.

     
     Programmer's Guide, Page 202: User-Defined Epilogues & Prologues
     ----------------------------------------------------------------
     The documentation for user-defined epilogue and prologue code reads
     "Your macro function must return the parmbytes parameter."  It
     should read "...the localbytes parameter."


     Programmer's Guide, Page 323: The C++/MASM Interface
     ----------------------------------------------------
     The second sentence in the third paragraph reads: "The linkage 
     specification applies only to called routines, not to external
     variables." It should read "The linkage specification applies to
     called routines and external variables." The last sentence in the
     same paragraph should be removed.
     
     Help for Runtime Error R6921
     ---------------------------------------
     The online help for runtime error R6921 reads "...Possibly the
     CONFIG.SYS file contained a line such as DEVICE=C:\OS\MM386.EXE..."
     The file name should read "C:\DOS\EMM386.EXE".


===============< Part 2: Information on Microsoft CodeView >==============

     CV.TXT File
     --------------------
     Detailed information on configuring CodeView is in the CV.TXT file,
     in the directory in which you installed MASM.


     CodeView and 32-bit Registers
     --------------------------------------------------
     CodeView 4.01 does not support single-stepping through code which
     uses 32-bit registers while a DPMI server is present.  Windows 3.1
     and 386-MAX are examples of DPMI servers.  If you need to single-
     step through 32-bit code, you can exit Windows and use a VCPI server 
     such as EMM386.EXE to run CodeView, or use an alternate debugger 
     such as WDEB386 (available in the Microsoft Windows Software 
     Development Kit).
     

     CodeView and .COM Files
     --------------------------------------------------
     CodeView 4.01 does not show source code when debugging .COM files.  
     If you need to view source code, build your program as a small-model 
     .EXE for debugging purposes.


=========================< Part 3: Error Messages >========================

     32-Bit Linker Errors
     --------------------
     If you attempt to assemble a 16-bit executable, but call the 32-bit
     version of LINK, you will receive a LNKnnnn error message. The
     following output example demonstrates specifically which error 
     messages you may receive:
          
          **********************************************************
          Microsoft (R) 32-Bit Executable Linker Version 1.0
          Copyright (C) Microsoft Corp 1992-93. All rights reserved.

          /z2
          "afile.obj"
          "afile.exe"
          NUL
          LINK : warning LNK4044: unrecognized option "z2"; ignored
          LINK : warning LNK4044: unrecognized option "r"; ignored
          LINK : error LNK1104: cannot open file "afile.exe"
          **********************************************************
     
     You may also receive the warning:

          cvtomf() : warning : 16-bit segment


     If you are building a 16-bit executable, use LINK.EXE included with
     MASM 6.11. If you have the directories for both the 16-bit and
     32-bit linkers included in your PATH, the directory containing the
     16-bit LINK.EXE must be listed before the directory containing the
     32-bit linker.


     ML Error Messages
     -----------------
     Information on ML error messages has been updated for MASM 6.11.
     New ML error messages and warnings can be found in the text file
     ERRMSG.TXT, located in the directory in which you installed MASM.
     For additional information, see "ML Error Messages" in Microsoft
     MASM Environment and Tools. 


     MS-DOS Extender Errors
     ----------------------
     ML.EXE and NMAKE are MS-DOS-extended using DOSXNT and can issue
     a DXnnnn error message. Microsoft DOSXNT MS-DOS Extender error 
     messages and explanations can be found in the text file ERRMSG.TXT 
     in the directory in which you installed MASM.
     

=======================< Part 4: Pentium Information >=====================

     Microsoft MASM 6.11 provides support for the Intel(R) Pentium(TM) 
     processor instructions and timings.

     
     .586 and .586P Directives
     -------------------------
     The .586 directive enables assembly of non-privileged instructions 
     available for the Pentium processor. The .586P directive enables
     privileged instructions in addition to the non-privileged instructions
     for the Pentium.
     
     
     PENTIUM.TXT File
     ----------------
     Descriptions of new Pentium instructions, and a table of Pentium 
     timings for all instructions, can be found in the text file 
     PENTIUM.TXT in the directory in which you installed MASM.


====================< Part 5: Tips for Using MASM 6.11 >===================
     
     ALIAS directive
     ---------------
     The ALIAS directive is not included in the printed documentation
     for MASM 6.11. The ALIAS directive can be used for creating 
     libraries that allow the linker (LINK) to map an old function to 
     a new function.

          Syntax:    ALIAS  <alias> = <actual-name>

     where alias is the alternate or alias name, and actual-name is
     the actual name of the function or procedure. The angle brackets
     are required.

     The ALIAS directive should be used with LINK 5.3 or later and LIB
     3.2 or later.


     Assembling Files Generated by Compilers
     ------------------------------------------
     Many compilers support assembly-language output.  If you experience
     difficulty assembling the output of such compilers, you may need to
     assemble using the /Zm option.  In some cases (for instance, if the
     compiler inserts nondelimited comments or page numbers) it may be 
     necessary to edit the assembly-language output by hand.


     CD-ROM Not a Valid Target
     -------------------------
     A CD-ROM drive is not a valid target for MASM 6.11.


     CMP Instruction Encoding
     ------------------------
     MASM 6.1x uses a different encoding for the CMP <reg8>,<reg8> 
     instruction than MASM 6.0 did.  There is no difference in length or 
     processor timing.

     
     .FPO Directive
     --------------
     The .FPO directive controls the emission of debug records to the
     .debug$F segment or section. This directive was originally 
     included with MASM386 5.10.NT and is not supported by MASM 6.11.
     If you are using both MASM 6.11 and MASM386 5.10.NT, the following
     allows you to continue to implement the .FPO directive:

     IF @version LT 600
     .FPO
     ENDIF
     
     
     
     INVOKE Command
     --------------
     The MASM 6.x INVOKE command does not support transferring control
     between 16-bit and 32-bit code segments. When the assembler
     encounters an INVOKE command in a 16-bit segment, it assumes
     that the procedure being invoked is also in a 16-bit segment; if
     the assembler encounters an INVOKE in a 32-bit segment, it assumes
     that the invoked procedure is also in a 32-bit segment.

     To avoid this problem, push the necessary parameters on the stack
     and make the appropriate call instead of using INVOKE.


     LINK and System Resources
     ------------------------
     You may encounter the following error message when running LINK on 
     Windows 3.1:
          
          System resource exhausted. Abort, Retry, Fail?

     This may occur because LINK opens a large number of files, and the 
     buffer for SHARE may have been exceeded. To fix this problem, edit 
     your AUTOEXEC.BAT, setting the following values for SHARE:

          /L:500 /F:4096

     
     MOUSE.COM
     ---------
     Microsoft Mouse Driver (MOUSE.COM) Version 8.20a is included with
     MASM 6.11. If you have a later version of the Microsoft Mouse
     installed on your system, it is recommended you use it instead of
     the Mouse Driver included with MASM 6.11.
     

     MS-DOS and Windows NT File Compatibility
     ----------------------------------------
     Files installed on the Microsoft Windows NT File System (NTFS) will 
     only run on Microsoft Windows NT.  Files installed on the MS-DOS 
     (FAT) File System will run on MS-DOS, Microsoft Windows, or Microsoft 
     Windows NT.


     NMAKE and NMAKER
     ----------------
     MASM 6.11 includes two versions of the NMAKE project management 
     utility.  NMAKER.EXE is a real-mode version of the utility.  
     NMAKE.EXE is a driver program which first loads the MS-DOS extender 
     DOSXNT into memory, and then runs NMAKER.EXE.  Using the NMAKE.EXE 
     driver will result in faster build times.  Some development tools 
     from other manufacturers may be incompatible with NMAKE.EXE.  If you 
     encounter incompatibilities, use NMAKER.EXE instead.


     Response Files
     --------------
     Information on response files can be found in "ML Command Line 
     Options" in Online help.
     
     
     SAMPLES.TXT and NTSAMPLE.TXT
     ---------------------------------------------
     SAMPLES.TXT contains information about the MASM samples for 
     MS-DOS/Windows; NTSAMPLE.TXT contains information about the 
     samples given for MASM for Windows NT. Both files include 
     information about additional tools you may need to build some 
     of the samples. If you install MASM 6.11 for MS-DOS/Windows and 
     Windows NT or for just Windows NT, and if you choose to install 
     the sample code during the setup process, the files SAMPLES.TXT 
     and NTSAMPLE.TXT are included. If you install MASM 6.11 for MS-DOS/
     Windows only, only SAMPLES.TXT is included.


     Using Control-C to Halt Operation of MASM
     -----------------------------------------------
     MS-DOS applications running under DPMI, such as ML.EXE, may not 
     respond immediately to pressing Control-C.  If you press Control-C, 
     and ^C appears on the screen but you are not returned to MS-DOS, 
     press the Enter key.


     Using MASM 6.x Structures
     --------------------------------------------
     MASM 6.x supports a more powerful syntax for structure definition 
     and usage than previous versions of MASM.  This more powerful 
     syntax is enabled by default.  To use the older syntax, issue 
     the OPTION OLDSTRUCTS directive (see Appendix A of the MASM
     Programmer's Guide for more information).

     Note: use of nested structures requires the new MASM 6.x syntax.
     If you use nested structures, the OPTION OLDSTRUCTS directive will
     be ignored for the structure which is nested.


     Using the 32-bit Linker
     -----------------------
     In order for ML.EXE to call the 32-bit linker included with the 
     high-level language resident on your machine, the option /coff must
     be included in the command line. For example:

     ML /c /coff afile.asm
     LINK -subsystem:console -out:afile.exe afile.obj libc.lib

     The following example shows how to build a DLL:

     ML /c /coff afile.asm
     LINK -entry:DllMain afile.obj -dll -def:afile.def -implib:afile.lib
     

     Visual C++ 1.0/Fortran Powerstation 1.0 Compatibility
     -----------------------------------------------------
     There are known interoperability conflicts using MASM 6.11 with 
     Microsoft Visual C++ 1.0 or Microsoft Fortran Powerstation 1.0.  
     If you wish to do mixed language programming with these products, it 
     is recommended that:

     - you install Visual C++/Fortran Powerstation and MASM 6.11 in 
       separate sub-directories.

     - you place \MSVC or \F32 (your Visual C++ or Fortran Powerstation 
       sub-directory) first on your path statement before \MASM611 (your 
       MASM 6.11 sub-directory).

     - you use NMAKE.EXE from MASM 6.11.  You can do this using various
       methods, such as moving or renaming NMAKE.EXE installed in \MSVC
       or \F32 thus causing the system to continue searching your path 
       and use the NMAKE.EXE in \MASM611.

     Optionally, for MASM 6.11/Visual C++ mixed programming, you may
     use NMAKER.EXE which is installed with both products.

 
     /WIN32 Switch for H2INC
     -----------------------
     Use the /WIN32 switch with H2INC to convert C header files to 
     NT-compatible MASM include files. When you use the /WIN32 switch,
     C int data types are converted to the 4-byte assembler equivalent
     DWORD (signed int data types are converted to SDWORD). Without the 
     /WIN32 switch, H2INC converts int data types to 2-byte WORD (and 
     signed int data types to SWORD).


     Working with MASM 5.1 Code
     --------------------------
     MASM 6.x offers major advances over previous versions of MASM.
     Some of these improvements require changes that make MASM 5.1
     source code incompatible with MASM 6.x. To provide compatibility
     with code written for MASM 5.1, MASM 6.x allows you to access
     MASM 5.1 compatibility code in three ways:
     
          - By using the conversion driver MASM.EXE. MASM.EXE converts
            your existing command-line options to the new syntax, adds
            the compatibility option /Zm, and invokes ML.EXE.
          
          - By using ML.EXE with the /Zm option. You also need to
            convert command-line options to the new syntax.
          
          - By placing the statement OPTION M510 at the beginning of
            each file.
            
     In most cases, using the /Zm option or OPTION M510 will be the best
     solution for assembling existing code. If you prefer to modify your
     code so it can be assembled without /Zm or OPTION M510, do the
     following:
     
     1. Add the appropriate OPTION directives to your code.

        - Always add the following:

          OPTION OLDSTRUCTS ; Supports old-style structures
          OPTION OLDMACROS  ; Supports old-style macros
          OPTION DOTNAME    ; Supports naming identifiers with
                            ; a leading dot [.]

        - If your code does not specify the .386 or .386P directive, add
          the following:

          OPTION EXPR16     ; Use 16-bit precision in expressions

        - If your code does not contain a .MODEL directive, add the
          following:

          OPTION OFFSET:SEGMENT ; Specifies that the OFFSET operator
                                ; defaults to segment-relative rather
                                ; than group-relative

        - If your code does not contain a .MODEL directive or if the
          .MODEL directive does not specify a language, add the following:

          OPTION NOSCOPED       ; Makes code labels global rather than
                                ; local to the procedure in which they
                                ; appear
          OPTION PROC:PRIVATE   ; Makes code labels defined with PROC
                                ; local unless specified otherwise

     2. Once your code assembles with the OPTION directives, remove each 
        OPTION directive, one at a time, and reassemble the code after you 
        remove each one.

        Usually, it is best to remove the OPTION directives in the 
        opposite order in which you added them. In some cases, you may 
        decide that you prefer the MASM 5.x compatibility behavior 
        instead of the new MASM 6.x behavior. When this is true, do not 
        remove the corresponding OPTION statement from your code. 
        
     For more information on assembling MASM 5.1 code, see Appendix A 
     of the MASM Programmer's Guide.

     
     Working With Microsoft BASIC Far Strings
     ---------------------------------------------
     The BASIC runtime function StringAssign does not correctly handle
     strings of zero length.  Instead of calling StringAssign to convert
     a zero-length string, simply return a near pointer to a doubleword 
     with the value 0.



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

     Exiting from MS-DOS Critical Errors
     --------------------------------------------------
     MS-DOS critical errors, such as attempting to assemble a file on
     a drive which does not exist or is empty, produce the "Abort, Retry
     or Fail?" error message.  Selecting "Abort" when running MASM in 
     MS-DOS may cause memory to be corrupted.  This problem does not 
     occur when running MASM in Windows.  To avoid this problem, select
     "Retry" or "Fail", as appropriate.


     Expression Order in High-Level Conditionals
     --------------------------------------------------
     Comparisons in high-level conditionals cannot begin with a literal.
     For instance, this comparison causes an error:

          .IF 1 == AX

     but this works properly:

          .IF AX == 1


     Initializing Nested Structures
     --------------------------------------------------
     If one structure is nested within another, the inner structure's
     initializer list must either be empty or include a comma between
     every field.  For example, the structure INFO declared on page 123 
     of the Programmer's Guide contains a structure of type DISKDRIVES,
     which in turn contains three BYTE fields.  An object of type INFO
     could be initialized as:

          Info1 INFO { , , , , { }}      ; Inner initializer list is blank

     or as:

          Info1 INFO { , , , , {1, 2, }} ; Commas for all three fields

     but not as:

          Info1 INFO { , , , , {1, 2 }}  ; Error: missing last comma


     Span-Dependent Expressions used in Macros
     --------------------------------------------------
     MASM 6.1x evaluates macro expressions only on the first pass of 
     assembly, but code and data are reevaluated on subsequent passes.
     Because of this, macro expressions which depend on the span between
     two addresses may not evaluate correctly.  For instance, the
     following code will not evaluate correctly:

          Label1:
               JMP Label2
          Label2:

          REPEAT Label2 - Label1  ; Evaluates incorrectly
               INC AX
          ENDM

     View the listing file to determine if a questionable macro expression
     was evaluated as desired.


     Span-Dependent Equates in Macros and EXTERNDEF ABS
     ---------------------------------------------------
     The ABS operator causes an identifier to be exported as a relocatable
     unsized constant (see Programmer's Guide page 220).  If ABS is used
     with EXTERNDEF within a macro, and the constant being exported
     depends on the difference between two addresses, the constant may not
     be exported correctly.  In some cases, the listing file will show the
     correct value, but the value in the resulting .obj will be incorrect.
     For instance, the following code will not evaluate correctly:

          EXTERNDEF TableSize:ABS  ; Will not be exported correctly

          MAKETABLE MACRO
          Table1 LABEL BYTE
               DB 0, 1, 2
          TableSize EQU $-Table1
          ENDM

          SEG1 SEGMENT
          MAKETABLE
          SEG1 ENDS

     To avoid this problem, either use the 'PUBLIC' directive in place of 
     'EXTERNDEF', or put a label before the equate, within the macro.


     Span-Dependent Text Equates
     --------------------------------------------------
     The TEXTEQU operator is evaluated on the first assembly pass.  If
     TEXTEQU is used with an expression that depends on the difference
     between two addresses, the resulting constant may be incorrect.
     For instance, the following code will not evaluate correctly:

          Label1:
               JMP Label2
          Label2:
          WrongNum TEXTEQU %Label2-Label1 ; WrongNum will be incorrect


     Using The /link /nologo Command Line Options
     ---------------------------------------------------------
     The /link command line option for ML causes all following parameters
     to be passed to the linker.  If the /nologo command line option for
     is passed to the linker, the linker may parse other parameters
     incorrectly.  To avoid this problem, use the /nologo command line 
     switch for ML rather than passing it to the linker.  For instance,
     replace:

          ML hello.asm /link /nologo MYLIB.LIB

     with:

          ML /nologo hello.asm /link MYLIB.LIB

     Alternately, you may use the NMAKE utility to automate building
     your project.


     RET n Does Not Generate Epilogue
     ---------------------------------------------------------
     In MASM 5.1, using RET followed by a constant would cause epilogue
     code to be generated.  MASM 6.1x does not generate epilogue code in
     this case.
