@PO 1
@MT 4
@HM 1
@HE   TBTREE16             Copyright (c)  1988,1989   Dean H. Farwell II
@MB 4
@FM 2
@PC 40













                                  TBTREE16

                         ( Turbo BTree version 1.5 )

                            Quick Reference Guide

               Copyright (c)  1988,1989    Dean H. Farwell II

@PA
This reference guide is intended to simplify use of TBTREE16.  It provides a
listing of some of the procedures, functions, data types and constants
available to the user.  It is not all inclusive but is limited to those which
are normally required by the user to use TBTREE16.  I have specifically
excluded those items which I use internally between units but are of little
value to you or those which could be used in other applications but are not
necessary to use with TBTREE.  You can still use them by referring to the
particular unit in which they reside.  However, it is imperative that you
understand what the internal routines are doing before using them.

This Quick Reference Guide was developed to simplify the learning process for
the user and to give guidance concerning which routines the user should
reasonably be involved with.

This guide is not intended to fully document the included items, especially
the procedures and functions.  The source code for the units contains much
more in-depth documentation. This guide is only meant to provide a place to
turn when a quick refresher is required.


                                  Constants
                                  ---------

FNSIZE
     - FNSIZE = 80;
     - Maximum number of characters in a file name (including drive, path,
       file name and extension)
     - FILEDECS unit

MAXDATASIZE
     - MAXDATASIZE = 65520;
     - Maximum size for a data record (logical record)
     - LOGICAL unit

MAXSTRINGLENGTH = 255;
     - MAXSTRINGLENGTH = 255;
     - Maximum characters in a string
     - STRINGS unit

MAXVALSIZE
     - MAXVALSIZE = 245;
     - Maximum size of an index entry
     - BTREE unit
@PA
                                    Types
                                    -----

BufferSizeType
     - BufferSizeType = 0 .. MAXWORD;
     - Used for number of pages in buffer
     - PAGE unit

ByteArray
     - ByteArray = Array [ByteArrayRange] of Byte;
     - Used to store 1 to 255 bytes of data.  Routines in ByteData unit treat
       it somewhat like a string in that first byte contains number of bytes
       of data.
     - BYTEDATA unit

ByteArrayRange
     - ByteArrayRange = 0 .. MAXBYTE;
     - Used as index type for the ByteArray type
     - BYTEDATA unit

DataSizeRange
     - DataSizeRange = 0 .. MAXDATASIZE;
     - Range for size of a field and a logical record
     - LOGICAL unit

FileTypes
     - FileTypes = (INDEX,DATA,VLRDATA);
     - File types created and used as part of TBTREE16 which are of interest
       to the user
     - FILEDECS unit

FnString
     - FnString  = String[FNSIZE];
     - Used for file names (including drive, full path, file name and
       extensions)
     - FILEDECS unit

IOErrorRec
     - IOErrorRec = record
           routineName : RoutineNameString;
           tBTreeIOResult : Word;
           end;
     - Used to hold information when an I/O error occurs
     - ERROR unit
@PA
LrList
     - LrList = record
           fName    : FnString;
           currPage : PrNumber;
           current  : LrNumber;
           count    : LrNumber;
           case Boolean of
               TRUE  : (lrArray  : LogicalRecordsArray);
               FALSE : (page : SinglePage);
           end;
     - Type used for logical record lists.  Never manipulate any of the
       fields directly.  Only declare a variable of this type and use
       it as a parameter for the various routines supplied
     - LRECLIST unit

LrNumber
     - LrNumber = RecordNumber;
     - Logical record number within a file
     - FILEDECS unit

OpenFileRange
     - OpenFileRange = Byte;
     - Used as type for number of files that can be open at one time
     - FILEBUFF unit

RoutineNameString
     - RoutineNameString = String[50];
     - Used as type for routine name where error occurred
     - ERROR unit

PrNumber
     - PrNumber = RecordNumber;
     - Physical record number within a file
     - FILEDECS unit

RecordNumber
     - RecordNumber = 0 .. MAXLONGINT;
     - Generic Record number (logical or physical).
     - FILEDECS unit

SortFieldList
     - SortFieldList = ^SortField;
     - Used to form a linked list containing info about sort fields
     - SORT unit

SortFieldPosition
     - SortFieldPosition = DataSizeRange;
     - Position of sort field (in bytes) within the data record
     - SORT unit

StringCondition
     - StringCondition = (ST,    (* String Starts With Substring *)
                          CO,    (* String Contains Substring *)
                          EN);   (* String Ends With Substring *)
     - Used to specify partial string match criteria
     - NUMBERS unit
@PA
StringLengthRange
     - StringLengthRange = 0 .. MAXSTRINGLENGTH;
     - Used as range for number of characters in a string
     - STRINGS unit

UserDataArray
     - UserDataArray  = Array [0 .. 255] of Byte;
     - Used to store user data in parameter records
     - FILEDECS unit

ValueType
     - ValueType = (INVALIDVALUE,
                    BYTEVALUE,
                    SHORTINTVALUE,
                    INTEGERVALUE,
                    LONGINTVALUE,
                    WORDVALUE,
                    STRINGVALUE,
                    REALVALUE,
                    SINGLEVALUE,
                    DOUBLEVALUE,
                    EXTENDEDVALUE,
                    COMPVALUE,
                    BYTEARRAY);
     - Data types supported by TBTREE16 indexes
     - NUMBERS unit

VersionString
     - VersionString = String[6];
     - Used to store version information in the parameter records for the
       different file types.
     - FILEDECS unit

VSizeType = 1 .. MAXVALSIZE;
     - Size range for index entries
     - BTREE unit

@PA
                                 Procedures
                                 ----------

AddFieldToSortList
     - procedure AddFieldToSortList(var sPtr : SortFieldList;
                                    pos : SortFieldPosition;
                                    vType : ValueType);
     - Used to add one sort field to a sort field list
     - SORT unit

AddToLrList
     - procedure AddToLrList(lrNum : LrNumber;
                             var lrLst : LrList);
     - Add a logical record number to a logical record list (not normally
       needed except internally)
     - LRECLIST unit

AppendTextFile
     - procedure AppendTextFile(fName : FnString;
                                var fId : Text);
     - Checks open file buffer to see if file is open.  If not it opens
       file and adds it to the buffer.  In either case it returns the file
       id.  It opens the file for appending.
     - FILEBUFF unit

CloseAllFiles
     - procedure CloseAllFiles;
     - Close all files which are open and in the open file buffer
     - FILEBUFF unit

CloseFile
     - procedure CloseFile(fName : FnString);
     - Close a file and delete its entry from the open files buffer
     - FILEBUFF unit

ConcatenateThreeValues
     - procedure ConcatenateThreeValues(var val1;
                                        vType1 : ValueType;
                                        var val2;
                                        vType2 : ValueType;
                                        var val3;
                                        vType3 : ValueType;
                                        var resultArray);
     - Will take three values and will create a new byte array which is a
       concatenation of the three input values.
     - BYTEDATA unit

ConcatenateTwoValues
     - procedure ConcatenateTwoValues(var val1;
                                      vType1 : ValueType;
                                      var val2;
                                      vType2 : ValueType;
                                      var resultArray);
     - Will take two values and will create a new byte array which is a
       concatenation of the two input values.
     - BYTEDATA unit
@PA
ConvertStringToByteArray
     - procedure ConvertStringToByteArray(str : String;
                                          maxLength : StringLengthRange;
                                          var resultArray);
     - Takes a string as input and creates a byte array.
     - BYTEDATA unit

CopyLrList
     - procedure CopyLrList(sourceLrLst : lrList;
                            var destLrLst : LrList);
     - Create a new logical record list which is a copy of the given list
     - LRECLIST unit

CreateDataFile
     - procedure CreateDataFile(dFName : FnString;
                                lrSize : DataSizeRange);
     - Used to create a data file
     - LOGICAL unit

CreateIndexFile
     - procedure CreateIndexFile(iFName : FnString;
                                 valSize : VSizeType;
                                 valType : ValueType);
     - Used to create an index file
     - BTREE unit

CreateLrList
     - procedure CreateLrList(var lrLst : LrList);
     - Create a logical record list
     - LRECLIST unit

DeleteDataFile
     - procedure DeleteDataFile(dFName : FnString);
     - Used to delete a data file
     - LOGICAL unit

DeleteFromLrList
     - procedure DeleteFromLrList(var lrLst : LrList);
     - Delete one entry from a logical record list
     - LRECLIST unit

DeleteIndexFile
     - procedure DeleteIndexFile(iFName : FnString);
     - Used to delete an index file
     - BTREE unit

DeleteDataRecord
     - procedure DeleteDataRecord(dFName : FnString;
                                  lrNum : LrNumber);
     - Delete the given logical record from the DATA file
     - LOGICAL unit

DeleteValueFromBTree
     - procedure DeleteValueFromBTree(iFName : FnString;
                                      lrNum : LrNumber;
                                      var paramValue);
     - Delete a value and associated logical record number from index
     - BTREE unit
@PA
DestroyLrList
     - procedure DestroyLrList(var lrLst : LrList);
     - Destroys a logical record list and performs necessary cleanup
     - LRECLIST unit

DestroySortList
     - procedure DestroySortList(var sPtr : SortFieldList);
     - Deletes all entries from a sort field list returning the heap
       space
     - SORT unit

Difference
     - procedure Difference(lrLst1 : LrList;
                            lrLst2 : LrList;
                            var lrLst3 : LrList);
     - Creates list containing logical record numbers in list one
       but not in list two
     - SETOPS unit

FastMover
     - procedure FastMover(var source;
                           var dest;
                           numToMove : word);
     - Replaces the Turbo Pascal Move routine
     - FASTMOVE unit

FetchFileVersion
     - procedure FetchFileVersion(fName : FnString;
                                  var verString : VersionString);
     - Returns the version of TBTREE used to create the file
     - FILES unit

FetchUserDataArray
     - procedure FetchUserDataArray(fName : FnString;
                                    var userData : UserDataArray);
     - Fetch and return user data array from the given INDEX or DATA file
     - FILES unit

FindLrNumInBTree
     - procedure FindLrNumInBTree(iFName : FnString;
                                  lrNum : LrNumber;
                                  var paramValue;
                                  var found : Boolean);
     - Find logical record number in index and return associated entry if
       found
     - BTREE unit

GetALogicalRecord
     - procedure GetALogicalRecord(fName : FnString;
                                   lrNum : LrNumber;
                                   var destination);
     - Get the specified logical record and place it in destination
     - LOGICAL unit
@PA
GetRangeFromBTree
     - procedure GetRangeFromBTree(iFName : FnString;
                                   var paramValue1;
                                   cond1 : Condition;
                                   var paramValue2;
                                   cond2 : Condition;
                                   var lrLst : LrList);
     - Create a list which contains all logical record numbers with
       values which meet both conditions (fall within the given range)
     - BTREE unit

GetSubstringAtPositionFromBTree
     - procedure GetSubstringFromBTree(iFName : FnString;
                                       var paramValue;
                                       position : StringLengthRange;
                                       var lrLst : LrList);
     - Create a list which contains all logical record numbers with
       values which meet the given string condition by having a partial string
       match at the exact location within the target string
     - BTREE unit

GetSubstringFromBTree
     - procedure GetSubstringFromBTree(iFName : FnString;
                                       var paramValue;
                                       cond : StringCondition;
                                       var lrLst : LrList);
     - Create a list which contains all logical record numbers with
       values which meet the given string condition
     - BTREE unit

GetValidLogicalRecords
     - procedure GetValidLogicalRecords(fName : FnString;
                                        var lrLst : LrList);
     - Returns a list of all logical records for a given file.  Allows
       retrievals without use of an index.
     - LOGICAL unit

GetValuesFromBTree
     - procedure GetValuesFromBTree(iFName : FnString;
                                    var paramValue;
                                    cond : Condition;
                                    var lrLst : LrList);
     - Create list which contains all logical record numbers which
       meet the given condition.
     - BTREE unit

InsertValueInBTree
     - procedure InsertValueInBTree(iFName : FnString;
                                    lrNum : LRNumber;
                                    var paramValue);
     - Insert a value and associated logical record number in an index
     - BTREE unit
@PA
Intersection
     - procedure Intersection(lrLst1 : LrList;
                              lrLst2 : LrList;
                              var lrLst3 : LrList);
     - Creates list containing logical record numbers in both lists
     - SETOPS unit

OpenTextFile
     - procedure OpenTextFile(fName : FnString;
                              var fId : Text);
     - Checks open file buffer to see if file is open.  If not it
       opens file and adds it to the buffer.  In either case it returns
       the file id
     - FILEBUFF unit

OpenUntypedFile
     - procedure OpenUntypedFile(fName : FnString;
                                 var fId : File;
                                 recSize : Word);
     - Checks open file buffer to see if file is open.  If not it
       opens file and adds it to the buffer.  In either case it returns
       the file id
     - FILEBUFF unit

PrintBufferStats
     - procedure PrintBufferStats;
     - Prints buffer usage statistics to the printer
     - PAGE unit

PrintPageBuffer
     - procedure PrintPageBuffer;
     - Prints entire page buffer to printer
     - PAGE unit

ReleaseAllPages
     - procedure ReleaseAllPages(fName : FnString);
     - Releases all pages for a given file.  Frees up buffer space.
       Does not write them to disk automatically.  VERY DANGEROUS.  Do
       not use unless you fully understand what the routine does!
     - PAGE unit

ReleasePage
     - procedure ReleasePage(fName : FnString;
                             prNum : PrNumber);
     - Releases given page for a given file.  Frees up buffer space.
       Does not write it to disk automatically.  VERY DANGEROUS.  Do
       not use unless you fully understand what the routine does!
     - PAGE unit

RewriteTextFile
     - procedure RewriteTextFile(fName : FnString;
                                 var fId : Text);
     - Rewrites a text file and returns the file id.  Adds file to
       files open buffer
     - FILEBUFF unit
@PA
RewriteUntypedFile
     - procedure RewriteUntypedFile(fName : FnString;
                                    var fId: File;
                                    recSize : Word);
     - Rewrites an untyped file and returns the file id.  Adds file to
       files open buffer
     - FILEBUFF unit

SaveUserDataArray
     - procedure SaveUserDataArray(fName : FnString;
                                   userData : UserDataArray);
     - This routine will store the user data array into the given DATA or
       INDEX file.
     - FILES unit

SetImmediateDiskWrite
     - procedure SetImmediateDiskWrite(x : Boolean);
     - Used to set whether dirty pages are immediately written to
       disk.  Setting this to TRUE will degrade performance.
     - PAGE unit

SetMaxBufferPages
     - procedure SetMaxBufferPages(n : BufferSizeType);
     - Used to set the maximum buffer pages to use.  Can be done dynamically
       (at any time) even if more pages than the new maximum are in use
     - PAGE unit

SetMaxOpenFiles
     - procedure SetMaxOpenFiles(n : OpenFileRange);
     - Sets maximum number of files to be open at one time (open in
       the open file buffer)
     - FILEBUFF unit

SortList
     - procedure SortList(var lrLst : LrList;
                          fName : FnString;
                          sPtr : SortFieldList;
                          var success : Boolean);
     - Sorts a logical record list in ascending order using the sort field
       list
     - SORT unit

StoreALogicalRecord
     - procedure StoreALogicalRecord(fName : FnString;
                                     lrNum : LrNumber;
                                     var source);
     - Stores a logical record in the given data file.  Used when the
       associated logical record number is known
     - LOGICAL unit

Union
     - procedure Union(lrLst1 : LrList;
                       lrLst2 : LrList;
                       var lrLst3 : LrList);
     - Creates list containing logical record numbers in either list
     - SETOPS unit
@PA
UserIOError
     - procedure UserIOError(ioErrRec : IOErrorRec);
     - Called when I/O error occurs with TBTREE16 routines
     - ERROR unit

UsingCursorMakeCursorInvalid
     - procedure UsingCursorMakeCursorInvalid(iFName : FnString);
     - Makes cursor invalid.  Never required.  Only alleviates overhead of
       keeping track of cursor when inserts and deletes are performed on the
       index.  Will slightly speed up the inserts and deletes.
     - BTREE unit

VLRCreateDataFile
     - procedure VLRCreateDataFile(dFName : FnString);
     - creates a variable length record data file
     - VLOGICAL unit

VLRDeleteDataFile
     - procedure VLRDeleteDataFile(dFName : FnString);
     - Deletes a variable length record data file.
     - VLOGICAL unit

VLRDeleteDataRecord
     - procedure VLRDeleteDataRecord(dFName : FnString;
                                     lrNum : lrNumber);
     - Delete the given logical record from the VRLDATA file
     - VLOGICAL unit

VLRGetALogicalRecord
     - procedure VLRGetALogicalRecord(dFName : FnString;
                                      lrNum : LrNumber;
                                      var destination);
     - Get the specified logical record and place it in destination
     - VLOGICAL unit

VLRGetValidLogicalRecords
     - procedure VLRGetValidLogicalRecords(dFName : FnString;
                                           var lrLst : LrList);
     - Returns a list of all logical records for a given variable length
       record data file.  Allows retrievals without use of an index.
     - VLOGICAL unit

VLRStoreALogicalRecord
     - procedure VLRStoreALogicalRecord(dFName : FnString;
                                        lrNum : LrNumber;
                                        var source;
                                        size : DataSizeRange);
     - Stores a logical record in the given variable length record data file.
       Used when the associated logical record number is known
     - VLOGICAL unit
@PA
WriteBufferToDisk
     - procedure WriteBufferToDisk(fName : FnString);
     - Writes all dirty buffer pages for a particular file to the
       disk.
     - PAGE unit

WriteEntireBufferToDisk
     - procedure WriteEntireBufferToDisk;
     - Writes all dirty buffer pages to the disk.  Do this prior to
       terminating program
     - PAGE unit
@PA
                                  Functions
                                  ---------

CheckImmediateDiskWrite
     - function CheckImmediateDiskWrite : Boolean;
     - Returns true if pages will be immediately written to disk.
       Allows you to check it at any time.
     - PAGE unit

CheckMaxBufferPages
     - function CheckMaxBufferPages : BufferSizeType;
     - Returns maximum buffer pages allowed
     - PAGE unit

CheckPagesInUse
     - function CheckPagesInUse : BufferSizeType;
     - Returns number of pages currently in use
     - PAGE unit

DataRecordUsed
     - function DataRecordUsed(dFName : FnString;
                               lrNum : LrNumber) : Boolean;
     - Checks the existence of a data record for the given data file
     - LOGICAL unit

FileExists
     - function FileExists(fName : FnString) : Boolean;
     - Checks the existence of any file
     - FILES unit

FindLargestLr
     - function FindLargestLr(lrLst : LrList) : LrNumber;
     - returns the largest logical record in a list.  Probably not
       useful except internally
     - LRECLIST unit

FindLrInList
     - function FindLrInList(lr : LrNumber;
                             lrLst : LrList) : Boolean;
     - Returns true if the given logical record resides in the logical
       record list
     - LRECLIST unit

GetCountLr
     - function GetCountLr(lrLst : LrList) : LrNumber;
     - Returns the number of entries in the logical record list
     - LRECLIST unit

GetCurrLr
     - function GetCurrLr(lrLst : LrList) : LrNumber;
     - Returns the logical record number corresponding to the current
       cursor position.  The cursor position is not changed.
     - LRECLIST unit
@PA
GetDataRecordSize
     - function GetDataRecordSize(dFName : FnString) : DataSizeRange;
     - LOGICAL unit

GetFirstLr
     - function GetFirstLr(var lrLst : LrList) : LrNumber;
     - Set cursor to front of list and return the first logical record
       number in the list
     - LRECLIST unit

GetLastLr
     - function GetLastLr(var lrLst : LrList) : LrNumber;
     - Set cursor to end of list and return the last logical record
       number in the list
     - LRECLIST unit

GetNextLr
     - function GetNextLr(var lrLst : LrList) : LrNumber;
     - Moves the cursor forward and returns the corresponding logical
       record number
     - LRECLIST unit

GetNumberOpenFiles
     - function GetNumberOpenFiles : OpenFileRange;
     - Returns the number of files which are presently open
     - FILEBUFF unit

GetPrevLr
     - function GetPrevLr(var lrLst : LrList) : LrNumber;
     - Moves the cursor backward and returns the corresponding logical
       record number
     - LRECLIST unit

LastDataRecord
     - function LastDataRecord(dFName : FnString) : LrNumber;
     - Returns the logical record of the last valid data record in the given
       data file
     - LOGICAL unit

NumberOfBTreeLevels
     - function NumberOfBTreeLevels(iFName : FnString) : Byte;
     - Return the number of levels for the given index
     - BTREE unit

StoreNewLogicalRecord
     - function StoreNewLogicalRecord(fName : FnString;
                                       var source) : LrNumber;
     - Stores a new logical record in a data file.  Used when the
       logical record number is not known since this routine returns
       the logical record number after the store takes place.  You
       would not use this for an update.
     - LOGICAL unit
@PA
UsingCursorAndGEValueGetLr
     - function UsingCursorAndGEValueGetLr(iFName : FnString;
                                           var paramValue) : LrNumber;
     - Sets internal cursor to location in the index where the first value
       greater than or equal to paramValue is found.  Returns 0 if there is no
       such entry
     - BTREE unit

UsingCursorAndValueGetLr
     - function UsingCursorAndValueGetLr(iFName : FnString;
                                         var paramValue) : LrNumber;
     - Sets internal cursor to location in the index matching paramValue and
       returns the corresponding logical record number.  Returns 0 if there
       is no entry matching paramValue.
     - BTREE unit

UsingCursorGetCurrLr
     - function UsingCursorGetCurrLr(iFName : FnString) : LrNumber;
     - Does not move the internal cursor.  Only returns the logical record
       number corresponding to the current cursor position.  Returns 0 if the
       cursor is not valid.
     - BTREE unit

UsingCursorGetFirstLr
     - function UsingCursorGetFirstLr(iFName : FnString) : LrNumber;
     - Sets internal cursor to front of the index and returns the first
       logical record number.  Returns 0 if there are no entries in the index.
     - BTREE unit

UsingCursorGetLastLr
     - function UsingCursorGetLastLr(iFName : FnString) : LrNumber;
     - Sets internal cursor to end of the index and returns the last logical
       record number.  Returns 0 if there are no entries in the index.
     - BTREE unit

UsingCursorGetNextLr
     - function UsingCursorGetNextLr(iFName : FnString) : LrNumber;
     - Moves the internal cursor to the next entry and returns the
       corresponding logical record number.  Returns 0 if the cursor was not
       valid or if there is no next entry (you have moved past the end of
       index.
     - BTREE unit

UsingCursorGetPrevLr
     - function UsingCursorGetPrevLr(iFName : FnString) : LrNumber;
     - Moves the internal cursor to the previous entry and returns the
       corresponding logical record number.  Returns 0 if the cursor was not
       valid or if there is no previous entry (you have moved past beginning
       of index.
     - BTREE unit
@PA
UsingCursorSkipAndGetNextLr
     - function UsingCursorSkipAndGetNextLr(iFName : FnString) : LrNumber;
     - Moves the internal cursor to the next entry not equal to the current
       entry and returns the corresponding logical record number.  In other
       words, it will skip the cursor over all nonmatching values.  Returns 0
       if the cursor was not valid or if there is no next nonequal entry (you
       have moved past the end of index).
     - BTREE unit

UsingCursorSkipAndGetPrevLr
     - function UsingCursorSkipAndGetPrevLr(iFName : FnString) : LrNumber;
     - Moves the internal cursor to the previous entry not equal to the
       current entry and returns the corresponding logical record number.  In
       other words, it will skip the cursor over all nonmatching values.
       Returns 0 if the cursor was not valid or if there is no previous
       nonequal entry (you have moved past the beginning of index).
     - BTREE unit

VLRDataRecordUsed
     - function VLRDataRecordUsed(dFName : FnString;
                                  lrNum : LrNumber) : Boolean;
     - Checks the existence of a data record for the given variable length
       record data file
     - VLOGICAL unit

VLRGetDataRecordSize
     - function VLRGetDataRecordSize(dFName : FnString;
                                     lrNum : LrNumber) : DataSizeRange;
     - Returns the data record size for the given variable length record data
       file.  Used mostly internally
     - VLOGICAL unit

VLRLastDataRecord
     - function VLRLastDataRecord(dFName : FnString) : LrNumber;
     - Returns the logical record of the last valid data record in the given
       variable length record data file
     - VLOGICAL unit

VLRStoreNewLogicalRecord
     - function VLRStoreNewLogicalRecord(dFName : FnString;
                                         var source;
                                         size : DataSizeRange) : LrNumber;
     - Stores a new logical record in a variable length record data file.
       Used when the logical record number is not known since this routine
       returns the logical record number after the store takes place.  You
       would not use this for an update.
     - VLOGICAL unit
