readme.txt

mas for 8086 microprocessor

	  When you are creating a 32-bit application, you must link 
	  separately with a 32-bit linker. To prepare your object files 
	  for 32-bit linking, assemble using the following switches:
	  
	  - /c (assembles without linking)
	  - /coff (causes object files to be created in Windows NT-
	    compatible common object file format)
	    
	  After assembling, link with your 32-bit linker. Refer to the 
	  documentation included with your particular 32-bit linker for 
	  specific information and instructions. In addition, the sample
	  Windows NT applications in \SAMPLES\NTSAMPLE demonstrate the use 
	  of /c, /coff, and a 32-bit linker.

	  GROUP Directive and Flat-Model Programming
	  ------------------------------------------
	  The GROUP directive has no effect when used in 32-bit flat-model
	  programming. It is recommended that you not use the GROUP 
	  directive when programming in flat model. Using the GROUP 
	  directive with /coff will result in an error.

	  Structure Packing Issues for Mixed Language Programming
	  -------------------------------------------------------
	  Microsoft MASM uses /Zp1 as it's default setting for structure 
	  packing; this means that structures are not packed. Other 
	  languages may use other default settings for packing. For 
	  example, Microsoft C/C++ compilers prior to Visual C++ 32-bit 
	  edition use /Zp2; Visual C++ 32-bit edition uses /Zp8 as the 
	  default. Modules built using different structure packing may not 
	  be able to share structure data items, so care must be taken 
	  when using structures in mixed language programs.

	  The packing size is a maximum, not a fixed, packing value. This 
	  means that a member must have a size equal to or larger than the 
	  packing limit before any packing is done. 

	  /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).

    
     CD-ROM Not a Valid Target
     -------------------------
     A CD-ROM drive is not a valid installation target for MASM 6.11. Setup
     may incorrectly list a CD-ROM drive on the target drive list. 


     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.

     
     Debugging MASM Applications under Visual C++, 32-bit Edition, 
     or Fortran PowerStation, 32-bit Edition
     -------------------------------------------------------------
     When debugging a pure MASM application under the 32-bit editions of
     Visual C++ or Fortran PowerStation, you must link in the library 
     file (.LIB) provided with these high-level languages (LIBC.LIB in 
     Visual C++, LIBF.LIB with Fortran PowerStation). If you do not use 
     the .LIB file included in the high-level language, you will receive 
     an "Access Violation" error message when you attempt to run a MASM 
     application in either the 32-bit Visual C++ or 32-bit Fortran 
     PowerStation integrated development environment.
     
     
     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.


     Multi-File Assembly with MASM.EXE
     ---------------------------------
     When assembling multiple files with MASM.EXE, you must terminate the
     command-line with a semi-colon or a comma (for example, MASM *.asm;). 
     Failure to do this may cause the program to appear to hang if you are 
     running Microsoft Windows NT. If this does occur, you can terminate 
     the program with Ctrl+C.
     

     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 is not included in the MASM 6.10 manuals;
     however, this information can be found in "ML Command Line Options" 
     in On-line 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 choose to install the sample code during the 
     setup process, both SAMPLES.TXT and NTSAMPLE.TXT are included. 
     SAMPLES.TXT can be found in the \MASM611\SAMPLES subdirectory;
     NTSAMPLE.TXT can be found in the \MASM611\SAMPLES\NTSAMPLE
     subdirectory.


     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.


     Visual C++ 1.0/Fortran PowerStation 1.0 Compatibility
     -----------------------------------------------------
     There are specific steps you must take to use MASM 6.1x 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.1x in 
       separate sub-directories.

     - You place \MSVC\BIN or \F32\BIN (your Visual C++ or Fortran 
       PowerStation sub-directory) first on your path statement before 
       \MASM611\BIN (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.1x/Visual C++ mixed programming, you may
     use NMAKER.EXE which is installed with both products.

     When using the LINK utility included with Visual C++ 1.0, you may 
     encounter one or both of the following warnings:

	  LINK : warning L4017: /r : unrecognized option name; option 
				     ignored
	  CVPACK : warning CK4007 : unrecognized option /x; option 
				    ignored
     
     These warnings do not affect the resulting program and should be
     ignored.
     
 
     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. You also need to convert command-line options
            to the new syntax.
	    
     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.


     .FPO Directive
     --------------

     FPO stands for Frame Pointer Omission. The .FPO directive is a feature 
     added to MASM386 5.10.NT that controls the emission of debug records 
     to the .debug$F segment or section of the object file. These records 
     are the same records that the Microsoft Visual C++ 1.10 or Microsoft 
     Fortran PowerStation compilers emit when they perform frame pointer 
     elimination under /Oy and /Ox optimization control, respectively. 
     Unlike the compiler, MASM never performs any such optimization. it 
     simply passes on the information supplied by the programmer within 
     this directive to the object file.

     The .FPO directive does not have to be used in order to debug assembly 
     programs under the Microsoft Visual C++ 1.10 or Microsoft Fortran 
     PowerStation debuggers whether they are stand alone Windows NT
     applications or mixed language C\Assembly or Fortran\Assembly Windows 
     NT applications. This directive has been implemented to provide better 
     backward compatibility with assembly code written for MASM386 5.10.NT, 
     which is provided with the Windows NT DDK.

     The FPO directive should only be used on naked procedures or those 
     procedures not declared with proto and called with invoke. Also you do 
     not need to use the .FPO directive to debug naked procedures or on 
     procedures that use proto and invoke. 


     The following 6 parameters are used within the directive as follows. 

     .FPO (  number of bytes in a procedures local variables divided by 4, 
             number of bytes in a procedures parameters divided by 4,
             number of bytes in a procedure prologue,
             number of registers saved by a procedures prologue,
             If EBP is allocated,
             Frame Type )            


        Parameters                                      Range 
        ----------                                      -----
        number of bytes in local variables / 4          >= 0
        number of bytes in parameters / 4               0 - 65535
        number of bytes in the procedure prologue       0 - 255
        number of registers saved                       0 - 7
        If EBP is allocated                             0 = false, 1 = true
        Frame Type                                      0 - 2

        The valid values for the Frame Type parameter above are 

        FRAME_FPO   0
        FRAME_TRAP  1