       Copyright (C) 1995 MetaWare Incorporated; All Rights Reserved.

                         High C/C++ Version 3.31
                  Globally Optimizing Compiler and Tools
                    for 32-Bit Extended DOS and Windows
                               January 1995

READMEs included in this distribution
-------------------------------------
   README       -- This general README.
   FILELIST.TXT -- List of distribution files

   The following files are located in your HIGHC\DOC subdirectory:

   README.ADS   -- Developing an ADS Application
   README.MDB   -- MetaWare Debugger (MDB) Specifics
   README.WIN   -- MetaWare 32-Bit Windows Application Development Kit
   INLINE.RME   -- New inlining compiler controls
   PENTIUM.RME  -- Workaround for the Pentium floating-point divide problem
   UPFROM1X.RME -- Information for users upgrading from version 1.6 or 1.7


Table of Contents
-----------------
 1.  Introduction
 2.  Release Notes
 3.  Additions/Corrections to Printed Documentation
 4.  Profiler
 5.  Stack dump
 6.  Rogue Wave Tools.h++ Examples and Documentation
 7.  Driver Notes
 8.  Linking Object Modules Created with *_common Toggles
 9.  Known Problems
10.  Trouble-Shooting Tip
11.  Other Problems


1.  Introduction
----------------

The following features are new since Version 3.3:

*  Workaround for the Pentium floating-point divide problem; see
   PENTIUM.RME for a detailed description of how this works.

*  Command-line options -386_only, -486_only, and -Pentium_only

*  Toggle Pentium_safe_divide_code

*  Run-time library function _pentium_bad_fdiv_count()


2.  Release Notes
-----------------

*  For installation instructions, read the Installation Guide provided with
   your documentation.

*  For differences from and compatibility with prior versions, read the New
   Information! document.

*  Last-minute-supplied or unclassified software is in subdirectory ETC.


3.  Additions/Corrections to Printed Documentation
--------------------------------------------------

*  High C/C++ supports error handling.  See the High C/C++ Language
   Reference for details.

*  For information on namespaces, cast notation, and run-time type information,
   see the High C/C++ Language Reference.

*  High C/C++ 3.31 does not support namespace using directives and using 
   declarations as a declaration in a class definition.

*  The following optimizing toggles have been added to High C/C++:

   Alternate_entry_points
   Back_substitute_nodes
   Demote_sizes
   Improved_spill_analysis
   Optimize_floating_point
   Reorder_scratch_regs

   See New Information! for details.

*  See New Information! for additions to the Run-Time Library documentation.

*  Information about resolving the single-copy problem for templates is in 
   New Information!

*  Toggle Template_common is Off by default, not On as stated in New
   Information!

*  New Information! states that in cases where there is a conflict between
   a template function and a user-defined function with identical name and 
   argument list, the Phar Lap linker gives precedence to the user-defined 
   function and discards the template function.  The linker referred to is 
   386|LINK version 7.0.  This feature is not implemented in earlier versions.

*  New command-line options -386_only, -486_only, and -Pentium_only fine-
   tune code to run on the 386, 486, or Pentium processor only.  See 
   PENTIUM.RME for details.

*  New command-line option -Hlibobj allows you to link in one, two, or all 
   of the .obj files (pfnoflt.obj, sfnoflt.obj, and wildargs.obj) previously 
   linked in with the options -Hpfnoflt, -Hsfnoflt, and -Hwildargs.  Syntax
   is as follows:

      -Hlibobj=file.obj[, file.obj...]

   Options -Hpfnoflt, -Hsfnoflt, and -Hwildargs are also still available.

*  Use new command-line option -Hnalib if you want to make calls to non-ANSI
   versions of certain library functions.  See New Information! for details.

*  Compiling with command-line option -g automatically turns Off toggle 
   Optimize_across_statements (default On) unless you explicitly turn it on
   at the command line.  Forcing this toggle On maintains copy- and constant-
   propagation and dead-store elimination across statement boundaries when 
   you are compiling with command-line option -g.

*  Turn On toggle C_include to force all #include directives within its
   scope to behave like #c_include.  The default for this toggle is Off.

*  Toggle Downshift_file_names -- Convert include-file names to all lowercase
   Default:  Off

   When this toggle is On, the file-name specification of any subsequent 
   include is interpreted as if it were all lowercase.  This toggle is useful
   for moving source code from an operating system in which file-name casing
   is not significant to a system in which it is significant.

*  The name of toggle Globals_volatile has been changed. It is now called
   toggle Keep_global_refs_in_loops.  The default is still Off.

*  Toggle Long_double_math is On by default, not Off as stated in the 
   High C/C++ Programmer's Guide.

*  New toggle Pentium_safe_divide_code causes the compiler to generate
   Pentium-safe floating-point divide code.  See PENTIUM.RME for details.

*  Toggle Template_common is Off by default, not On as stated in New
   Information!

*  New run-time library function _pentium_bad_fdiv_count() returns the 
   number of times a defective floating-point denominator occurs in a given
   application.  See PENTIUM.RME for details.

*  Previously, output from compiler intrinsics _inb, _inw, and _ind
   was sign-extended.  This problem has now been fixed so that the 
   output is always unsigned.  Comparison of the output of these intrinsics
   to 0 (zero) no longer yields the result it did before; for example,
   the following code no longer works:

      if (_inb(edx_port) < 0)
         printf("ERROR\n")

*  For developers building embedded applications: the following paragraph 
   in Appendix G of the High C/C++ Programmer's Guide is wrong, and should 
   be disregarded:

   "If you are developing code for use in embedded systems, and you are 
   not writing your own library, use High C 1.x library hcc.lib or hce.lib
   instead of the High C/C++ libraries....  hcc.lib and hce.lib facilitate
   making an embedded product because they isolate system dependencies in 
   a few modules."

*  Keywords _Packed and _Unpacked are implemented for this compiler.

*  Use the _UNSAFE macro on virtual functions when you are creating your 
   own multithreadable stream classes.

*  WARNING:  The default C++ level for High C/C++ version 3.21 was 2.  For
             version 3.3 and later it is 3.  This means that some code that 
             compiled on version 3.21 with a warning message produces a 
             fatal error on version 3.3 and 3.31.  See the High C/C++ 
             Programmer's Guide for information about what is and is not 
             allowed at C++ level 3.

*  If you are using Phar Lap 386|DOS-Extender, you can use the -offset
   linker switch to make your program start at a location other than 0.
   The -offset switch takes a single parameter, which is the starting
   offset of the program; its value must be a multiple of 4K.  For example,
   "-offset 1000h" causes the program to start at offset 1000h (4K).
   You can specify this option when you compile.  For example:

      hc386 test.c "-Hldopt=-offset 1000h"

   Using this option has the added benefit of allowing the DOS extender
   to detect attempts by your program to dereference a NULL pointer, a common
   programming mistake.

*  You can now substitute format strings for explicit file names with 
   command-line options that generate output files.  These format strings
   make characteristics of the input file the default for the output
   file.

   The format strings are as follows:
   ------------------------------------------------------------------------
   @%f     Give the output file the same full name as the input file:
           drive, directory pathname, filename, and extension.
   @%d     Give the output file the same directory pathname and file name 
           as the input file.
   @%p     Give the output file the same prefix as the input file:
           drive and directory pathname, but not file name or extension.
   @%n     Give the output file the same file name as the input file.
   @%e     Give the output file the same extension as the input file.
   ------------------------------------------------------------------------

   Here are two examples:

   hc -Hlist=@%n.lst myfile.cpp      Generate a list file with the same
                                     file name as the input file (myfile) 
                                     and the extension .lst.

   hc -Hmap=@%d.xyz myfile.cpp       Generate a mapfile with the same file
                                     name as the input file (myfile) and
                                     the extension .xyz (instead of the 
                                     default .map).  Put it in the same 
                                     directory as the input file.

*  In Example 12.2 in the High C/C++ Programmer's Guide, we document the 
   prolog code as:

      push       ebp
      mov        ebp,esp
      sub        esp,n         ; ... (n is the length of the stack frame)
      push       edi           ; Save nonvolatile...
      push       esi
      push       ebx
      sub        esp,c         ; Allocate space for largest argument list...
      ...

   To improve the instruction scheduling capability for the 486 or Pentium 
   processor of the compiler in circumstances outlined below, the prolog code
   has been changed to the following:

      push       ebp
      mov        ebp,esp
      sub        esp,c+n+8     ; Largest argument list + length of stack frame
                               ;      + number of nonvolatile registers * 4
      mov        [esp+c+4],edi ; Save nonvolatile registers
      mov        [esp+c],esi
      ...

   This code allows more U-/V-pipe scheduling on the Pentium processor, and 
   is also one instruction shorter. 

   Watch out for the following, however:

   -  The instruction scheduler may move the stores of esi and edi down in
      the instruction stream. When this occurs, the prolog code will look
      slightly different from that shown above.

   -  If there is no need for an argument list, the compiler will not
      generate the above prolog; instead, it will use the original prolog
      shown in Example 12.2.

*  Similarly, Example 12.3, which is shown as:

      push       ebp
      sub        esp,n
      push       edi
      push       esi
      push       ebx
      sub        esp,c
      ...

   has been modified, with the same caveats as above, to:

      push       ebp
      sub        esp,c+n+12
      mov        [esp+c+8],edi
      mov        [esp+77c+4],esi
      mov        [esp+c],ebx
      ...


4. Profiler
-----------

The profiler does not work with the Rational Systems DOS 4G extender, because
the Rational linker does not provide support for the symbols used.


5.  Stack dump
--------------

Routine stackdump(int handle) does not include any routine names.  It
does include the "will return to" address, and eight arguments from the
stack.  It cannot provide any arguments that were passed in registers.


6.  Rogue Wave Tools.h++ Examples and Documentation
---------------------------------------------------

To make sure the compiler includes the correct ...\rwtool\lib directory
in the include-file search path, use command-line option -Hrw.  See
New Information! for details.

To compile and run the Rogue Wave examples:

   1. Go to the HIGHC\RWTOOL\TOOLEXAM directory.

   2. To compile example1.cpp, type:

         hc386 example1.cpp -Hrw

   3. To run the example, type:

         run386 example1


7.  Driver Notes
----------------

When you invoke High C/C++ with the command hc386, you are invoking a driver
program which in turn invokes the compiler.  See the Programmer's Guide for
more information.


8.  Linking Object Modules Created with *_common Toggles
--------------------------------------------------------

To correctly link modules that have been created with any of the *_common
toggles, you need Phar Lap 386|LINK version 4.1 or later.  If you try to
link one of these object modules with a linker version earlier than 4.1, the 
linker emits a "Bad Record Format" error.

If you want to use a user-defined function in place of a template-defined
function of the same name and parameter types, contact Phar Lap Technical 
Support to get Phar Lap 386|LINK version 7.0.  If you try to link your 
application without the newer linker, the linker you use will emit an 
"Unresolved Externals" or "Duplicate Definition" error.


9.  Known Problems
------------------

*  If you are compiling for Microsoft Windows 3.1x, and you are using the
   MetaWare -Hwin switch, you may encounter a problem with the Phar Lap
   linker. The linker will not correctly handle a variable whose size is
   between 125 and 128 bytes in length. If you have a character array of
   this size, you may see an undefined symbol error from the linker.

   When you encounter this, you have the following options:

   -  Increase the size of the array.
   -  Contact Phar Lap technical support at (617) 661-1510.
   -  Contact MetaWare technical support for an engineering update that 
      supplies a workaround for this problem.

   NOTE:  Two of our Windows example programs fail to link because of this
   problem:

      highc\win\sdk\prntfile
      highc\win\sdk\showfont

   You can resolve the problem by increasing the size of the 128-byte 
   character array in these examples to 256 bytes.

*  Function _bios_disk() does not support read, write, or verify operations.

*  At the hardware level, the signal() and raise() functions support only 
   the following exceptions:

      Function(s)          Signal number          Type of exception          
      -----------          -------------          -----------------
      signal(), raise()    SIGABRT                DOS critical error
      signal(), raise()    SIGINT                 Control-C
      signal() only        SIGFPE                 Floating-point exception
                                                  (x87, 486, or Pentium only)
                                                  
   All signals are supported at the software level (via raise()).

   WARNING:  If a hardware interrupt occurs during a DOS or BIOS operation, it
             may not be possible to execute the signal handler.  In this case,
             the results are undefined, and may result in a system crash.  See
             the Library Reference for descriptions of signal() and raise().

*  It is not possible to install the first function in the code segment as
   a signal handler.  The address of the first function is cs:0, which when
   passed to signal() (for example, signal(SIGINT, fnc)) is interpreted as
   SIG_DFL (defined as 0 (zero) in signal.h).  This causes the program to execute
   an exit(3) instruction (the default action) instead of the intended
   handler.  To solve this problem, move the handler away from the beginning
   of the file in which it resides, or precede it with a dummy stub function;
   or change the order in which the object modules are linked.  Or use the
   Phar Lap 386|LINK -offset option to install the function at an address 
   other than zero.

*  DOS Helper program sc.exe does not work with MS-DOS 5.0, because the system
   call sc.exe uses has been nullified in this version of MS-DOS.


10.  Trouble-Shooting Tip
-------------------------

Are you having trouble compiling and linking an extended DOS program?

*  Check:  Are 386|LINK and the DOS extender on your PATH?

*  Check:  Is the compiler \BIN subdirectory on your PATH?


11.  Other Problems
-------------------

If you think you have discovered a compiler problem, send a problem report to
MetaWare Technical Support.  If possible, please send a test case that
demonstrates the problem.

All problem reports must include your serial number and specify which version
of the compiler you are using.  If your sample code exceeds 15 lines, please
send it by diskette to the address below, or by E-mail to:

   tech@metaware.com

MetaWare Technical Support can be reached at (408) 429-6111, 8:00 a.m. to 
5:00 p.m. Pacific Time, Monday through Friday.


MetaWare Incorporated
2161 Delaware Avenue
Santa Cruz, CA 95060-5706
(408)429-6382  FAX:(408)429-9273

------------------------------------------------------------------------------
The installation program used to install MetaWare High C/C++, INSTALL, is
based on licensed software provided by Knowledge Dynamics Corp., P.O. Box 1558,
Canyon Lake, TX 78130-1558 (USA).  INSTALL is Copyright (c) 1987-1991 by
Knowledge Dynamics Corp. which reserves all copyright protection worldwide.
INSTALL is provided to you for the exclusive purpose of installing this
MetaWare product. MetaWare has made modifications to the software as provided
by Knowledge Dynamics Corp., and thus the performance and behavior of the
INSTALL program shipped with this MetaWare product may not represent the
performance and behavior of INSTALL as shipped by Knowledge Dynamics Corp.
MetaWare is exclusively responsible for the support of this MetaWare product,
including support during the installation phase.  In no event will Knowledge
Dynamics Corp. be able to provide any technical support for MetaWare products.
------------------------------------------------------------------------------



Document number:  RM-4701-002
