                           WELCOME TO BORLAND C++ 4.02


This README file contains important information about Borland C++.
For the latest information about Borland C++ and its accompanying
programs, read this entire file. See file OWLDOC.WRI for the latest
information on the ObjectWindows library.


TABLE OF CONTENTS
-----------------
1.  How to Get Help
     -Sources of information
2.  Installation
3.  Features
     -Compiler
     -Linker
     -IDE
     -Turbo Debugger
     -Resource Workshop
     -ObjectWindows Library (OWL)
     -VBX Support
4.  Important Information
     -Out of Memory and MAKESWAP
     -Threads
     -DDVT functions and RTTI
     -Inline assembly and interrupts
     -Creating 16-bit import libraries from .DEF files
     -Debugging DDE applications
     -Compiler and Linker Switch Changes
     -IDE/Integrated Debugging
     -Turbo Debugger for Windows
     -Just In Time Debugging
     -Using Tools with NTFS
     -NOEHxx Libraries
     -Running from a Windows 3.1 DOS Prompt
     -C/C++ Language Changes
     -Creating .COM Files
     -Converting Borland C++ 3.1 Windows Code to Borland C++ 4.02
     -Floating Point Formats
5. Miscellaneous Information


------------------
1. HOW TO GET HELP
------------------

SOURCES OF INFORMATION
----------------------
  If you have any problems, please read this file, the
  HELPME!.WRI and other files in your DOC subdirectory, and
  check the on-line help and the Borland C++ manuals first.
  If you still have a question and need assistance, help is
  available from the following sources:

  1. For instant on-line access to the Borland CompuServe forums,
     with their libraries of technical information and answers
     to common questions, type

        GO BCPPDOS     - for questions pertaining to DOS

         or

        GO BCPPWIN     - for questions pertaining to Windows

     If you are not a member of CompuServe, see the enclosed
     special offer, and write for full details on how to receive
     a free IntroPak containing a $15 credit toward your first
     month's on-line charges.

     For on-line access to Borland information on BIX, type

        JOIN BORLAND

     For on-line access to Borland information on GEnie, type

        BORLAND


  2. Borland offers a wide variety of Technical Support plans
     providing a range of assistance from installation and general
     usage of Borland C++ to language syntax, programming, and
     debugging help. For information about these support programs,
     call 1-800-523-7070.

  3. Borland's TECHFAX service. Call (800) 822-4269 for a FAX
      catalog of technical document entries.

  4. Borland DLBBS. Dial (408) 431-5096 (up to 9600 baud, 8-N-1)
      for a host of free technical documents and example programs.

  5. For immediate assistance with everything from configuring Borland C++
      to programming or debugging, call our C++ Programmer's
      Advisor Lines ($2/minute, first minute free):
            * Windows / Win32:     1-900-555-1002  or 1-800-782-5558 (MC/Visa)
            * DOS :      1-900-555-1004  or 1-800-368-3366 (MC/Visa)

  6. Technical information on Borland C++ is available on the Internet
     via anonymous ftp at our ftp site ftp.borland.com.

  7. Subscribe to Borland's free electronic newsleter and get a regular
      update on the hottest programming tips and tricks.  Send your full 
      name and address via electronic mail to tech-info@borland.com.

---------------
2. INSTALLATION
---------------

IMPORTANT!
Do not install Borland C++ 4.02 files over previously installed Borland
C++ directories. The files in this distribution will not work
with previously shipped tools and libraries.  This is particularly
true for configuration files from previous shipping
releases, like TDCONFIG.TDW and BCCONFIG.BCW.

Also, be especially careful when using object files and libraries
from Borland C++ 3.1 with binaries created with this release. There are
several potential problems when linking with old objects or libraries.
Exceptions won't work correctly (destructors won't get called) when a
pre-BC4 stack frame is unwound due to an exception. See the "New Compiler
and Linker Switches" and "NOEHxx Libraries" sections for more information.

Do not use long file names when installing under Windows NT.

Installing Borland C++ 4.02 on your hard disk:
----------------------------------------------
Installing from floppy disks:
     1. Select File|Run from Windows 3.1, Windows for Workgroups 3.1x,
        or Windows NT.
     2. Enter A:INSTALL (or B:INSTALL) on the input line.

Installing from the CD-ROM:
     1. Go to the CD-ROM, and change directories to INSTALL.
     2. Select File|Run from Windows 3.1, Windows for Workgroups 3.1x,
        or Windows NT.
     3. Enter X:INSTALL on the input line (where X: is your CD-ROM drive).

NT console applications and Win32s
----------------------------------
There is no Win32s console, so attempting to run a Win32 console
application without NT loaded will result in an error.

Configuring the Windows NT command prompt
-----------------------------------------
To run 16-bit protected-mode programs (bcc, tlink) under an NT command prompt
you need to add the following line to CONFIG.NT:

  ntcmdprompt

Under the default NT command-line prompt, DOS COMMAND.COM is run after
returning from a TSR (such as RTM.EXE which bcc and tlink load). Adding the
above line will cause the original NT CMD.EXE to be run.


-----------
3. FEATURES
-----------

Compiler:
---------
  - Support for writing 16 and 32-bit Windows applications that target
    Windows 3.1, Win32s and Windows NT, and 16-bit DOS applications.
  - Pentium support.
  - Support for ANSI C++ exception handling, structured exception handling
    under C, and mixed C/C++ exception handling. All exception handling
    constructs are available for both 16- and 32-bit.
  - Additional optimizations and faster compile time.
  - Support for ANSI C++ operator new[] and operator delete[].
  - Runtime Library support for the ANSI C++ string class.
  - Support for ANSI C++ runtime type identification (RTTI).
  - Support for ANSI C++ new style casts dynamic_cast, static_cast, const_cast,
    and  reinterpret_cast.
  - Support for three character types as provided in ANSI C++.

Linker (16-bit and 32-bit):
---------------------------
  - Now handles binding of resources; no need for a separate RC or
    RLINK step.
  - Linker debug capacity expanded.

IDE
---
  - 16-bit DOS and Windows plus 32-bit Windows targeting from a single IDE.
  - Integrated GUI debugging for 16-bit Windows applications.
  - Includes both 16- and 32-bit tools (compiler, linker, resource
    compiler, resource binder, and library manager)
  - A new project manager that supports multiple targets, drag-and-drop,
    and Style Sheets for associating options.
  - AppExpert, which simplifies the process of creating
    ObjectWindows applications through code generation.
  - ClassExpert, which simplifies adding and managing classes in
    your AppExpert application.
  - Transfers, Settings Notebook, SpeedMenus, and a configurable SpeedBar.
  - Expanded editor support, including column blocking and window
    splitting.  TEMC now called KEYMAPR.

Turbo Debugger:
---------------
  - Turbo Debugger (TD32) for Win32s and Windows NT.
  - Supports OS exception handling.
  - Supports C/C++ exception handling.
  - Windows NT thread support.
  - Supports just in time debugging
  - Video DLL to run TDW in a window.
  - Remote debugging with TDW.
  - Session state saving.
  - Process attach for Windows NT.
  - Turbo Debugger Video Configuration Utility (TDWINI.EXE).
  - Built in large model for greater capacity.

Resource Workshop:
------------------
  - Support for Win32s, Win32.
  - Resource preview
  - DialogExpert
  - Auto ID numbering
  - Auto mapping of accelerators and help hints to menu items
  - Support for VBX controls
  - SpeedMenus
  - Dialog editor property inspector
  - Integrated with ClassExpert and IDE project manager

ObjectWindows Library (OWL)
---------------------------
  - Complete coverage of Windows API, including GDI
  - Single source for Win 3.1, Win 32s, and NT
  - Built in exception handling using standard C++ exceptions for robust error
    handling
  - Built-in type safety using standard C++ templates
  - Toolbars, status lines, and print preview
  - Flexible Document/View architecture
  - Supports VBX 1.0 controls in a dialog or window
  - Layout Windows
  - Mix-in architecture
  - Support for 3d controls
  - Support for BWCC controls
  - Gadgets and Widgets
  - Multi threading support
  - Printing and print previewing support

VBX Support
-----------
Borland's visual tools, such as Resource Workshop, provide support of VBX 1.0
controls via a DLL called BIVBX102.DLL. You can freely distrubute this DLL
with programs you create that use VBX controls.

BIVBX102.DLL has been tested with a large number of VBX controls written to
the Microsoft Visual Basic 1.0 CDK specification. If you have a problem with
a specific control, make sure that it does not require VB 2.0 or VB 3.0 CDK
functionality. VBX 2.0 and 3.0 controls will usually display a message saying
that they require VB 2.0 or 3.0 support. In some cases, though, the control
may appear to work but exhibit instability. Please contact the control vendor
and explain the problem. They may have an updated control or may be able to 
contact Borland to find a solution.

Documentation:
--------------
This distribution includes printed books and online help to assist
you in understanding and using the new features of Borland C++ 4.02.

For C++ Language and Programming information:
     See the Library Reference, the
     Programmer's Guide, and the DOS Reference.
     See also the online Help.

For information on using MAKE, TLINK, and resource tools:
     See the User's Guide.
     See also the online Help.

For information on keyboard mapping and KEYMAPR (used to be called TEMC):
     See the online Help.

For information on using the IDE, AppExpert & ClassExpert, the Integrated
Debugger, and compiling options:
     See the User's Guide.
     See also the online Help.

For information on using the new Project Manager:
     See the online Help.

For information on converting your ObjectWindows 1.0 code to
ObjectWindows 2.0:
     See the ObjectWindows Programmer's Guide.
     See also the online text file OWLDOC.WRI.

For information on programming in ObjectWindows 2.0:
     See the ObjectWindows Reference Guide, and the
     ObjectWindows Programmer's Guide.
     See also the online text files HELPME!.WRI and OWLDOC.WRI.

For help using Turbo Debugger:
     See the online text file TD_RDME.TXT.
     See also the online Help.

To use the online Help, make sure the Borland C++ 4.02 \BIN directory is
on your path.


------------------------
4. IMPORTANT INFORMATION
------------------------

Out of Memory and MAKESWAP
--------------------------
If you get "Out of Memory" errors from DOS when running the
command-line tools, or if you have only 8 MB of RAM and have
out-of-memory problems building and using 32-bit applications,
then create a swap file with the MAKESWAP utility.  (Note that
this applies to DOS only, not to DOS boxes opened under
Windows.) MAKESWAP takes the size of the file to create in
KBytes, for example

  MAKESWAP 12000

will create a 12MB swap file in the current directory called EDPMI.SWP
for use by Borland command-line tools.  To enable the swap file, use
the DPMI32 environment variable by issuing the following command at
the DOS prompt:

  set DPMI32=SWAPFILE <location of swap file>\EDPMI.SWP

You must clear this environment variable by issuing the command

  set DPMI32=

before running Paradox or other 16-bit DPMI-hosted executables,
such as Borland C++ 3.1 command-line tools.


Threads
-------
When creating secondary threads, the _beginthread or _beginthreadNT
and _endthread() RTL functions must be used to ensure the proper RTL
initialization and cleanup. Using NT's CreateThread and ExitThread
functions will result in undefined behavior if an implicit or
explicit call is made to the RTL. Both exception handling and RTTI
can lead to implicit RTL calls.


DDVT functions and RTTI
-----------------------
When compiling code that contains DDVT functions, do not use run-time
type information or you will receive an error message. In order to
compile without using run-time type information, compile all code
that uses DDVTs (for instance OWL 1.0x libraries and applications)
with the -RT- switch (Options|Project|C++ Options|Exception
handling\RTTI in the IDE).


Inline assembly and interrupts
------------------------------
If your inline assembly code includes an interrupt call, the compiler does
not preserve any registers altered by the call. You must write code to save
and restore registers when using interrupt calls within inline assembly code.


Creating 16-bit import libraries from .DEF files
------------------------------------------------
Use the /o implib switch when creating 16-bit import libraries from .DEF files
to prevent implib from generating extensions for import entry module names.


New Compiler and Linker Switches
--------------------------------
Two new compiler switches for exception handling have been added.

   The -xf switch causes exception-handling prolog code to be generated
   inline (instead of a function call), increasing performance and module
   size. This switch is off by default.

   Use the -xc switch when compiling DLLs that will be used with
   non-BC++ 4.02 built executables (e.g. BC++ 3.1 or compilers from
   different vendors). This switch is off by default.

BCC switch -1- generates 8086 code.


IDE/Integrated Debugging
------------------------
The default extension for Borland C++ 4.02 project files is .IDE.

Using the Microsoft DBWIN utility interferes with the Event log's
ability to display those same messages. To see those messages in
the Event log, either quit DBWIN or select Options|No Output in DBWIN.

DDE applications must be debugged in hard mode.

Hard-mode debugging does not work reliably under Windows NT version 3.1, and
may crash the WOW session. The IDE disallows users from selecting hard mode on
all stops, but setting a breakpoint on certain Windows messages may cause the
debugger to go into hard mode.


Turbo Debugger for Windows
--------------------------
You can use TD32 to debug under Win32s. However, to do so, you must
ensure you use SVGA.DLL or equivalent support in the VideoDLL entry
in the [TurboDebugger] section of TDW.INI.

TD32 can support dual monitor debugging under Win32s. Ensure that
a monochrome adapter is installed in your machine and set the
Mono=yes flag in the [VideoOptions] section of TDW.INI:

     [VideoOptions]
     MONO=yes

See the online text file called TD_RDME.TXT for more information on
using TD32 and TDW.


Using Tools with NTFS
---------------------
When using Borland C++ 4.02 tools under NTFS, be aware of assumptions
about file extensions. If Borland C++ 4.02 tools see an extension,
they assume no default. Therefore, with "bcc32 test.1.cpp", BCC32
spawns TLINK32 with "-ap c0x32.obj test.1, test.1, import32 cw32".
As TLINK32 sees an extension on test.1, it makes NO assumptions about
a .obj or .exe extension.  It attempts to look for test.1 (instead of
test.1.obj) and to create test. (instead of test.1.exe).

Embedded blanks in filenames are not currently supported. For
instance, under the Windows NT NTFS file system it is legal to have a
file named "This is an interesting file name.cpp". The response file
processing in our 32-bit tools cannot handle this type of file.

16-bit tools running on NT cannot use NTFS filenames.


NOEHxx Libraries
----------------
Purpose:

The NOEHxx libraries eliminates the overhead of exception-handling code in
the run-time library for users who don't need it and who do rely on any
libraries that require it.

How to use:

A NOEHxx library must be linked in before the standard runtime library.
For command-line tools this can be accomplished by specifing the appropriate
NOEHxx library on the BCC command-line, or making it the first library given
to TLINK.

For the IDE, add the approriate library to the project using AddNode.
To ensure the NOEHxx library is processed before the standard libraries,
turn on "Show Runtime Nodes" in the Options|Environment|ProjectView dialog.
From the project window you can move the library up and down using the
ALt-<arrow> keys. Be sure the NOEHxx library appears before other standard
libraries. Note: use NOEHWL.LIB when building DPMI16 programs.

What they do:

The NOEHxx libraries resolve calls to exception-related compiler helper
functions to dummy functions that return appropriate return values. They
also restore the pre-exception behavior of operator new to return NULL on
out of memory conditions. Non-exception enabled versions of setjmp() and
longjmp() are also provided.

Limitations:

Note: some features introduced in BC4.0 require exception handling.
These include the string class, BIDS container classes, the standard
OWL libraries, and RTTI.


Running from a Windows 3.1 DOS Prompt
-------------------------------------
If you run BCC or TLINK from a Windows DOS box and you get
out of memory errors, increase the XMS memory (in the 'Maximum'
setting) allocated for the DOS box by editing the appropriate .PIF
file (usually DOSPRMPT.PIF). BCC.EXE needs about 4MB to compile
medium-sized .CPP files, and might need more memory for large .CPP
files with debugging information.

NOTE: You must set the 'Maximum:' setting to the amount needed, not
      the 'Required:' setting.  Using the 'Required:' setting only
      sets aside memory for XMS, NOT for DPMI services and hence
      any amount set in the 'Required:' setting box is unavailable.


C/C++ Language Changes
----------------------
Many changes were made to the compiler in compliance with the
latest changes proposed by the ANSI C++ committee.  These include
three distinct char types, enhancements to templates, support for
virtual functions differing in return types, and other improvements
listed here.  See the Library Reference and the Programmer's Guide
for complete details on these changes and how they affect your
code.

wchar_t is a fundamental data type in C++ programs. In C programs it
continues to be a typedef defined in stddef.h. See online Help.

Enum operator overloading is also supported.

The runtime library now supports the ANSI C++ string class.  If you
already have a string class, it must be renamed for Borland C++ 4.0.

In addition, operator new and operator new[] now throw an
exception (xalloc), as specified by the ANSI C++ committee.
To get the old behavior, you can issue set_new_handler(0). 
(set_new_handler(0), however, does not work with ObjectWindows
or string classes.) See Chapter 3 of the Programmer's Guide.

Arrays are now being allocated through operator new[]() and deleted
by operator delete[](). An example is provided in Chapter 3 of the
Programmer's Guide.

Borland C++ 4.02 implements ANSI C++ runtime type identification (RTTI). See
the Library Reference, "C++ runtime support",  for a description of
class Type_info. RTTI and operator typeid() are fully described in
Chapter 3 of the Programmer's Guide.

Borland C++ 4.02 provides a full implementation of exception handling
under C++ and C.  C exceptions can be handled in C or C++ code;
C++ exceptions can be handled only in C++ code. The C++ exceptions are
described in the Library Reference, "C++ run-time support." See Chapter 4
of the Programmer's Guide for a full description of how to use exception
handling.

Borland C++ 4.02 also implements the accepted ANSI C++ new style casts.
See the Chapter 3 of the Programmer's Guide for information and
examples.


Creating .COM Files
-------------------
Creating .COM files requires setting the compiler to the tiny memory
model, telling the linker to make a .COM file, and linking to the
CT.LIB library.  The IDE does not generate .COM files but the
command-line tools do.  For example:

     bcc -mt -lt file.cpp ct.lib


Converting Borland C++ 3.1 Windows Code to Borland C++ 4.02
-----------------------------------------------------------
To get your BC++ 3.1 code to compile and run under Borland C++ 4.02,
modify your code to reflect three character types where compiler
errors occur when using the Borland C++ 4.02 RTL includes.
Alternatively, you can use the -K2 compiler option with the RTL
includes from BC++ 3.1. This option provides for only two character
types. (Note that -K2, a backward compatibility switch, is supported
only in the 16-bit compiler.) Also, use operator new[]() and
delete[]() syntax for class arrays.

Some 32-bit to 8-bit conversions allowed by ANSI are flagged by
BCC32 with "Conversion may lose significant digits in function
XXXXX".  You can safely ignore this message if you are doing certain
types of 32-bit to 8-bit casts (for instance, int to char) and you're
not worried about losing significant digits in those cases.


Floating-Point Formats
----------------------
Floating-point formats are a collection of formatting information used to
manipulate floating point numbers in certain runtime library functions such
as scanf() and atof().

This section discusses why you might get the error
FLOATING POINT FORMATS NOT LINKED : ABNORMAL PROGRAM TERMINATION and tells
you how to resolve it.

There are no current plans to fix this because it is not a bug. The
intent is to avoid linking the floating-point formats (about 1K of
overhead) when they are not required. The tradeoff is that the
programmer must explicitly request that the floating-point formats be
linked in for some programs that manipulate floats in a limited and
specific fashion.

Because you can get this error in a number of different ways, check the
following list of potential causes to find out how to resolve the error.
The causes are listed in order of most common to least common.

  1.  CAUSE:  Floating point set to <None>.  You have your
      floating point option set to None when it should be set to
      either Fast or Normal.

      FIX:  Set Floating Point to Fast or Normal.

  2.  CAUSE:  Either the compiler is over-optimizing, or the
      floating-point formats really do need to be linked in because
      your program manipulates floats in a limited and specific
      fashion. Under certain obscure conditions, the compiler will
      ignore floating point usage in scanf() (e.g., trying to
      read into a float variable that is part of an array contained
      in a structure.)

      FIX: Add the following to one source module:

              extern _floatconvert;
              #pragma extref _floatconvert

  3.  CAUSE:  Forgetting to put the address operator & on the scanf
      variable expression. For example,
          float foo;
          scanf("%f", foo);

      FIX: Change the code so that the & operator is used where it
      is needed.  For example, the above code should be
          float foo;
          scanf("%f", &foo);


---------------------------
5.MISCELLANEOUS INFORMATION
---------------------------

Compiler/Libraries/Command-line Tools
-------------------------------------
If TLINK.EXE or any other 16-bit tool reports an "out of memory" error when
run from a makefile, use MAKER.EXE instead of MAKE.EXE.

The #define for _fstat in sys\stat.h needs to cast the second parameter to
a struct stat * so that MFC FILE.CPP will compile.

Because ANSI C++ states that printf() and cout must coexist, stdiostreams
is now redundant.

The definitions of string member functions find_first_of and find_last_of 
are incorrect (pp. 497, 498 of the Library Reference). The found character's
position is in the return value. Parameter pos specifies the location
within the string to begin searching.

The second definition of string member function compare is incorrectly
documented in the Libary Reference. The correct function syntax is

   int _RTLENTRY compare(const string _FAR &s,
                         size_t orig,
                         size_t n = NPOS );

The second parameter specifies where to begin comparing, and the third
parameter specifies the how many character to compare.

See online help for a description on the TRegexp class used by the
string class.

The description of the -vi compiler switch on page 60 of the User's Guide
is incorrect. When -vi is on NO inline substitution will occur. When -vi is
off, inline substitution WILL occur.


IDE
---
You must explicitly close 32-bit applications run under the Project
Manager; exiting the Project Manager will not terminate them.

MAKE logic is based on the time and date stamps, so it is necessary to
perform a "build" after switching a target from 16-bit to 32-bit or vice
versa, or when switching between memory models in 16-bit applications.

The IDE restricts command-line length to 128 characters. You can redefine
the command-line length in BCW.INI by adding

   [Transfer]
   cmdlen=512   ;user-definable command-line length limit

To get the WHEREIS example to build using the IDE, change the assembler1
tool (using Options|Tools) from:

  /m /dMDL=small /zi $tasm

to:

  $NOSWAP $SAVE CUR $CAP MSG(TASM2MSG.DLL) /m /dMDL=small
  $NAME($EDNAME)$EXT($EDNAME), $OUTNAME

Miscellaneous
-------------
Incompatibilities between the 3/10/94 version of the ATI Ultra (Mach 8)
video driver and Borland C++ will cause crashes under various conditions.
Borland recommends using the 8514/A compatible driver when using Borland C++,
or to try a later version of the ATI Ultra (Mach 8) driver when available.

