dos_compilers/Microsoft QuickC v251/BIN/README.DOC

                              README.DOC File
                    
                           Release Notes for the
   Microsoft(R) QuickC(R) Compiler with QuickAssembler, Version 2.51

          (C) Copyright Microsoft Corporation, 1989-1990

This document contains release notes for Version 2.51 of the Microsoft
QuickC Compiler with QuickAssembler. It includes information on both C and 
assembly language. The Contents section below lists the documentation for 
C and assembly language affected by the release notes. In all cases, the 
information in this document supersedes the information in the manuals.
However, Microsoft revises its documentation at the time of reprinting;
the manuals may already include some of this information.

Note: If you're reading this from within on-line help, but would prefer to
print it out by loading README.DOC into a word processor, you can find the
file in the executable files directory (the default is \QC25\BIN).

The other documentation files are \SAMPLES\QASAMPLES.DOC, which explains
the assembly-language example programs in the SAMPLES directory; and
SAMPLES.DOC, which explains the C-language example programs in the same
directory.

(COMPAQ is a registered trademark of Compaq Computer Corporation.)
(Intel is a registered trademark of Intel Corporation.)
(Novell is a registered trademark of Novell, Inc.)


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


This document has five parts:

          Part           Notes
          ----           ----------------------------------------------
            1            Notes on "Up and Running"
            2            Notes on "C for Yourself"
            3            Notes on "QuickC Tool Kit"
            4            Notes on "QuickAssembler Programmer's Guide"
            5            Additional Notes on QuickC with QuickAssembler



===================< Part 1: Notes on "Up and Running" >===================


Page  Note
----  ----

Inside Front Cover
      Brief Guide to Keystrokes
---   -------------------------
      The chart on the inside front cover says the ESC key "stops the
      compiler and linker from continuing."  ESC stops the compiler but NOT
      the linker.  Press CTRL+BREAK to stop both the compiler and linker.

      If you are using the debugger and running a program that expects
      keyboard input, pressing either CTRL+C or CTRL+BREAK and then ENTER
      will allow you to exit.

  6   Running SETUP
---   -------------
      If you already have QuickC installed, SETUP will overwrite the
      existing QC.INI file that contains the current compiler options,
      etc. set in the environment. If you wish to save those settings,
      rename this file before running SETUP.

 19   Using QuickC
---   ------------
      If you own a COMPAQ(R) SLT/286, and the LCD display goes
      blank when exiting from QuickC back to DOS, you should
      run the program DAC_ON.COM before loading QuickC. To obtain a
      copy of DAC_ON.COM, contact your authorized COMPAQ Computer
      Dealer.

 42   The Debugger
---   ------------
      The Quickwatch command does not display complete information
      for assembler structures. Only the first member of a structure
      is shown.

      You may see the message "currently running program terminated"
      while debugging.
      
      This may happen if your program is linked with a user-created
      library module that contains debugging information, and for
      which the source files are present. In such a case, single-
      stepping into a function contained in the library will cause
      the debugger to terminate the current program and attempt to
      compile the source files for the library module into an
      executable program.

      You can avoid this problem by setting your program list to
      contain only the name of the source file of your program.

(miscellaneous)

      Accessing Memory at 0xFFFF
      --------------------------
      Due to a problem with the Intel(R) processor, any attempt to
      access a word value at memory location 0xFFFF may cause the
      system to hang. The most likely way for this to happen is from
      within the QuickC debugger, if you use the WO (display word) or
      DW (display double word) operators to examine a register 
      containing 0xFFFF. Any C or assembly-language program trying
      to access that location may also cause the system to hang.

      Incompatibility with Novell(R) Netware
      --------------------------------------
      If you have a peripheral (such as a mouse) that uses IRQ 3, and
      your system is part of a network using Novell Netware version
      2.15 or lower, your system may hang when you load the QuickC
      environment. As a temporary solution, reset your peripheral to
      use another interrupt. For more information, contact your Novell
      Netware dealer.



===================< Part 2: Notes on "C for Yourself" >===================


Page  Note
----  ----

 53   Type Qualifiers
---   ---------------
      The fourth paragraph in this section is incorrect. A long double
      value is the same size as a double. It contains 8 bytes, not 10. It
      expresses a floating-point number with at least 15 digits of
      precision, not 19. Table 4.1 on page 49 should also be corrected.

164   Declaring a Pointer with the Wrong Type
---   ---------------------------------------
      In the first program listing on the page, the line

           ptr = val;      /* Error! */

      should read

           ptr = &val;     /* Error! */

215   Table 11.4   Standard vs. Low-Level
---   -----------------------------------
      The headings across the top of the table should read 

         Function     Parameters        Returns        Error Condition

298   Vector-Mapped Fonts
---   -------------------
      Add this note to the description of vector mapping:

      If a vector-mapped font is selected in graphics mode, any function
      affecting "_moveto" or "_lineto" will also affect the font
      ("_setlinestyle" and so on) when "_outgtext" is called.

304   Example Program Using Fonts
---   ---------------------------
      The line reading

           if( !_setfont( list ) )

      should read

           if( _setfont( list ) >= 0 )

309   Limits on _asm Identifiers
---   --------------------------
      Never use reserved assembly words as labels, variable names, or other
      identifiers within an _asm block. This includes words in the
      following categories:

         - ASM Opcodes such as CMP or MOV
         - Opcodes new to the 80186, 80286, and 80386 such as ARPLS or CLTS
         - Reserved operand words such as WORD or PARA
         - C library functions such as "exit" or "time"

      For example, the following code is not permitted:

           main()
           {
              int word;
              _asm { mov WORD PTR [word],ax }
           }

      The variable 'word' can be used in the C part of the program, but not
      within the assembly block.

 366  Font Display Routines
 ---  ---------------------
      The return values for the _registerfonts and _setfont functions
      should be

      _registerfonts

      Returns: the number of fonts registered, or a negative value if
               failure

      _setfont

      Returns: a negative value if failure, zero or positive if
               successful



==================< Part 3: Notes on "QuickC Tool Kit" >===================


Page  Note
----  ----

  94  /Gw, GW (Generate Code for Windows Function Calls)
 ---  --------------------------------------------------
      QuickC 2.5 supports development of programs for the next release
      of Windows. If you wish to develop programs for Windows 2.03, you
      must explicitly link your program with C51STUBS.LIB.

 130  /INC (Prepare for ILINK)
 ---  ------------------------
      By default, ILINK will call LINK if the incremental link fails.
      To make ILINK call QLINK instead, use the /E option and an 
      argument. For example:

           ILINK /E "QLINK @RESPONSE" PROGRAM.EXE

 259  Warning Message C4018
 ---  ---------------------
      The warning message below is new and should be added to page 259:

           C4018   'operator': signed/unsigned mismatch

      An expression involving the specified operator had inconsistent
      integer types. The two integer expressions used in the comparison
      operation are not of the same signed or unsigned type.

(miscellaneous)

      Makefile Compatibility with QuickC 2.0
      --------------------------------------
      The name of the linker supplied with QuickC has been changed
      from LINK to QLINK. Any makefile used with QuickC 2.0 that
      specify the LINK command should be changed accordingly.

      Makefile Compatibility with Programmer's WorkBench
      --------------------------------------------------
      The makefiles generated by QuickC are not fully readable by 
      Microsoft Programmer's WorkBench (PWB) included with Microsoft's
      Professional Development Systems. PWB is unable to read the
      linker options specified in QuickC makefiles, so you will have to 
      re-specify those options using PWB's menus. QuickC cannot read
      makefiles generated by PWB.



========< Part 4: Notes on "QuickAssembler Programmer's Guide" >===========


Page  Note
----  ----

 xi   Running SETUP Before Using Help
---   -------------------------------
      Before using the Quick Advisor, make sure you run the SETUP
      program. This program combines files on different disks to build
      QA.HLP, which contains help on assembly language as well as DOS
      and BIOS interrupt functions. 

 xi   Expanding Environment Space
---   ---------------------------

      QuickAssembler for QuickC makes use of certain environment
      variables, such as HELPFILES. However, these variables are stored
      in an area of memory called the "environment space." You may need
      to expand this memory to use the new environment variables
      successfully.

      If you run DOS 3.2 or later, you can set the environment space
      with the DOS SHELL command. For example, the following command
      sets the environment size at 3000 bytes when placed in CONFIG.SYS:

           SHELL=COMMAND.COM /E:3000 /p

      Consult your DOS manual for more information.

 xi   Temporary Files and the TMP Environment Variable
---   ------------------------------------------------
      If you do not have a TMP environment variable set, the linker
      prints the following message when it creates a temporary file:

           temporary file <filename> created

      To avoid getting this message, set the TMP environment variable to
      the name of a drive and directory. This drive should have some free
      space. For example, the following command line sets C:\TEMP as the
      directory where the linker places temporary files:

           SET TMP=C:\TEMP

      For convenience, place this command (or a similar one) in your
      AUTOEXEC.BAT file to execute it automatically.

  6   Terminating the Program with .EXIT
---   ----------------------------------
      When you use the .STARTUP directive, the recommended method for
      terminating the program is to use the .EXIT directive. With
      stand-alone assembly programs, you must explicitly terminate
      or the processor will execute meaningless instructions beyond the
      end of the program.

      The .EXIT directive has the following syntax:

           .EXIT [exitcode]

      in which exitcode is an optional register, memory location, or
      constant that contains a value to return to DOS. This value must
      not be larger than one byte.

      When you use this directive, the assembler generates instructions
      that call DOS function 4CH (Exit with Return Code). You can use
      another method to terminate the program if you wish. The assembler
      generates an advisory warning if you use .STARTUP without .EXIT.

      The .EXIT directive requires that .MODEL was previously used.

      Within the environment, the assembler generates an advisory
      warning message if you use .STARTUP without using .EXIT. Outside
      the environment, the assembler does not generate this message.

  7   Effect of ILINK on Building a Program
---   -------------------------------------
      By default, the QuickC environment invokes ILINK to link programs.
      ILINK, in turn, requires that a program have a default data
      segment (it may be empty). To meet this requirement, you can do
      any of three alternatives:

      1. Declare a data segment with .DATA if using simplified segment
         directives.

      2. Declare a group named DGROUP.

      3. Turn Incremental Link off in the Linker Flags dialog box.

      The use of ILINK imposes some other requirements on assembly-
      language programs:

      1. You cannot have a segment with the AT attribute.

      2. Avoid depending on distances between segments being fixed. Some
         programs calculate the distance between two segments and then
         use this value elsewhere. When ILINK is in use, segment-address
         arithmetic is unpredictable.

      3. The DUP operator cannot have a program address as an operand.
         For example, the following statement is compatible with ILINK:

      myarr     DW     10 DUP (5)

      However, the next statement is not compatible with ILINK, even
      though it is supported by the assembler:

      myarr     DW     10 DUP (myproc)

  7   Searching for Include Files
---   ---------------------------
      When building and running a program, note that the assembler looks
      for include files in the following order:

      1. The directory in which the current source file is located
      2. Directories specified with the /I command-line option
      3. The current directory (as recognized by the environment)
      4. Directories specified in the INCLUDE environment variable

  9   Assembling from the Command Line
---   --------------------------------
      QCL does not report some warning messages reported inside the QuickC
      environment. QCL does not warn you if you use .STARTUP without .EXIT.

 14   Specifying Debug Expressions
---   ----------------------------
      The QuickC environment now supports an optional display-format
      character for examining arrays. You can add a suffix to any
      expression for the Watch window as follows:

           expression,nf

      in which n is a number and f is a format specifier (such as i, x,
      d, or a). Both are optional. The use of n displays the expression
      as if it were an array. If the expression is already an array,
      then the use of n displays the array as if it were an array of a
      higher dimension. The assembler does not type any symbol as an
      array. Thus, the use of n with a variable declared in assembly
      always displays the variable as an array of one dimension.

      The optional f display-format specifier only affects the format
      in which each member of the array is displayed.

      The Watch window determines the type of array from the expression
      or from BY, WO, or DW if used. If WVAR is declared as type WORD
      (or "int" in C), then WVAR,5x displays the first five words at the
      address of WVAR. The "x" specifies hex format. BY WVAR,5x displays
      the first five bytes at the address of WVAR. Each byte is
      displayed as if it were a hexadecimal word-sized value.

 56   The PROC Directive
---   ------------------
      The PROC directive sets the BP register to point to a procedure's
      frame, but only if you use a parameter list or the LOCAL directive.

 82   Using Full Segment Definitions
---   ------------------------------
      The program example on this page should declare class name 'CODE'
      for the segment definition:

      _TEXT     SEGMENT  'CODE'

      The class name 'CODE' is necessary if you want to debug the
      module. The assembler issues a warning message if you assemble a
      code segment without this class name. If you use simplified
      segment directives, the code segments automatically have this
      class name.

109   Defining Segment Combine Types
---   ------------------------------
      The combine type describes how the linker combines segments, but
      does not affect the assembler itself. Within any given module, the
      assembler concatenates segments with the same name. Thus, segments
      with the COMMON attribute are overlapped only if they are in
      different modules.

383   Assembling with Two Passes
---   --------------------------
      In addition to the options listed in Appendix B, QCL supports the
      /P2 option, which specifies two-pass assembly. The /P1 option
      specifies one-pass assembly and is now the default. Two-pass
      assembly is slower than one-pass assembly, but enables some
      language-specific features (such as IF1 and IF2) that rely on two
      passes.

383   Removing Copyright Message
---   --------------------------
      In addition to the options listed in Appendix B, QCL supports the
      /nologo option, which prevents QCL from printing the product name
      and copyright information. QCL also prints a warning message when a
      nonstandard version of DOS is detected. The /nologo option prevents
      this message from being printed.

386   Using /AT to Generate a .COM File
---   ---------------------------------
      If you use QCL to generate a .COM file but do not use /AT, the
      linker may produce a file with an .EXE extension. This file is
      really in .COM format. It should be renamed immediately. You can
      prevent this situation by using the /AT option, or by using the
      /Fe option to explicitly give the name of the output file. For
      example, the following command line produces a file with a .EXE
      extension:

           QCL sample.asm /link /TINY

      However, the following command lines each produce a file with a
      .COM extension:

           QCL /AT /Ln sample.asm /link /TINY
           QCL /Fe sample.com sample.asm /link /TINY

392   Line-Number Index in Listing File
---   ---------------------------------
      The line-number index generated by /Sq (and generated by default
      within the environment) lists correspondences between source-file
      lines and listing-file lines. This index, placed at the end of the
      listing file, is read and interpreted by the QuickC environment.
      You should avoid writing utilities that read this index. The
      format of the line-number index is subject to change without
      notice.



========< Part 5: Additional Notes for QuickC with QuickAssembler>=========


Source of DOS and BIOS Function Information in Help
---------------------------------------------------
On-line help includes information on IBM ROM BIOS services as well as
MS-DOS service calls. The information on these topics is adapted from the
books "IBM ROM BIOS" and "MS-DOS Functions" by Ray Duncan. Both books are
published by Microsoft Press and are part of the Programmer's Quick
Reference Series.

Math Coprocessor Instructions in .ASM Programs
----------------------------------------------
If you do not have a math coprocessor chip, you must use the /FPi option
when assembling code for emulated floating-point instructions. If the
switch is omitted, your assembly-language programs may hang your machine.

Setting Breakpoints on Assembly Procedures and Labels
-----------------------------------------------------
Version 2.51 of QuickAssembler now supports setting breakpoints on labels.
Because assembly procedures are treated as labels, a dialog box verifies if
you want to set a breakpoint at a procedure label.  Additional information
can be found in the on-line help. 

ILINK and Tiny Model
--------------------
When switching to tiny model from another model, or from another model to
tiny model, turn off the incremental link option the first time you build
after switching models.  Alternatively, you can delete to .SYM and .ILK
files to force a full link.  ILINK should always be disabled
when creating tiny model (.COM) programs.