@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