
  PRODUCT  :  Borland C++                           NUMBER  :  1006
  VERSION  :  3.0
       OS  :  DOS
     DATE  :  April 9, 1993                            PAGE  :  1/4

    TITLE  :  Overlaying Turbo Vision


  BACKGROUND
  ==========

  In order to create an overlaid Turbo Vision program, one must
  have the Turbo Vision Source code and a copy of Turbo Assembler
  (v2.5x, or above).  If you have problems with the assembler
  running out of memory, download TI1331, which will explain how to
  run TASMX, the DPMI protected mode assembler, from the IDE or
  from BCC.


  OVERVIEW
  ========

  1. Rebuild the Turbo Vision Library to include overlay support
  and move certain non-overlayable object modules to a second
  library.

  2. Set up a project file for the overlaid program and make sure
  that all the correct options are set for overlaid program,
  including -Vs and -B.  If you prefer using the command line
  tools, you can create an analogous Makefile.

  3. Add TV.LIB and the second library you created in step one,
  above, to the project and mark TV.LIB as overlayable.


  REBUILDING FOR OVERLAYS
  =======================

  In order to use Turbo Vision in an overlaid program, TV.LIB must
  be rebuilt.  Change directory to the Turbo Vision Source code
  directory (ex. C:\BORLANDC\TVISION\SOURCE ) and run this command:

       MAKE -B -DOVERLAY

  This will generate a new copy of TV.LIB which can be overlayed.
  It will also create two .OBJ files, SYSINT.OBJ and TEVENT.OBJ.
  These two files contain code for TV's interrupt handlers and
  cannot be overlayed.  In addition, there are a few other OBJ
  files still in the library which cannot be overlaid either since
  they include code that could be called from Turbo Vision's
  critical error handler.  These can be extracted from the library
  with the following command:

       TLIB TV.LIB -*SYSERR -*TSCREEN -*DRIVERS -*DRIVERS2
            -*SWAPST -*TEVENT -*SYSINT

  Create a new library called TVNO.LIB that consists of the
  aforementioned OBJ files that should not be overlaid.  Use the
  following command to do this:

       TLIB TVNO.LIB -+TEVENT -+SYSINT -+TSCREEN -+SYSERR
            -+DRIVERS -+DRIVERS2 -+SWAPST


  SETTING UP THE PROJECT
  ======================

  Create a project file that includes all the source modules and
  libraries used by your program.

  First, go to Options|Application and select <Dos Overlay>.  Then
  sure to set the following options:

       Options|Compiler|Code Generation : Large Model
       Options|Compiler|Code Generation : Compile Via Assembler
       Options|Compiler|C++ Options : Local Virtual Tables
       Options|Linker|Libraries : Unmark Turbo Vision

  Of course if there are any other options needed for the project,
  such as <Word Alignment> or <Optimizations> set those at this
  time, as well as marking the appropriate modules in the project
  to be overlaid or not as desired.


  OVERLAYING TV.LIB
  =================

  Now, add TV.LIB and TVNO.LIB to the project.  In their respective
  local options screens, mark <Overlay This Module> for TV.LIB and
  leave it blank for TVNO.LIB.  It is imperative that TVNO.LIB not
  be overlaid.

  Now select <Compile | Build All> to build the program.


  COMMAND LINE EQUIVALENTS
  ========================

  If using a Makefile and the command line tools, the following
  options for BCC are equivalent to the options listed in step 2:

       -Y, -Yo        Compile for Overlays
       -ml            Large Model
       -B             Compile Via Assembler
       -Vs            Local Virtual Tables

  Your command line will look something like this:

       bcc -Vs -B -ml -Yo myfile.cpp -Yo- tvno.lib -Yo tv.lib


  IMPORTANT!!
  ===========

  Be sure to use the same BC switches outlined in the makefile when
  compiling your source code to be overlayed with the new overlayed
  Turbo Vision library! (i.e. use the -Vs and -B switches  -  In
  the IDE use OPTIONS|COMPILER|C++ OPTIONS|LOCAL VIRTUAL TABLES
  and  OPTIONS|COMPILER|CODE GENERATION|COMPILE VIA ASSEMBLER ).


  TROUBLESHOOTING
  ===============

  If the assembler runs out of memory when assembling one of the
  files built by the compiler, use TASMX, the protected mode
  assembler, instead.  Download TI1331 for instructions on how to
  set up the Assember Transfer item to call TASMX.

  If warning "No stub for fixup at SEGMENT:XXXXh in module MODULE"
  is generated, most likely not all modules in the project are
  being compiled with -B and -Vs, or that the Turbo Vision library
  was not compiled with overlay support.  Double check that the
  steps in this document have all been followed correctly and
  rebuild the program with <Compile | Build All>.


  INCREASING PERFOMANCE
  =====================

  To improve performance of an overlaid Turbo Vision application it
  may be helpful to increase the size of the global variable
  __ovrbuffer to 0x2000 or greater.  This will set up an 128K
  overlay buffer.


  EXAMPLE
  =======

  Here are explicit instructions for overlaying the TVFORMS program
  in TVISION\DEMOS.  These instructions assume that the Turbo
  Vision library has been recompiled for Overlay support as
  described above:

       - Change directory to \BORLANDC\TVISION\DEMOS
       - Run BC and open TVFORMS.PRJ as a project.
       - Make these changes:
            Options | Application : Choose DOS Overlaid.
            Options | Compiler | Code generation : Reset to Large
                                                   Model
            Options | Compiler | Code generation : Select compile
                                                   via Assembler
            Options | Compiler | C++ options : Select Local Virtual
                                               Tables
            Options | Linker | Libraries : Uncheck Turbo Vision
       - Add TV.LIB and TVNO.LIB to the project file.
       - In the project window, select TV.LIB and any other source
       module you wish to overlay.  On each, select the name, type
       <Ctrl-O> and mark <Overlay This Module> on the Local Menu
       Dialog that appears.
       - Do not overlay TVNO.LIB.
       - Selecting <Compile | Build All> will now build an overlaid
         version of TVFORMS.









