
                             WELCOME TO THE BORLAND
                               POWERPACK FOR DOS

This README file contains important information about the Borland PowerPack
for DOS. For the latest information about this product and its accompanying
programs and manuals, read this entire file.

-----------------
TABLE OF CONTENTS
-----------------

1.  How to Get Help
     -Sources of information
2.  Installation
     -Performing custom installations
3.  Features
     -BGI
     -Compatibility
     -Windows/Win32 API Emulation
     -Function implementation
     -Debuggers
4.  Important Information
     -Delivering the Application
     -Additional APIs
     -TLookupValidator class
     -Using the QEMM memory manager
     -Turbo Vision palette changes
     -NOEHxx Libraries
     -Debuggers
     -Recompiling Existing Turbo Vision Applications
     -TPicResult Type and vsXXXX Constants
     -Using the Paradox Engine with PowerPack for DOS
5.  Miscellaneous Information

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

SOURCES OF INFORMATION
----------------------
  If you have any problems, please read this file, and
  check the on-line help and the PowerPack and 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
---------------
For more install information see the online-text file PINSTALL.TXT.

The Borland PowerPack requires Borland C++ version 4.02 or later. 
If you do not have version 4.02 or later of Borland C++ contact 
the Borland Order Desk at 1-800-645-4559 to upgrade.  Outside of 
North America, contact your local Borland office.

Make sure you specify the correct directory that you installed 
Borland C++ into during install.

Make sure you have turned ON the "CD-ROM:" entry if you have performed a
CD-only configuration installation of Borland C++. Also make sure you have
entered the full path to the BIN directory for the "CD-ROM Binary Directory"
option (e.g. D:\BC4\BIN).

   IMPORTANT:  Make sure to remove any overlay switches from your makefiles
   and projects if you are converting an overlaid application to a DOS
   extended application.  Overlays are not compatible with DOS extended
   applications, and are, in fact superfluous.

Note: make sure that \BC4\BIN comes before comes before any PowerPack path
in you PATH settings.


Performing custom installations
-------------------------------
If you are going to build 16-bit applications, you will need the 16-bit
command-line tools, the 16-bit Turbo Debugger, the 16-bit large-model
Run-time Library, and the 16-bit Class Library from Borland C++.
When performing a Custom install of Borland C++, make sure the 
following options are turned on:

   Customize Installation for Borland C++ Product - 16-bit Windows, DOS

   Borland C++ Tools - Command Line Tools, Debugger, Visual Tools, Run-time
   Libraries, Class Library

   Borland C++ Debugger - Turbo Debugger

   Borland C++ Run-time Libraries - all options on

   Borland C++ Class Libraries - all options on


If you are going to build 32-bit Applications, you will need the 32-bit
command-line tools, the 32-bit debugger, the 32-bit RTL libraries,
and the 32-bit class Libraries from Borland C++. When performing a
Custom install of Borland C++, make sure the following options are turned on:

   Customize Installation for Borland C++ Product - 32-bit Windows, DOS

   Borland C++ Tools - Command Line Tools, Debugger, Run-time
   Libraries,  Class Library

   Borland C++ Debugger - Turbo Debugger

   Borland C++ Visual Tools - Integrated Development Environment (IDE)

   Borland C++ Run-time Libraries - all options on

   Borland C++ Class Libraries - all options on


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

Borland PowerPack for DOS lets you build 16-bit and 32-bit DOS extended
applications. There is full support for 16-bit and 32-bit protected mode BGI
and Turbo Vision.

You can generate DOS extended applications from the IDE by selecting the
appropriate target from the TargetExpert selection list. To enable DPMI
targeting and Turbo Vision for DOS in the IDE your BCW.INI file should
contain these lines (automatically added by INSTALL):

[AddOns]
addon000=bcwdpmi.dll

The installation of the PowerPack will not always use addons000. If you have
previously installed a product that uses this section, the install program 
will use "addon001" or the first free number in sequence.

The following section will also be added:

[dpmi]
bcinclude=C:\BC4\INCLUDE
bclib=C:\BC4\BIN

BGI
---
BGI support for DOS extended applications follows a slightly different model
from real mode. Now there are BGI DLLs. The BGI16.DLL contains most of the
graphics library functionality. There are still separate driver files as in
the old DOS BGI. The 32-bit BGI has a BGI32.DLL which provides support similar
to BGI16.DLL. However, the 32-bit drivers are implemented as DLLs. The 32-bit
drivers are kept in the \BC4\BGI directory for consistency.

Instead of linking with GRAPHICS.LIB, you should link with BGI16.LIB or
BGI32.LIB, for 16-bit and 32-bit applications, respectively.

Note: using BGI in a DOS extended application requires that
you have the BC4\BGI directory in your path.

Compatibility
-------------
32-bit DOS extended applications which use the ANSI C/C++ functions
should run unmodified under NT.

32-bit DOS extended applications in general should run under DOS,
NT, Windows 3.1 DOS boxes, Windows 3.11 DOS boxes and OS/2 2.x DOS
boxes.  Applications which use interrupts or IO instructions, or
expect to have direct access to video/DOS memory will generally
fail to run under NT.

16-bit DOS extended applications should run unmodified under DOS,
NT, Windows 3.1 DOS boxes, Windows 3.11 DOS boxes and OS/2 2.x DOS
boxes.


Windows/Win32 API Emulation
----------------------------
The 16-bit and 32-bit extenders support emulation of most of the Windows and
Win32 APIs. The libraries DPMI16 and DPMI32 include import records for those
APIs which are emulated, so use of an unimplemented API will result in
link time errors. If you need to use an API which is not implemented
by the extenders, you can hook unresolved APIs and provide resolution
for them at run time. To do this, you need to implement and export
a hook function as follows:

    FARPROC WINAPI _export BorlandUnresolvedEntryHook (LPCSTR modName,
                                                       BOOL byOrdinal,
                                                       LPCSTR entry);

The first parameter is the name of the module for the function, for
example, "KERNEL".  The second parameter tells whether the third
parameter is a string or an ordinal value.  If it is FALSE, then the
third parameter is a string naming the unresolved entry, for example,
"GETATOMNAME".  Your hook function should determine if it is has an
implementation for this entry.  If it does, it should hand back a
pointer to the function.  This will be used by the loader to resolve
the references in the image.

There are a few restrictions to this functionality:

    - Your hook function may be called before the RTL has initialized.
      It may therefore call strcmp and a few related string functions,
      but little else.  It should not attempt to do I/O, or
      allocations.

    - If the application is a 16-bit application, the hook function
      should be in the first segment in the image, and this should be
      a preload segment.  The hook function will have access to the
      automatic data segment.

    - The function should not call any unimplemented APIs.


Function implementation
-----------------------
The int86, int86x, intdos, intdosx, and intr RTL functions will not be
supported on DPMI32. The int386 and int386x RTL functions should be used
instead.


Debuggers
---------
Two debuggers are available:
       TD.EXE for 16-bit application debugging
       TD32.EXE for 32-bit application debugging


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

Delivering the Application
--------------------------
16-bit applications will always need to ship with the following files:

   RTM.EXE
   DPMI16BI.OVL

If these applications use BGI, you will have to ship BGI16.DLL, plus
the appropriate BGI drivers and fonts.

32-bit applications will always need to ship with the following files:

   32RTM.EXE
   DPMI32BI.OVL

If these applications use BGI, you will have to ship BGI32.DLL, plus
the appropriate BGI drivers and fonts.

If your 32-bit application will be run under a DOS box under Windows
3.1 or later, you will need to install WINDPMI.386 in the
user's SYSTEM.INI file. These files need to be on your path, or in the
same directory as the application.

Additional APIs
---------------
The following additional Windows APIs, not listed in the printed documentation,
are emulated under DPMI16:

   _lclose
   _lread
   _lcreat
   _lseek
   _lopen
   _lwrite
   wsprintf
   AnsiToOemBuff
   GetCurrentTime
   GetDesktopWindow
   GetExePtr
   GetPrivateProfileInt
   GetPrivateProfileString
   GetProfileInt
   GetProfileString
   GetSystemDirectory
   GetTickCount
   GetWindowsDirectory
   OemToAnsiBuff
   OpenFile
   WritePrivateProfileString
   WriteProfileString

TLookupValidator Class
----------------------
The following validator class has been added to the product, but was
not listed in the printed documentation:

   TLookupValidator                                 validate.h
   -----------------------------------------------------------
A lookup validator compares the string typed by a user with a list of
acceptable values. TLookupValidator is an abstract validator type from which
you can derive useful lookup validators. You will never create an instance
of TLookupValidator. When you create a lookup validator type, you need to
specify a list of valid items and override the lookup method to return
True only if the user input matches an item in that list. One example of a
working descendant of TLookupValidaor is TStringLookupValidator.

Member functions:

   isValid       virtual Boolean isValid( const char *s );

Calls lookup to find the string s in the list of valid input 
items.  Returns True if lookup returns True, meaning lookup found 
s in the list; otherwise, return False.

see also:  TLookupValidator::lookup

   lookup       virtual Boolean lookup( const char *s );

Searches for the string s in the list of valid entries and 
returns True if it finds s;  otherwise, returns False.  
TLookupValidator's lookup is a pure virtual function that always 
returns False.  Descendant lookup validator classes must override 
lookup to perform a search based on the actual list of acceptable 
items.

Using the QEMM memory manager
-----------------------------
If you use the QEMM memory manager comment out the following line from your
CONFIG.SYS file:

REM DEVICE=C:\QEMM\QDPMI.SYS SWAPFILE=DPMI.SWP SWAPSIZE=1024

This removes the QEMM DPMI Services Manager, which is not compatible with
Borland's DPMI Manager 32RTM. Only our tools (BCC32, MAKE, TLINK32,
TD32 etc.) will not run under the QEMM server. Your applications will
run under the QEMM server.

Turbo Vision palette changes
----------------------------
Turbo Vision 2.0's application palette has been expanded to include Blue
and Cyan dialog colors. In addition, the help colors have been incorporated
into the application palette. This could cause you to get undefined symbol
errors for cpColor, cpBlackWhite, cpMonochrome, cHelpColor, cHelpBlackWhite,
and cHelpMonochrome.

The cpXXXX palettes have been renamed cpAppXXXX. The cHelpXXXX palettes are
no longer defined because they were merged into the cpAppXXXX palettes. If
you are overriding TApplication::getPalette to add the help colors to the
application palette, remove your getPalette function. It is no longer needed.
The help colors are now part of the application palette, and you can use the
help system without any palette modifications.

If you are overriding TApplication::getPalette to extend the palette for your
own user-defined classes, you will need to modify the palettes returned by
your user-defined classes. The Turbo Vision 2.0 palette has been expanded
from 63 colors to 131 colors. This means your user defined classes probably 
return references to palette entries 64 and up. You will need to modify your
user-defined classes to return palette references 132 and up.

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 not 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.

Debuggers
---------
Borland's Turbo Debugger supports both 16-bit DPMI debugging (TD.EXE) and
32-bit DPMI debugging (TD32.EXE). DPMI support services are provided by
several files delivered with PowerPack for DOS, and are used by both
debuggers.

   - A new command-line switch has been added to TD32.EXE:  -vd.
     This switch enables the use of 32-bit DPMI video dlls. This
     allows users to create their own DPMI video dlls to access BGI
     video modes under dpmi.

     Usage of -vd switch:
           -vd<\path\video_dll_name>

     PowerPack for DOS provides SVGA32.DLL for 32-bit dpmi BGI
     support. It is used in conjunction with TD32.EXE. When the -vd
     switch is used with TD32.EXE, the default video_dll_name is
     SVGA32.DLL. No name needs to be supplied. SVGA32.DLL is the
     default and it must be located in the same directory as TD32.EXE.

     Three DOS environment variables can be set to enable specific
     options available when using SVGA32.DLL:

           set SVGA32=MONO    (enables TD32.EXE dual monitor support)
           set SVGA32=COLOR   (enables TD32.EXE on a color monitor, the
                               default behavior.)
           set SVGA32DEBUG=<filename>  (Output SVGA32 diagnostic info
                                        to a log file.)

     SVGA32.DLL is not required to debug 32-bit DPMI BGI applications.

   - 32-bit DPMI dual-monitor support is provided within SVGA32.DLL.
     To use this dual-monitor support, set the SVGA32 environment
     variable, as shown above, to MONO, and invoke TD32.EXE using
     the -vd command line switch.

   - Remote debugging of DPMI applications is not currently supported.

   - Mouse support is not currently provided for 32-bit dual-monitor
     debugging.

   - MS Mouse driver 9.01 has known problems which render it
     incompatible with TD32.EXE and TD.EXE under DOS. All other
     mouse drivers function properly.

Recompiling Existing Turbo Vision Applications
-----------------------------------------------
To recompile your existing Turbo Vision 1.0 applications with Turbo Vision
2.0, you must:

   - Change #include <tv.h> to #include <tvision/tv.h> in all files.

If you are compiling in the IDE, you also must:

   - Enable Turbo Vision support by right clicking on the EXE node in your
     project, selecting TargetExpert, turning on the Turbo Vision check box,
     and pressing OK.

   - Update your include path by changing
     Options|Project|Directories|Source Directories|Include to C:\BC4\INCLUDE.

   - Rebuild with Project|Build All to overwrite old OBJs.


TPicResult Type and vsXXXX Constants
------------------------------------
The following reference material is missing from the printed documentation:

=============================================================
TPicResult type                                    validate.h
=============================================================

Declaration  enum TPicResult = (prComplete, prIncomplete, prEmpty,
                                prError, prSyntax, prAmbiguous,
                                prIncompNoFill);

Function  TPicResult is the result type returned by the picture 
          member function of TPXPictureValidator.

See also  TPXPictureValidator::picture


=============================================================
vsXXXX constants                                   validate.h
=============================================================

          Function  Input line objects use vsOK to check that
                    their associated validator objects were
                    constructed properly. When called with a
                    command parameter of cmValid, an input
                    line object's valid member function
                    checks its validator's status field. If
                    status is vsOK, the input line's valid
                    returns True, indicating that the
                    validator object is ready to use.

                    The only value defined for status other
                    than vsOK is vsSyntax, used by
                    TPXPictureValidator to indicate that it
                    could not interpret the picture string
                    passed to it. If you create your own
                    validator objects, you can define error
                    codes and pass them in the status field.

            Values  The validate.h header file defines two
                    constants used by validator objects to
                    report their status:

Validator status constants
-----------------------------------------
Constant         Value     Meaning
-----------------------------------------
vsOK               0       Validator constructed properly

vsSyntax           1       Error in the syntax of either a
                           TPXPictureValidator or a
                           TDBPictureValidator
-----------------------------------------

See also  TValidator::status


Using the Paradox Engine with PowerPack for DOS
-----------------------------------------------
If you are using the Paradox Engine with executables created with the
DOS PowerPack, and you receive the runtime error message:

   Unable to locate GDI.DLL

this means that your executable attempted to load an old version of
PXENGWIN.DLL. Make sure that you are using version 3.01 of the Paradox Engine
and that there are no older versions being found first on your path. If you
do not have version 3.01 of the Paradox Engine you can obtain an upgrade by
calling the Borland Order Desk at (800) 645-4559. Outside of North America 
contact your local Borland office.


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

CD Only Configuration Install
-----------------------------
If you have done the CD Only Configuration install, you will need to update
your Turbo Vision example files by doing the following:

  For each example

     - Select the Options menu

     - Select the Project option

     - Modify the Include Source Directory to show
       <CD-ROM drive>:\BC4\INCLUDE;<path you installed the PowerPack to>

     - Modify the Library Source Directory to show
       <CD-ROM drive>:\BC4\LIB;<path you installed the PowerPack to>.

     - Press the OK button.

Doing these steps sets both your CD-ROM INCLUDE and LIBRARY paths, and your
PowerPack INCLUDE and LIBRARY paths.

If you have done the CD Only Configuration install, then you must change
the BC DOS & Library Icon help-file path (in the Borland C++ group) from
the CD to your hard drive.

Changing Target Type
---------------------
If you change the target type for an application from DPMI16 to DPMI32 or
vice-versa, you must rebuild the application. If you only request a MAKE,
the application will not be built correctly, because MAKE logic is based
on the time and date stamp.

Reinstallation
--------------
If you reinstall any portion of Borland C++ after installing the
PowerPack, some PowerPack environment settings may be lost.
If this happens, reinstall the PowerPack.

Phar Lap Compatibility
----------------------
When running protected-mode applications that use Phar Lap's DOS extender
and which will spawn applications using Borland's DOS extender (for example
NMAKE), load 32RTM first. This will cause Borland's DPMI server to be used,
which is compatible with both DOS extenders.
