
               WELCOME TO TURBO PASCAL DATABASE TOOLBOX 4.0
               --------------------------------------------

  This README file contains important information about Turbo Pascal
  Database Toolbox 4.0. Please read it in its entirety and refer to it
  for the latest information about the compiler and accompanying
  programs.


TABLE OF CONTENTS
-----------------
  1. How to Get Help (!)
  2. Corrections/Additions to the Manual
  3. New Features
  4. Converting Data Files from Turbo Access 1.0 to 4.0 Format
  5. Unpacking and Using TOOLS.ARC
  6. Compiling Turbo Access for Generic MS-DOS Computers
  7. Important Tips
  8. Files on the Disks


1. HOW TO GET HELP
------------------
  If you need help with the Turbo Pascal Database Toolbox, please
  read this file and the Reference Manual.

  If you still have a question and need technical assistance, help is
  available from the following sources:

  1. Type GO BPROGA on the CompuServe bulletin board system for instant
  access to the Borland forums with their libraries of technical
  information and answers to common questions. In addition, all
  example programs from the manual are available on CompuServe in
  machine-readable form.

  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 online charges.

  2. Check with your local software dealer or users' group.

  3. Write to:  Borland International
                Turbo Pascal Database Toolbox Technical Support
                4585 Scotts Valley Drive
                Scotts Valley, CA 95066

  Please remember to include your serial number or we will be unable
  to process your letter.

  4. If you have an urgent problem that cannot wait, you can call the
  Borland Technical Support Department at (408) 438-5300.

    Please have the following information ready before calling:

    A.  Product name and serial number from your original distribution
        disk. Please have your serial number ready or we will be
        unable to process your call.

    B.  Computer brand, model, and the brands and model numbers of any
        additional hardware.

    C.  Operating system and version number (the version number can be
        determined by typing VER at the DOS prompt).

    D.  Contents of your AUTOEXEC.BAT file.

    E.  Contents of your CONFIG.SYS file.

    F.  Contents of your TACCESS.ERR file.


2. CORRECTIONS/ADDITIONS TO THE MANUAL
--------------------------------------
  Page 5: On Disk 2
    We have included the utility UNPACK.COM instead of ARCX.COM for
    dearchiving compressed .ARC files.

    There is an additional file on disk 2 called TOOLS.ARC.  Look
    under the section titled "UNPACKING AND USING TOOLS.ARC." in this
    README file for more information.

  Page 14: Program Header
    If you are using LSort unit, the header will look like this:

      program SortExample;
      uses LSort;

  Page 17:
    Top of page

    To look at the Turbo Pascal Sort sample programs, put your Turbo
    Pascal Database Toolbox disk 2 into drive A, and at the DOS prompt
    type:

      A:UNPACK A:SORTEX

  Page 22: Quick Reference Guide to Sort Routines
    These are the correct calls to the LTurboSort and TurboSort
    functions:

      function LTurboSort(ItemLength : word;
                          InpPtr, LessPtr, OutPtr : ProcPtr) : byte;

      function TurboSort(ItemLength : word;
                          InpPtr, LessPtr, OutPtr : ProcPtr) : byte;

  Page 24: LTurboSort
    The Declaration should be:

      function LTurboSort (ItemLength : word;
                           InpPtr, LessPtr, OutPtr : ProcPtr): byte;

  Page 26: TurboSort
    The Declaration should be:

      function TurboSort (ItemLength : word;
                          InpPtr, LessPtr, OutPtr : ProcPtr): byte;

  Page 41: top of page
  
    The smallest data record allowed is 18 bytes . . .

  should be:

    The smallest data record allowed is 14 bytes . . .

  Page 42: Figure 4.1
    The message at the bottom of the window should read:

      See TAccess.Err for more information

  Page 47:
    Second paragraph, last sentence

    The strings returned by IntToStr are two characters long; the
    strings passed to StrToInt must likewise be two characters long.

  Page 49:
    Replace the keyword "otherwise" with "else" in the bottom of the
    case statement.

  Page 53:
    The header for the procedure OpenIndexFile should be changed to:

      procedure OpenIndexFile (var CodeIndex : IndexFile;
                                   FName     : FileName;
                                   KeySize   : byte;
                                   Dups      : byte);

  Page 62:
    First sentence:

      A:\UNPACK A:\TADEMO

    Middle of BTREE.PAS--A Customer Database

      Put the Turbo Pascal Database Toolbox Disk 2 into drive A, and
      at the DOS prompt type

        A:\UNPACK A:\BTREE

      Copy EDITLN.PAS to your system by entering

        A:\UNPACK A:\TOOLS

    Note: See the section "UNPACKING AND USING TOOLS.ARC" in this
          README file for information concerning the MISC.ARC file.

  Page 65:
    In the procedure OpenDataSet, replace the filenames
    'Customers.dat' and 'Customers.idx' with 'Customer.dat' and
    'Customer.idx.'

  Page 71: Compiling TAHIGH.PAS
    UNPACK should be used instead of ARCX.

  Page 75: MaxDataRecSize
    Under Declaration

      const MaxDataRecSize = (a word, 14..65,521, giving maximum
                              data record size)

    Under Remarks

       Writeln ('The size of Myrec is ',SizeOf(MyRec));

  Page 79: PageSize
    Under Remarks

      The number of bytes, N, occupied by each page in an index
      file is found as follows:

         N = (KeySize + 9) X PageSize + 5

      where KeySize is the key length for the index file.

      . . .

      By combining the above two equations, it can be seen that
      the major determinant of index file size is the KeySize:

         D = 2 X E X (KeySize + 9) + ((6 X E) / PageSize)

  Page 81: Low Level Calls
    These are the correct calls to MakeFile and OpenFile:

      procedure MakeFile (var DatF:DataFile; FileN:FileName; 
                              RecLen:word);

      procedure OpenFile (var DatF:DataFile; FileN:FileName; 
                              RecLen:word);

  Page 82: 
    Under Index File Initialization

      These are the correct calls to MakeIndex and OpenIndex:

        procedure MakeIndex(var IndexF:IndexFile; FileN:FileName;
                                KeyLen, Status: byte);

        procedure OpenIndex(var IndexF:IndexFile; FileN:FileName;
                                KeyLen, Status: byte);

    Under Index File Search

      This is the correct call to SearchKey:

          procedure SearchKey(var IndexF:IndexFile;
                              var DataRef:longint;
                              var Key);

  Page 83: DataSet Initialization
    These are the correct calls to TACreate and TAOpen:

      procedure TACreate(var DatSet:DataSet;
                         var Name:FileName;
                             RecordLen:word;
                             IndexFName:FileName;
                             KeyLen:byte);

      procedure TAOpen(var DatSet:DataSet;
                       var Name:FileName;
                           RecordLen:word;
                           IndexFName:FileName;
                           KeyLen:byte);

  Page 88: CloseFile
    Under Example, the variable declaration for the program should
    be:

      var
        CustomerFile : DataFile;

  Page 93: EraseFile
    This is an expanded example of how to erase a datafile:

    var
      CustFile : DataFile;
      ...

    begin
      EraseFile (CustFile);
      if not OK then
        Writeln('Customer data file could not be erased.');
    end.

  Page 94: EraseIndex
    This is an expanded example of how to erase an indexfile:

    var
      CodeIndex : IndexFile;
      ...

    begin
      EraseFile (CodeIndex);
      if not OK then
        Writeln('Code index file could not be erased.');
    end.

  Page 100: MakeFile
    This is the correct Declaration for MakeFile:

      procedure MakeFile(var DatF : DataFile;
                             FileN : FileName;
                             RecLen : word);

  Page 101: MakeIndex
    This is the correct Declaration for MakeIndex:

      procedure MakeIndex(var IndexF : IndexFile;
                              FileN : FileName;
                              KeyLen, Status : byte);

    Under the Function description, the last sentence should read:

    If OK is False, there is no space on the disk or directory for a
    new file, or the disk is write protected.

  Page 103: OpenFile
    This is the correct Declaration for OpenFile:

      procedure OpenFile(var DatF : DataFile;
                             FileN : FileName;
                             RecLen : word);

  Page 104: OpenIndex
    This is the correct Declaration for OpenIndex:

      procedure OpenIndex(var IndexF : IndexFile;
                              FileN : FileName;
                              KeyLen, Status : byte);

    Under the Function description, the first sentence of the second
    paragraph should read:

    On exit, the OK flag is set to True if the file was opened
    successfully.

  Page 108: SearchKey
    This code finds all the names that begin with an S:

      Name:='S';
      SearchKey(IndexF,DataRef,Name);
      While OK and (Name[1] = 'S') Do
       Begin
         Writeln (Name);
         NextKey(IndexF,DataRef,Name);
       End;

  Page 110: TACreate
    This is the correct Declaration for TACreate:

      procedure TACreate(var DatSet : DataSet;
                           DatFName : FileName;
                           RecordLen : word;
                           IndexFName : FileName;
                           KeyLen : byte);

  Page 113: TAFlush
    TAFlush is located in the file TAHIGH.PAS, not TACCESS.PAS.

  Page 116: TAOpen
    This is the correct Declaration for TAOpen:

      procedure TAOpen(var DatSet : DataSet;
                           DatFName : FileName;
                           RecordLen : word;
                           IndexFName : FileName;
                           KeyLen : byte);

  Page 142: Deleting Keys
    First sentence

    "Turbo Basic Access" should be "Turbo Pascal Access."

  Page 152:
    Item #4

    After the Uses statement, you should insert:

      {$I MyProg.typ}

  Page 153:
    Second sentence

    Replace with:
      This allows you to close files and perform any other cleanup
      work that your program requires.

    Converting Turbo Pascal Access Data and Index Files
      To dearchive CONVERT.ARC you should enter at the DOS prompt:

        A:\UNPACK A:\CONVERT

  Page 155:
    Last sentence

    Replace with:

      A:\UNPACK A:\REFLEX

  Page 156:
    Listing of ASSET.FD

    The number of fields in the record should be 7.

  Page 160:
    In the listing of the extension to the ASSET.FD file, you must
    change the specification of:

      Buyer[25]     Buyer.idx
      NoDuplicates

    to an index file that does have duplicate keys:

      Buyer[25]     Buyer.idx
      Duplicates

  Page 161:
    To compile and run BUILDKEY.PAS for the ASSET example you must
    type:

      TPC buildkey /M /Rasset


3. NEW FEATURES
---------------
  Version 4.0 of the Turbo Pascal Database Toolbox contains many
  additional utilities and enhancements for your use.  These include:

  *  Unitized Turbo Access (TACCESS.PAS) and Turbo Sort (SORT.PAS)
     modules

  *  Turbo Access now supports databases with over 2 billion records.

  *  New Turbo Access routines FlushFile and FlushIndex will insure
     physical disk writes in order to save databases.

  *  A unit of high-level routines (TAHIGH.PAS) for manipulating
     data sets.

  *  A utility to configure the Turbo Access units (TABUILD.EXE) for
     your database applications.

  *  A large sort unit (LSORT.PAS) for sorting over 2 billion
     records.

  *  The program TRAINER.EXE that demonstrates how B+Trees are
     implemented.

  *  A set of utilities (EXPORTR, IMPORTR, GENTYPE, and BUILDKEY)
     that allow you to convert REFLEX database files to Turbo Access
     files and vice versa.

  *  A greatly enhanced version of the BTREE.PAS sample program.

  *  A sample program that will sort any textfile (TEXTSORT.PAS).


4. CONVERTING DATA FILES FROM TURBO ACCESS 1.0 TO 4.0 FORMAT
------------------------------------------------------------
  The program called CONVERT.PAS (located in CONVERT.ARC) will
  convert Turbo Access 1.0 file formats to the new 4.0 format. 
  To achieve this, the programmer must specify the configuration
  of their database by setting constants in the file
  TEMPLATE.NFO.  There is specific documentation concerning how
  to copy and modify TEMPLATE.NFO at the top of the CONVERT.PAS file.

  CONVERT.PAS comes configured with an example template,
  BTREE.NFO, which will convert the sample data and index files
  from BTREE 1.0 to a format that can be read by the new BTREE
  program.  There is documentation at the top of the CONVERT.PAS
  file describing the steps to converting the BTREE files.


5. UNPACKING AND USING TOOLS.ARC
--------------------------------
  The file called TOOLS.ARC on disk 2 contains the source code to
  three units called MISCTOOL, FILEUTIL, and EDITLN.  These units
  are used by the programs in the archived files BTREE.ARC,
  SORTEX.ARC, REFLEX.ARC, and MISC.ARC.  It is recommended that
  you set up a directory that contains the unpacked files in
  TOOLS.ARC.  Put the Turbo Pascal Database Toolbox Disk 2 into
  Drive A, and at the DOS prompt type:

    MD \TOOLS
    CD \TOOLS
    A:\UNPACK A:\TOOLS

  In order to recompile many of the .PAS files in BTREE.ARC,
  SORTEX.ARC, REFLEX.ARC, or MISC.ARC, you will have to set up a unit
  directory path to the TOOLS directory, which will contain the source
  to the units MISCTOOL, FILEUTIL, and EDITLN.  Please refer to
  Chapter 10 for information concerning unit directories within the
  integrated environment.  See also Chapter 12 of the Turbo Pascal 4.0
  Owner's Handbook for information concerning the /U command-line
  directive.  


6. COMPILING TURBO ACCESS FOR GENERIC MS-DOS COMPUTERS
------------------------------------------------------
  Since the TABuild program uses IBM specific calls, you will
  not be able to use this program on generic MS-DOS computers
  to customize Turbo Access for each database.  The following
  is an alternate method for compiling Turbo Access:

  1) Make a Turbo Access directory on your system (for example,
     TACCESS) and copy the following files from disk 1:
       TACCESS.PAS
       TASIZES.PAS
       TAHIGH.PAS (optional)

  2) When you want to start a new database project, create a
     subdirectory below the Turbo Access directory and set it as
     the logged drive.

  3) Create a record and key type definition file (as described in the
     manual) called MYPROG.TYP where MYPROG is the name of your
     program. Create and run the following program, to compute the sizes
     of your record and key(s).

program GenTAConstants;
{$I  MYPROG.typ} { Include user's record and key type definitions }
var
  OutFile : text;
begin
  Assign(OutFile, 'TAccess.def');
  Rewrite(OutFile);
  Writeln(OutFile, 'Const');
  Writeln(OutFile, '  MaxDataRecSize = ', SizeOf(MaxDataType):3,';');
  Writeln(OutFile, '  MaxKeyLen      = ', SizeOf(MaxKeyType) - 1:3,';');
  Writeln(OutFile, '  PageSize       =  16',';');
  Writeln(OutFile, '  Order          =   8',';');
  Writeln(OutFile, '  PageStackSize  =   5',';');
  Writeln(OutFile, '  MaxHeight      =   5',';');
  Close(OutFile);
end.

  Note: this program outputs the 6 constants used to configure Turbo
        Access.  The last 4 values are defaults which offer good
        performance and are fine for development of your database.
        If you want to calculate the optimal constants to speed up
        accesses to your database, see Appendix B for more information.

  4) TACCESS.DEF is an include file used by Turbo Access.  To compile
     Turbo Access, at the DOS prompt enter:

       >TPC ..\TACCESS /Q /DGENERIC /DTADebug

     /DGENERIC defines the symbol Generic which is used to make sure
               that only the "Generic" pieces of code in Turbo Access
               will be compiled.

     /DTADebug defines the symbol TADebug which means that extra error
               handling/reporting code will be compiled in.  Make sure
               to define this while developing your database.  When
               you are all done, you may want to recompile Turbo Access
               to create smaller/faster code.

  5) You can now optionally compile the unit of high-level calls,
     TAHIGH.PAS with the following command:

     >TPC ..\TAHIGH /Q /U..\ /DGENERIC /DTADebug

     /U..\ tells the compiler to look in the parent directory for
           units (in this case TACCESS).  Please refer to Chapter 12
           of the Turbo Pascal 4.0 Owners Handbook for
           information about command-line directives.

  6) Finally, copy TACCESS.TPU (and optionally TAHIGH.TPU) into
     your working directory, with the following command:

     >COPY ..\TA*.TPU

     You now have the Turbo Access (and TAHIGH) unit customized
     for your database.  You need not recompile this code unless
     you A) change your record or key structure or B) want to
     optimize the constants/code.


7. IMPORTANT TIPS
-----------------

  SORT UNIT REQUIRES FAR CALLS
  ----------------------------
  The calls made by the TurboSort function are from a separate unit
  (SORT) which requires a far call implementation with the $F
  compiler directive.  Failure to implement far calls will cause your
  Sort program to behave unpredictably.  For information on how to
  implement a far call for the TurboSort function, refer to the Turbo
  Pascal Database Toolbox 4.0 manual, pages 10-14.
  

  COMBINING HIGH AND LOW LEVEL DATABASE ROUTINES
  ----------------------------------------------

  The reference manual discusses two main types of database routines
  that you may call from your programs: the low level routines (found
  in TACCESS.PAS) and the high level routines (found in TAHIGH.PAS).
  You can use both the high and the low level routines in a single
  program.  The sample program called HITADEMO.PAS on disk 2 shows
  you how to accomplish this.

  In order to retrieve information from a dataset (initially created
  with high level routines) with calls to low level routines, you
  will need to access the individual file types within a dataset,
  which are defined as below in TAHIGH.PAS on disk 1:
  
    type
      DataSet = record
                  Data : DataFile;
                  Index : IndexFile;
                end;

  While this type is transparent to the programmer for all of the
  calls to the high-level routines, you will have to use it for such
  low-level routines as GetRec, FindKey, SearchKey, UsedRecs, FileLen,
  etc.  An example of this usage is given in the procedure below:

    procedure TASize(MyDataSet : DataSet;
                      var TotalRecords, UsedRecords : LongInt);
    begin
      TotalRecords := FileLen(MyDataSet.Data);
      UsedRecords := UsedRecs(MyDataSet.Data);
    end;

  Another example of how to access these two file types within a
  dataset is given in the RebuildDatabase procedure in HITADEMO.PAS.
  

  RECOMPILING TABUILD.PAS
  -----------------------
  On disk 1 you will find the utility TABUILD.EXE that configures the
  Turbo Access units for your database applications.  On disk 2, in
  an archived file named MISC.ARC, there are source files to the
  TABUILD utility.  While no modifications to this utility are
  necessary for Turbo Access projects, some programmers may wish
  to modify and customize TABUILD for their own unique applications.
  There are detailed instructions for recompiling TABUILD at the top
  of the TABUILD.PAS source file.


  WRITING FIELD DEFINITION FILES FOR BUILDKEY
  -------------------------------------------
  Appendix E of the DataBase Toolbox manual discusses the Reflex
  translation programs.  If you execute the BUILDKEY program as
  demonstrated in Appendix E, you may receive an error message such
  as:

    Building keys:
    Error adding key xxxxxxxxx
  
  A typical cause of this error message will be that your Reflex
  database possessed two identical fields in separate records.  If
  you had specified "NoDuplicates" inside the field definition file
  that BUILDKEY used, this error message would be the result.  To fix
  the problem, simply change the "NoDuplicates" status in your field
  definition file to "Duplicates", and execute the BUILDKEY utility
  once again.


8. FILES ON THE DISKS
---------------------

  DISK I:  TURBO SORT/TURBO ACCESS
  ----------------------------------
  README   COM  - Program to display README file
  TAINST   EXE  - Directory installation program for TABuild
  TABUILD  EXE  - Turbo Access configuration program
  TASIZES  PAS  - Utility program used by TABuild to output the
                  sizes of records and keys
  TACCESS  PAS  - Turbo Access unit source code
  TAHIGH   PAS  - Source code for the unit of high-level Turbo
                  Access routines
  SORT     PAS  - Source code for the Turbo Sort unit
  SORT     TPU  - Compiled Turbo Sort unit
  LSORT    PAS  - Source code for the Long Sort unit
  LSORT    TPU  - Compiled Long Sort unit
  TRAINER  EXE  - B+ Tree Trainer program
  TRAINER  CMD  - Data file used by Trainer to build a sample
                  B+ Tree
  README        - This file!


  DISK II: UTILITIES/SAMPLE PROGRAMS
  ------------------------------------
  TOOLS    ARC  - General purpose units used by various Turbo
                  Access programs and utilities.  Put these
                  in your standard units directory.

    MISCTOOL PAS  - Unit of some general purpose routines
    FILEUTIL PAS  - Unit of File I/O types and routines
    EDITLN   PAS  - Unit that implements a line editor

  SORTEX   ARC  - Archived Turbo Sort sample programs

    CUSTOMER DTA  - Data file used by SORTEX1.PAS & SORTEX2.PAS
    SORTEX1  EXE  - Sample sort program for one datafile
    SORTEX1  PAS  - Source to SORTEX1 program
    SORTEX2  EXE  - Sample sort program for two datafiles
    SORTEX2  PAS  - Source to SORTEX2 program
    STOCK    DTA  - Data file used by SORTEX2.PAS
    TEXTSORT EXE  - Sample sort program for any text file
    TEXTSORT PAS  - Source to TEXTSORT program

  TADEMO   ARC  - Archived Turbo Access low-level sample program

    TADEMO   EXE  - Simple low-level Turbo Access sample program
    TADEMO   PAS  - Source to TADemo program
    TADEMO   TYP  - Record and key type definition file for TADemo

  HITADEMO ARC - Archived Turbo Access high-level sample program

    HITADEMO EXE  - Simple high-level Turbo Access sample program
    HITADEMO PAS  - Source to HITADemo program
    HITADEMO TYP  - Record and key type definition file for HITADemo

  BTREE    ARC  - Archived source to Btree, a sample database program

    BTREE    EXE  - Executable Btree customer database program
    BTREE    PAS  - Source to the Btree program
    BTREE    TYP  - Record and key type definition file for Btree
    WINDOWU  PAS  - Window unit routines for Btree

  CONVERT  ARC  - Archived program and associated files that demonstrate
                  how to convert Turbo Access 1.XX files to Turbo Access
                  4.0 files

    ACCESS   BOX  - Source for Turbo Access 1.XX routines
    GETKEY   BOX  - Source for Turbo Access 1.XX routines
    CONVERT  PAS  - Turbo Access 1.0 to 4.0 file conversion program
    TEMPLATE NFO  - Template which contains typed constants that
                    customize the CONVERT program for a particular
                    database
    BTREE    NFO  - A copy of TEMPLATE.NFO customized to convert
                    BTree's sample data and index files
    CUSTTA1  DAT  - Datafile from Btree Turbo Access 1.0
    CUSTTA1  IXC  - Indexfile from Btree Turbo Access 1.0
    CUSTTA2  IXN  - Indexfile from Btree Turbo Access 1.0

  REFLEX   ARC  - Archived programs that translate between Reflex and
                  Turbo Access files

    ASSET    DAT  - Sample Turbo Access datafile
    ASSET    FD   - Field definition file for Asset
    BUILDKEY PAS  - Utility to generate index files from data files
    EXPORTR  EXE  - Utility to export Turbo Access data files to
                    Reflex
    EXPORTR  PAS  - Source code to ExportR
    FIELDDEF PAS  - Source code to unit for creating field definition
                    files
    GENTYPE  EXE  - Utility to generate type definition files
    GENTYPE  PAS  - Source code to Gentype
    IMPORTR  EXE  - Utility to import Reflex data files to Turbo
                    Access
    IMPORTR  PAS  - Source code to ImportR
    REALCONV PAS  - Source code to unit for converting 6 and 8 byte
                    real numbers
    REFDATE  PAS  - Source code to unit for converting Reflex dates
    REFLEX   PAS  - Source code to unit for converting Reflex files
    STOCK    RXD  - Sample Reflex data file

  MISC     ARC  - Source code to the TABuild and TAInst programs

    CONFIG   PAS  - Source code to unit for configuring TABuild
    PATHS    INC  - Include file used by TAInst and TABuild
    SEARCH   OBJ  - Object file used by CONFIG.PAS
    SETCONST PAS  - Source code to unit for calculating Turbo Access
                    configuration constants
    TABUILD  PAS  - Source code to TABuild configuration program
    TAEDIT   PAS  - Source code to unit for editing configuration
                    files
    TAINST   PAS  - Source code to TAInst installation program

  UNPACK   COM  - Utility to unpack .ARC files


END
---