Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / BTV115.ZIP / BTV.TXT < prev next >

Wrap

Text File | 1992-06-02 | 60.8 KB | 1,500 lines

BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── INTRODUCTION BTV.PAS is a fully object oriented Turbo Pascal 6.0 programming interface for Novell's Btrieve database manager. Through OOP techniques BTV.PAS greatly simplifies interface to Btrieve for Turbo Pascal. Included in this package are full working examples that demonstrate the ease and power of the BTV interface. Also included is a complete application for recovering damaged files. Just a few of the features are : * Over 40 functions for Btrieve including : * Create, easy file definition and creation * Clone, create an empty copy of a file * Recover, recover records from a damaged file * Save, save all records to a DOS file compatible with BUTIL * Load, read records from a file created by Save or BUTIL * Create Supplemental Indexes * Supports multiple and segmented keys * Supports alternate collating sequences * Supports variable length records * Automatic padding and justification of string keys * Supports full transaction processing * Supports full network record and file locking * Automatic integrated error handling In writing this documentation I have assumed the reader is knowledgeable about the workings of Btrieve and the basics object oriented programming in Turbo Pascal 6.0. This document is not meant to explain or serve as a tutorial on either of these subjects. I think you will find the source code itself fairly well documented. I strongly recommend that you look it over. If you have any questions, suggestions for improvement, or problems, please do not hesitate to contact me. If you need a version for Turbo 5.5 please let me know. Richard Hansen PO Box 18571 Saint Paul, MN 55118-0571 USA CompuServe ID 70242,3367 BTV.PAS Copyright (C) 1992 Richard W. Hansen, all rights reserved. Btrieve Copyright (C) Novell, Inc. BUTIL Copyright (C) Novell, Inc. DEFINITION OF SHAREWARE Shareware distribution gives users a chance to try software before buying it. If you try a Shareware program and continue using it, you are expected to register. Individual programs differ on details -- some request registration while others require it, some specify a maximum trial period. With registration, you get anything from the simple right to continue using the software to an updated program with printed manual. 1 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── Copyright laws apply to both Shareware and commercial software, and the copyright holder retains all rights, with a few specific exceptions as stated below. Shareware authors are accomplished programmers, just like commercial authors, and the programs are of comparable quality. (In both cases, there are good programs and bad ones!) The main difference is in the method of distribution. The author specifically grants the right to copy and distribute the software, either to all and sundry or to a specific group. For example, some authors require written permission before a commercial disk vendor may copy their Shareware. Shareware is a distribution method, not a type of software. You should find software that suits your needs and pocketbook, whether it's commercial or Shareware. The Shareware system makes fitting your needs easier, because you can try before you buy. And because the overhead is low, prices are low also. Shareware has the ultimate money-back guarantee -- if you don't use the product, you don't pay for it. DISCLAIMER - AGREEMENT Users of BTV.PAS must accept this disclaimer of warranty: "BTV.PAS is supplied as is. The author disclaims all warranties, expressed or implied, including, without limitation, the warranties of merchantability and of fitness for any purpose. The author assumes no liability for damages, direct or consequential, which may result from the use of BTV.PAS." BTV.PAS is "shareware" and is provided at no charge to the user for evaluation. Feel free to share it with your friends, but do not give it away altered or as part of any other source code package. If you find this source code useful and continue to use BTV.PAS after a reasonable trial period, you must register it. The registration fee will license one copy for use on any one computer at any one time. You must treat this software just like a book. An example is that this software may be used by any number of people and may be freely moved from one computer location to another, so long as there is no possibility of it being used at one location while it's being used at another. Just as a book cannot be read by two different persons at the same time. Commercial users of BTV.PAS must register and pay for their copies of BTV.PAS within 30 days of first use or their license is withdrawn. You may use BTV.PAS in your software projects, but you may only distribute it in executable form. No royalties are required for programs you develop using licensed copies of BTV.PAS. Anyone distributing BTV.PAS for any kind of remuneration must first contact Richard Hansen for authorization. This authorization will be automatically granted to distributors recognized by the ASP as adhering to its guidelines for shareware distributors, and such distributors may begin offering BTV.PAS immediately (However Richard Hansen must still be advised so that the distributor can be kept up-to-date with the latest version of BTV.PAS.). REGISTRATION Many new features are planned, so registration is a good idea, just to make sure you have the latest and greatest version. Individual registrations are 2 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── $20.00 (U.S), commercial and corporate registrations are $50.00 (U.S.). All non U.S. registrations please add $10.00. All registered users will receive a copy of the latest version and printed documentation. Send all registrations to : Richard Hansen PO Box 18571 Saint Paul, MN 55118-0571 USA OVERVIEW There are three objects that make up the BTV OOP interface to Btrieve. The most important of these is the BtrieveFile object. BtrieveFile contains all the routines for opening and creating files, reading, writing and deleting records, etc. It contains a pointer to the data buffer that can be automatically allocated and deallocated by the object if you desire. Next, is the ErrorHandler object, this object controls error handling for the file. Any Btrieve error may be turned on or off for trapping by the error handler object. This frees you from the need to check for errors after each operation, but still allows for full error checking. Each file object has a pointer to an error handler, this error handler can be the same or different for each file you open. If an error is turned on the error handler will call an error display routine, and based on a return code from it, will continue, abort, or retry an operation. Last, there is the DisplayObject. This object handles the display of any errors encountered. It is called by the error handler, and returns an action code, possibly based on some user response, to the error handler. This action code will cause the error handler to either abort the program, retry the operation, or continue processing. DECLARATIONS const bOpen = 0; ... bGetKey = 50; These constants define all the available btrieve operations. bOkay = 0; ... bLastError = bOutOfMemory; These define all the status codes returned by Btrieve. In addition there are constants for file open modes, locking, key types, file flags, etc. MaxSegments = 24; Defines the maximum total number of key segments allowed for file. If none of your files will ever have this many segments then redefine it to some smaller size and save a few bytes of memory. 3 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── MaxBuffSize : Word = 16 * 1024; This initialized variable defines the maximum size that will be automatically allocated for a file data buffer. There is no need to redefine this if you are using fixed length records, since only as much memory as needed will actually be allocated. If you are using variable length records and are sure they will be smaller than 16K bytes, then you can redefine this as needed before opening the file. {.$DEFINE BCHECK} If this compiler directive is defined a check for Btrieve will be made during initialization. If it is not present the program will be halted. {.$DEFINE BTRIEVE50} Define this to make all opcodes new to Btrieve version 5.0 available. type PProgress = ^TProgress; TProgress = Object Constructor Init; Procedure Display(Count : LongInt); Virtual; end; Defines an object with a method to display the progress of Recover, Load and Save operations. Count is the current record count, the display routine will be called every ten records. AllErrors = bInvalidOp..bLastError; ErrorSet = Set of AllErrors; These two define a set of all possible Btrieve errors. ErrorAction = (erAbort, erDone, erRetry); Enumerates the possible responses to a Btrieve error. One of these three actions must be returned by your error display routine. If erAbort is returned the program will be halted, if erDone is returned the program will continue, if erRetry is returned the Btrieve operation that generated the error will be executed again. PErrorDisplay = ^ErrorDisplay; ErrorDisplay = Object Constructor Init; Function Display(Error : Integer; ErrorMsg : String; OpCode : Byte; OpCodeMsg : String; FileName : PathStr ): ErrorAction; Virtual; Destructor Done; Virtual; end; ErrorDisplay is the object that will display errors to the user. This is an ABSTRACT object and can never be used as is, you must define a descendant 4 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── object that does what you want in each program. The error handler will pass an error number, error description, operation, operation description, and the full file path to your object. Your object should display the error and return an action code. This action code can be based on user input, the type of error, operation or whatever. PErrorHandler = ^ErrorHandler; ErrorHandler = Object RetryCount : Word; MaxRetry : Word; RetryDelay : Word; TrappedErrors : ErrorSet; ErrorDisplay : PErrorDisplay; Constructor Init(DisplayObject : PErrorDisplay); Function ErrorDispacther(ErrorCode : Integer; OpCode : Byte; FileName : PathStr ): ErrorAction; Virtual; Function Error(Status : Integer; OpCode : Byte; FileName : PathStr ): Boolean; Virtual; Procedure SetMaxRetry(Retry : Word); Function GetMaxRetry: Word; Procedure SetDelay(Seconds : Word); Function GetDelay: Word; Procedure AddErrors(ErrorCodes : ErrorSet); Procedure RemoveErrors(ErrorCodes : ErrorSet); Procedure SetErrors(ErrorCodes : ErrorSet); Procedure GetErrors(var ErrorCodes : ErrorSet); Procedure ClearRetry; Function ErrorMsg(ErrorCode : Integer): String; Virtual; Function OpMsg(OpCode : Integer): String; Virtual; Destructor Done; Virtual; end; This is the error handler object used to trap Btrieve errors. It can be used as defined. Each possible error can be set so it is trapped or not by this error handler. By default all errors except end of file are trapped. All trapped errors will be routed through the error display object assigned to the handler when it is initialized. Untrapped errors must be handled directly in your program code. Locking errors (record in use, file in use) are a special case. These errors, which happen only on networked systems, automatically generate retries. No error will be generated until the maximum number of retries, set by you, have been attempted. This feature can save some programming work on your part if you are writing an application that uses the networked version of Btrieve. If this all sounds complicated, don't worry, it really isn't that bad. Please take a look at the example code to see how easy it is to setup the error handling. My feelings on error checking are that the more automatic it is the better. In BTV.PAS little work up front leads to considerably less coding later. You only need to do this stuff once, no matter how many files you open. Once you get the error handling setup, you can pretty much forget about 5 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── it in the rest of your program. In fact, it gets even easier if you create a standard error handling Unit and reuse in all your programs. PBtrieveFile = ^BtrieveFile; BtrieveFile = Object Path : PathStr; AltPath : PathStr; Data : Pointer; DataSize : Integer; Allocate : Boolean; BytesRead : Word; BytesToWrite: Word; Key : Pointer; KeySize : Byte; SegmentCnt : Byte; CurIndex : Word; IndexCnt : Byte; Status : Integer; FileOpen : Boolean; ErrHandler : PErrorHandler; KeyList : KeyDefArray; KeyStart : Array[0..MaxSegments - 1] of Byte; PosBlock : Array[1..PosBlockSize] of Byte; VariableLen : Boolean; SISegments : Byte; ReadKeyDefs : Boolean; CurrentKeySize : Byte; Constructor Init(FilePath : PathStr; ErrorObject : PErrorHandler; DataBuf : Pointer; DataBufSize : Word); Destructor Done; Virtual; Procedure AddAltSequence(AltSeqPath : PathStr); Procedure AddKeySegment(Position : Word; Size : Word; Flags : Word; KeyType : Byte; NullValue : Byte; Justify : Byte); Procedure Open(Mode : Integer; Owner: String); Procedure Close; Procedure Create(Flags : Word; RecordSize : Word; PageSize : Word; Pages : Word; Mode : Integer); Procedure Clone(NewFilePath : PathStr; Mode : Integer); Function Error(ErrStatus : Integer; OpCode : Byte; FileName : PathStr ): Boolean; Function Recover(NewFilePath : PathStr; DisplayObj : PProgress): Integer; 6 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── Function Save(NewFilePath : PathStr; DisplayObj : PProgress): Integer; Function Load(InputFilePath : PathStr; DisplayObj : PProgress): Integer; Procedure AddSupplKeySegment(Position : Word; Size : Word; Flags : Word; KeyType : Byte; NullValue : Byte; Justify : Byte); Procedure CreateIndex; Procedure DropIndex(Index : Integer); Procedure SetOwner(Owner : String; Mode : Integer); Procedure ClearOwner; Procedure SetKeyPath(Number : Word); Procedure MakeKey(V1 : Pointer; V2 : Pointer; V3 : Pointer; V4 : Pointer; V5 : Pointer; V6 : Pointer); Procedure Get(Op : Word; Lock : Word); Procedure GetDirect(Lock : Word; Position : LongInt); Function GetPosition: LongInt; Procedure UnlockAll(Lock : Word); Procedure Insert; Procedure Update; Procedure SetOutputSize(Size : Word); Procedure AddErrors(ErrorCodes : ErrorSet); Procedure RemoveErrors(ErrorCodes : ErrorSet); Procedure SetErrors(ErrorCodes : ErrorSet); Procedure GetErrors(var ErrorCodes : ErrorSet); Procedure Delete; Procedure ClearBuffer; Procedure ClearKey; Procedure FillKeyBuffer(var KeyBuf; Size : Word); Procedure ChangeBufferSize(Size : Word); Procedure Stat(var FData : FileSpec); Function bResult: Integer; Function IsOpen: Boolean; Function NumberOfRecords: LongInt; Procedure StartTransaction(Lock : Word); Procedure EndTransaction; Procedure AbortTransaction; Procedure Unload; Procedure Reset; Procedure Version(var Ver : Word; var Rev : Word; var OSFlag : Char); Procedure FixKeyStrings; end; The BtrieveFile object is the heart of BTV.PAS. It contains all the routines 7 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── for manipulating Btrieve files. It is a fairly complex object; but, it greatly simplifies your interaction with Btrieve files. You will create one of these objects for each file you want to access in a program. To open a file, you execute two object methods. First, you init the object passing a file path, an error handler (can be nil), and a pointer to a data buffer and the data buffer size. Any number of files can share a single error handler. If you pass a nil pointer for the data buffer, a buffer will be allocated for you. Next, you call Open with an open mode (Read Only, Exclusive, or Accelerated ) and file owner name. Creating a file is almost as easy. Init is called the same as for Open. Next, for each key segment needed, you execute the AddKeySegment method passing the key position, size, key type, etc. This will define each key segment you need for the file. After all keys are defined make a call to Create. This method takes the file flags, record size, page size, etc. as parameters and Creates a new file. Create does not open the file, so finish off with a call to the Open method. Reading and writing records is just as simple. For a read by key you must first make a call to MakeKey, to build the key buffer. Then call Get, supplying the opcode for the type of read you want and the locking state. The data will be passed back in the file buffer setup on initialization. For the step operation you just call Get passing the correct opcode. To write a new record, fill the buffer you setup and execute the Insert method. To change a record, first read it with a call to Get. Make any changes to the buffer and call Update. Procedure CheckForBtrieve; This procedure can be called to check for the presence of Btrieve. It halts the program if Btrieve is not loaded. This is the same routine called during program initialization, if that feature is enabled. OBJECT DECLARATIONS - BtrieveFile FIELDS - Allocate : Allocate : Boolean; This field is set by Init and used by Open and Done. If the data buffer pointer passed to Init is nil, Allocate is set to TRUE and file buffer memory will automatically be allocated and deallocated. AltPath : AltPath : PathStr; Holds the name and path of an alternate collating sequence for the file. BytesRead : BytesRead : Integer; Is the number of bytes input from the file on the last read operation. BytesToWrite : BytesToWrite: Integer; Holds the number of bytes in the buffer that will be output to the file on the next write operation. For fixed length records it defaults to the size of the file record and should not be changed. For variable length 8 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── records it should be set before each record is written. CurIndex : CurIndex : Word; CurIndex is the current Key number (access path) used for the reads and writes. CurrentKeySize : CurrentKeySize : Byte; Used to find the largest key. Data : Data : Pointer; Points to the file buffer. DataSize : DataSize : Integer; DataSize is the size of the file buffer pointed to by Data. ErrHandler : ErrHandler : PErrorHandler; A pointer to the ErrorHandler object that will control all error checking. If ErrHandler is nil no error checking is done. FileOpen : FileOpen : Boolean; Will be set to TRUE if the file is opened successfully. IndexCount : IndexCnt : Byte; Number of keys in the file. Key : Key : Pointer; Points to the file key buffer. KeyList : KeyList : KeyDefArray; Holds a definition record for each key segment in the file. KeySize : KeySize : Byte; Size of the key buffer pointed to by KeySize. KeyStart : KeyStart : Array[0..MaxSegments - 1] of Byte; Holds a list of the offsets of the first segment of each key. Path : Path : PathStr; Path contains the name and path of the file. PosBlock : PosBlock : Array[1..PosBlockSize] of Byte; The Btrieve position block. ReadKeyDefs : ReadKeyDefs : Boolean; Indicates whether the key definitions have been setup manually or should be read from the file. SegmentCnt : SegmentCnt : Byte; The total number of segments in all keys. Status : Status : Integer; The status of the last Btrieve operation. VariableLen : VariableLen : Boolean; Set to TRUE if the file holds variable length records. 9 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── SISegments : SISegments : Byte; Used in setting up a supplemental index. METHODS - Init : Constructor Init( FilePath : PathStr; var ErrorObject : PErrorHandler; DataBuf : Pointer; DataBufSize : Word); Initializes the file name and path, sets the pointer to the error handler object. If ErrorObject is nil no error checking is done, it is all up to the programmer in this case. If DataBuf is not nil then Allocate will be set to TRUE and memory for the file buffer will be allocated and deallocated automatically. If DataBuf is not nil then DataBufSize must be the size of the buffer pointed to by DataBuf. If DataBuf is nil then the value of DataBufSize is ignored. See Open, Create, Done, ErrorHandler object. Done : Destructor Done; Virtual; Disposes of key buffer memory. If Allocate is TRUE, also disposes of the file buffer memory. See Init. AbortTransaction : Procedure AbortTransaction; Aborts the current Btrieve transaction. See EndTransaction, StartTransaction. AddAltSequence : Procedure AddAltSequence(AltSeqPath : PathStr); Defines an alternate collating sequence file that will be loaded and passed to Btrieve on a Create. This method only needs to be called before Create and if an alternate collating sequence is desired. See Create. AddErrors : Procedure AddErrors(ErrorCodes : ErrorSet); Call AddErrors to add a set of error codes to those handled by the file's error handler. Use it in conjunction with RemoveErrors to turn an error on and off for automatic trapping. AddErrors just makes a call to the error handler AddErrors method, so it is here mostly for convenience. You could just as well add errors by dereferencing the ErrHandler pointer. But this is one of the most often made calls to the error handler. See RemoveErrors, ErrHandler, GetErrors, SetErrors, TErrorHandler. AddKeySegment : Procedure AddKeySegment(Position : Word; Size : Word; Flags : Word; KeyType : Byte; NullValue : Byte; Justify : Byte); AddKeySegment is used to manually define keys for the file. When creating a file the keys must be setup by calls to AddKeySegment. Keys do not have 10 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── to be defined before opening a file. On an Open if no calls to AddKeySegment have been made, then the key information will be read from the file itself. Except for Justify, the parameters are the same as defined by Btrieve. Position is the position of the segment in the file. It is the same as Btrieve expects, remember they start at one not zero. Size is the number of bytes in the key segment you are defining. Flags are the usual flags such as modifiable, duplicate, etc. KeyType can be any valid type understood by Btrieve. NullValue will normally be set to zero. Please check your Btrieve manual for more information on defining keys. Justify is a special parameter that makes the use of left and right justified key strings simpler. All pascal type strings (Btrieve's lstrings) can be automatically padded to the left or right with spaces to their defined sizes. If Justify is set to bLJustify a string will be padded to it's full length with spaces. If Justify is bRJustify then a string key will be left padded to its defined size with spaces. Set Justify to bNormal to leave your key strings as passed. While this padding is not absolutely necessary, it does make strings easier to use. Since the same padding is done to the keys used to read from or write to the file, you will never need to worry about trailing or leading spaces on your string keys. To define the keys for a file, just make repeated calls to AddKeySegment. Make one call for each segment needed. You must make these calls in order, just as if you were building the key data buffer directly. Add the segments that make up key one first, then the segments for key two, then the segments for key three, etc. The segments for each key must also be added in order, segment one, segment two, etc. The data will be stored in KeyList and passed to Btrieve on a Create. A typical call would look like : F.AddKeySegment(1,10, bModifiable + bExtended, bLstring, 0, False); This key starts at position 1 in the file, is modifiable, is a lstring and is the last segment in its key path, it has a null value of zero, and is not right justified. See the bXXXXX constants, Create. AddSupplKeySegment: Procedure AddSupplKeySegment(Position : Word; Size : Word; Flags : Word; KeyType : Byte; NullValue : Byte; Justify : Byte); This functions the same as AddKeySegment but is used to define a supplemental index. You can only define one key at a time. See the bXXXXX constants, CreateIndex, AddKeySegment. bResult : Function bResult: Integer; This function returns the last error status from Btrieve. Unlike the 11 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── Turbo Pascal IoResult function; a call to bResult does not reset the status, so multiple calls can be made to this function. ChangeBufferSize : Procedure ChangeBufferSize(Size : Word); This method should only be used for files with variable length records where the file buffer is allocated by the object. Use it in that rare instance when you need to change the size of the file buffer. See Data, Init. ClearBuffer : Procedure ClearBuffer; Clears the file data buffer, the memory pointed to by the Data field. ClearKey : Procedure ClearKey; Clears the file key buffer, the memory pointed to by the Key field. ClearOwner : Procedure ClearOwner; If an owner has been assigned to a file, this method will clear it. The file must be opened before invoking this method. See SetOwner. Clone : Procedure Clone(NewFilePath : PathStr; Mode : Integer); Clone will create an empty copy of the file on the specified file path. Mode indicates whether the file should be over written if it already exists. See the bXXXXX constants. Close : Procedure Close; Closes an open file. See Done. Create : Procedure Create(Flags : Word; RecordSize : Word; PageSize : Word; Pages : Word; Mode : Integer); Create a new file. Flags are the normal Btrieve file flags such as truncate, variable length, or key only. RecordSize is the file record size, or the fixed length portion size for variable length records. PageSize is the page size you want for the file; as usual, it must be a multiple of 512 bytes, up to 4096 bytes. Pages is the number of pages Btrieve should preallocate to the file. Mode indicates whether the file should be over written if it already exists. A typical call could be : F.Create(bNormal, 100, 512, 0, bNoOverWrite); This file would have no special features like variable length records, is 100 bytes long, has a 512 byte page size, has no preallocated pages, and will not over write an existing file on the same path. PLEASE NOTE: Before calling Create you must define the keys by calls to AddKeySegment. 12 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── See the bXXXXX constants, AddKeySegment, Init. CreateIndex : Procedure CreateIndex; Adds a new supplemental index to the file. First, you must set up the new index by calling AddSupplKeySegment. If you are adding more than one new index, create each one separately. See AddSupplKeySegment. Delete : Procedure Delete; Deletes the current record from the file. You must have previously read a record. See Get, GetDirect. DropIndex : Procedure DropIndex(Index : Integer); Removes the supplemental index specified by the parameter Index from the file. EndTransaction : Procedure EndTransaction; Ends the current Btrieve transaction. See AbortTransaction, StartTransaction. Error : Function Error(ErrStatus: Integer; OpCode : Byte; FileName : PathStr ): Boolean; This method is intended mainly for internal use. If the error handler is not nil just makes a call to the error handlers Error method. FillKeyBuffer : Procedure FillKeyBuffer(var Buff; Size : Byte); This method is for copying data directly into the key buffer. Size is the number of bytes to copy. FixKeyStrings : Procedure FixKeyStrings; Justifies all key strings when writing a record. Internal use only. Get : Procedure Get(Op : Word; Lock : Word); Read a record from the file, this file will execute gets or steps. If you are reading by key value, before executing this method you must set up the key by calling MakeKey. Op is the type of read to attempt, such as equal to the key, greater than the key, less than the key, step first, step last, next record, or previous record. Lock is a standard Btrieve locking type. Please see your Btrieve manual for more information on record locking. See the bXXXXX constants, MakeKey, SetKeyPath. GetDirect : Procedure GetDirect(Lock : Word; Position : LongInt); Read a record from the file using a record position. Lock is a standard Btrieve locking type. Position is the position of the desired record, you should get this by a call to GetPosition. You may want to call SetKeyPath to establish the index that will be active after the read. Please see 13 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── your Btrieve manual for more information on record locking. See the bXXXXX constants, GetPosition, SetKeyPath. GetPosition : Function GetPosition: LongInt; Returns the position of the current record in the file. You must have previously read a record. Use the value returned as the position parameter to GetDirect. See Get, GetDirect. GetErrors : Procedure GetErrors(var ErrorCodes : ErrorSet); Returns the full set of trapped error codes currently set in the error handler. See TrappedErrors, SetErrors, AddErrors, RemoveErrors, bXXXXX constants. Insert : Procedure Insert; Add a new record to the file. Just fill the file buffer (pointed to by Data) and call this method. When writing variable length records be sure to set the actual number of bytes of data by a call to SetOutputSize. See SetOutputSize, Update. IsOpen : Function IsOpen: Boolean; Returns TRUE if the file is open. Load : Function Load(InputFilePath : PathStr; DisplayObj : PProgress): Integer; Reads records from a DOS file and inserts them into the file. This operates the same as BUTIL with the -Load option. The file being read must be in the same format as BUTIL generates with the -Recover option. Load will read the files generated by the Save method. InputFilePath is the name of the DOS file to read from. DisplayObj is a pointer to a method that can be called to display the progress of Load. Recover. DisplayObj can be nil, in that case no call will be made. Load will return a non-zero value if any errors occur. If there is an error, you can check the value of bResult to tell which file had a problem. If bResult returns zero, then the DOS file had an error. If the error returned is bLoadInputErr, then the DOS file is not in the correct format. See Save. MakeKey : Procedure MakeKey(V1 : Pointer; V2 : Pointer; V3 : Pointer; V4 : Pointer; V5 : Pointer; V6 : Pointer); Use this method to build a key before reading a record. The V1..V6 parameters are the addresses of the data values that will make up the key. These parameters must be specified in the same order as in the key. A key will be built for the current index, held in the CurIndex field. 14 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── Any unused parameters should be passed with a value of nil. A typical call might be : F.MakeKey(@State, @City, nil, nil, nil, nil); You may need to call SetKeyPath to establish the index that you want to use. See the bXXXXX constants, SetKeyPath. NumberOfRecords : Function NumberOfRecords: LongInt; Returns the NumberOfRecords, actually the largest number of records ever in the file, reported by Btrieve. Open : Procedure Open(Mode : Integer; Owner: String); Open a file. Mode is the file access mode such as accelerated, exclusive, read only or verify. It would normally be set to zero. Owner is the eight character file owner name. Unless you have set an owner name with a call to SetOwner, this should be a null string. See the bXXXXX constants, SetOwner, Init. Recover : Function Recover(NewFilePath : PathStr; DisplayObj : PProgress): Integer; Recover Clones the file, then copies all possible records to the new file. The file should be opened in Read Only mode. NewFilePath is the name of the new file to create. DisplayObj is a pointer to a method that can be called to display the progress of Recover. DisplayObj can be nil, in that case no call will be made. Recover will return a non-zero value if any errors occur. If there is an error, you can check the value of bResult to tell which file had a problem. If bResult returns zero, then the new file had an error. RemoveErrors : Procedure RemoveErrors(ErrorCodes : ErrorSet); Use RemoveErrors to remove a set of error codes from those handled by the file's error handler. Use it in conjunction with AddErrors to turn an error on and off for automatic trapping. RemoveErrors just makes a call to the error handler RemoveErrors method, so it is here mostly for convenience. You could just as well remove errors by dereferencing the ErrHandler pointer. But this is one of the most often used calls for the error handler. See AddErrors, ErrHandler, TErrorHandler. Reset : Procedure Reset; Resets all resources held by a workstation. Save : Function Save(NewFilePath : PathStr; DisplayObj : PProgress): Integer; Writes all the records that can be read to a DOS file. The file should be opened in Read Only mode. This method operates the same as BUTIL with the -Recover option. The file being written is in the same format as BUTIL needs for its -Load option. Save generates file that can be read by the 15 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── Load method. NewFilePath is the name of the DOS file to create. DisplayObj is a pointer to a method that can be called to display the progress of Save. DisplayObj can be nil, in that case no call will be made. Save will return a non-zero value if any errors occur. If there is an error, you can check the value of bResult to tell which file had a problem. If bResult returns zero, then the DOS file had an error. See Load. SetErrors : Procedure SetErrors(ErrorCodes : ErrorSet); Setup the full set of trapped errors currently used by the error handler. See SetErrors, GetErrors, AddErrors, RemoveErrors, bXXXXX constants. SetKeyPath : Procedure SetKeyPath(Number : Word); Sets the key number (access path) that will be used for all reads and writes. SetOutputSize : Procedure SetOutputSize(Size : Word); Call SetOutputSize to set the length of the buffer before writing a record to the file. This defaults to the size of the record defined in the file, so this is used only for variable length records. SetOwner : Procedure SetOwner(Owner : String; Mode : Integer); Owner is the eight character file owner name. Mode is the restrictions desired on access to the file. Please consult your Btrieve manual for more information on these restrictions. See the bXXXXX constants, ClearOwner. StartTransaction : Procedure StartTransaction(Lock : Word); Start a Btrieve transaction. See AbortTransaction, StartTransaction. Stat : Procedure Stat(var FData : FileSpec); Returns the file statistics reported by Btrieve. Unload : Procedure Unload; Unloads Btrieve from memory. UnlockAll : Procedure UnlockAll(Lock : Word); Unlocks all locked records in the file. Lock identifies the type of locks that are active. Less than or equal to 200 indicates single locks, greater than 200 indicates multiple record locks. Please see your Btrieve manual for more information on record locking. See the bXXXXX constants. Update : Procedure Update; Updates an existing record in the file. When writing variable length records be sure to set the actual number of bytes of data by a call to 16 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── SetOutputSize. See SetOutputSize, Insert. Version : Procedure Version(var Ver : Word; var Rev : Word; var OSFlag : Char); Returns the version number of Btrieve that is running. Ver is the full version number, Rev is the revision number, OSFlag indicates the operating system. OBJECT DECLARATIONS - ErrorHandler FIELDS - RetryCount : RetryCount : Word; The number of times an operation has been attempted so far. RetryCount is only used on lock errors. MaxRetry : MaxRetry : Word; The maximum number of retries allowed. RetryDelay : RetryDelay : Word; Delay between retries. TrappedErrors : TrappedErrors : ErrorSet; Set of all trapped errors. Any error in this set will be checked for by ErrorHandler and passed to an error display routine. This set defaults to all errors except End Of File. ErrorDisplay : ErrorDisplay : PErrorDisplay; Pointer to the object that will be called to display errors. If ErrorDisplay is nil, no errors will be displayed. METHODS - Init : Constructor Init(var DisplayObject: PErrorDisplay); Initialize the error handler. DisplayObject is the object that will be called to display errors. If DisplayObject is nil, no errors will be displayed. See Done, ErrorDisplay object. Done : Destructor Done; Virtual; Destroys the object. See Init. AddErrors : Procedure AddErrors(ErrorCodes : ErrorSet); Add the errors in the set ErrorCodes to the set of trapped errors. See ErrorSet, TrappedErrors, SetErrors, GetErrors, RemoveErrors, bXXXXX constants. 17 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── ClearRetry : Procedure ClearRetry; Clears the current number of retries. See SetDelay, GetDelay, RetryCount, ClearRetry, MaxRetry, GetMaxRetry. ErrorDispatcher : Function ErrorDispacther(ErrorCode : Integer; OpCode : Byte; FileName : PathStr ): ErrorAction; Virtual; ErrorDispatcher is called by the Error method. The error code, error description, operation code, operation description, and file path name will be passed to the error display object to display and classify. The error object will return an action code, erAbort, erDone, or erRetry. On erAbort the program will be immediately halted. erDone will cause the error state to be cleared, so the operation will return to your program code. erRetry will leave the error state to TRUE, so the operation can be retried. See Error, ErrorDisplay object, ErrorAction, bXXXXX constants. Error : Function Error(Status : Integer; OpCode : Byte; FileName : PathStr ): Boolean; Virtual; If Status is in the set of trapped errors (zero cannot be added to the set), Error calls the ErrorDispatcher method. The status will be passed to the ErrorDisplay object through the ErrorDispatcher routine. In the case of file or record lock errors (84, 85), no error will be generated until the operation has been tried the number of times stored in RetryCount. If the action code returned by the error dispatcher is erDone, Error will return FALSE to the calling routine, indicating no more errors. If the action code is erRetry then TRUE is returned, so the calling routine will execute the operation again. If a Status is not in the set of trapped errors, FALSE is always returned. In this case the program must check the file status for errors. See ErrorDispatcher, ErrorDisplay object, ErrorAction, bXXXXX constants. ErrorMsg : Function ErrorMsg(ErrorCode : Integer ): String; Virtual; Returns a string describing the error associated with ErrorCode. See the bXXXXX constants. GetDelay : Function GetDelay: Word; Returns the current seconds delay between retries. See GetDelay, RetryCount. GetErrors : Procedure GetErrors(var ErrorCodes : ErrorSet); Returns the full set of trapped error codes. 18 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── See TrappedErrors, SetErrors, AddErrors, RemoveErrors, ErrorSet, bXXXXX constants. GetMaxRetry : Function GetMaxRetry: Word; Return the maximum number of retries. See RetryCount, ClearRetry, MaxRetry, SetMaxRetry. OpMsg : Function OpMsg(OpCode : Integer): String; Virtual; Returns a string describing the operation associated with OpCode. See the bXXXXX constants. RemoveErrors : Procedure RemoveErrors(ErrorCodes : ErrorSet); Remove the errors in the set ErrorCodes from the set of trapped errors. See TrappedErrors, SetErrors, GetErrors, AddErrors, ErrorSet, bXXXXX constants. SetDelay : Procedure SetDelay(Seconds : Word); Set the seconds of delay between retries. This delay is only used for lock errors. See GetDelay, RetryCount. SetErrors : Procedure SetErrors(ErrorCodes : ErrorSet); Setup the full set of trapped errors. See SetErrors, GetErrors, AddErrors, RemoveErrors, ErrorSet, bXXXXX constants. SetMaxRetry : Procedure SetMaxRetry(Retry : Word); Set the maximum number of retries. See RetryCount, ClearRetry, MaxRetry, GetMaxRetry. OBJECT DECLARATIONS - ErrorDisplay METHODS - Init : Constructor Init; Initialize the object; See Done; Display : Function Display(Error : Integer; ErrorMsg : String; OpCode : Byte; OpCodeMsg : String; FileName : PathStr ): ErrorAction; Virtual; This routine is called by the error handler, for any errors that are in the set of trapped errors. Error is the Btrieve status code, ErrorMsg a description of the error code. OpCode is the operation that generated the 19 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── error. OpCodeMsg is a description of the operation. FileName is the full path name for the file. This routine must return an action code that will tell the error handler what to do next. Here is an example of a what typical error display method might look like : Function TheErrorDisplay.Display(Error: Integer; ErrorMsg: String; OpCode: Byte; OpCodeMsg: String; FileName: PathStr): ErrorAction; var Ch : Char; begin GotoXY(1,1); { show what happened } Writeln('<BTRIEVE IO ERROR>'); Writeln(FileName); Writeln(ErrorMsg); Writeln(OpCodeMsg); Case Error of { a couple errors to abort on } bFileNotOpen, bFileNotFound, bNotLoaded : begin Writeln('Press a key ...'); Ch := ReadKey; Display := erAbort; end; else { we will let user decide what to do here } begin Writeln('Do you wish to try again (Y/N)?'); Ch := UpCase(ReadKey); if (Ch = 'Y') then Display := erRetry else Display := erDone; end; end; end; As you can see, you have full control of what happens because of any error. You can use the opcode and error to classify errors and control the error handler actions. Pass back erAbort to halt the program, erRetry to make another attempt, or erDone to continue and return the error to your program. Done : Destructor Done; Virtual; Destroys the object. See Init. OBJECT DECLARATIONS - TProgress METHODS - Init : Constructor Init; Display : Procedure Display(Count : LongInt); This method is called by Recover, Save, and Load to display the progress of the operation. You must define a new descendant object with a working 20 BTV - Turbo Pascal OOP Interface for Btrieve Version 1.15 ────────────────────────────────────────────────────────────────────────────── Display method. Before calling Recover, Save, or Load, initialize an object of your new type. Then pass a pointer to your object to Recover, Save, or Load. Your Display method will be called every ten records plus one final time when the operation is complete. 21 APPENDIX A - bXXXXX Constants The following are Btrieve defined operation codes. bOpen = 0 bEndTransaction = 20 bClose = 1 bAbortTransaction = 21 bInsert = 2 bGetPosition = 22 bUpdate = 3 bGetDirect = 23 bDelete = 4 bStepNext = 24 bGetEqual = 5 bStop = 25 bGetNext = 6 bVersion = 26 bGetPrev = 7 bUnlock = 27 bGetGreat = 8 bReset = 28 bGetGreatEqual = 9 bSetOwner = 29 bGetLess = 10 bClearOwner = 30 bGetLessEqual = 11 bCreateIndex = 31 bGetFirst = 12 bDropIndex = 32 bGetLast = 13 bStepFirst = 33 bCreate = 14 bStepLast = 34 bStat = 15 bStepPrev = 35 bBeginTransaction = 19 bGetKey = 50 The following are Btrieve defined status codes. bOkay = 0 bNullKeypath = 44 bInvalidOp = 1 bBadKeyFlags = 45 bIOerror = 2 bFileAccessDenied = 46 bFileNotOpen = 3 bMaxOpenFiles = 47 bKeyNotFound = 4 bInvalidAltSequence = 48 bDuplicateKey = 5 bKeyTypeErr = 49 bInvalidKey = 6 bOwnerIsSet = 50 bDifferentKey = 7 bInvalidOwner = 51 bInvalidPos = 8 bCacheWriteErr = 52 bEOF = 9 bInvalidVersion = 53 bKeyModifyErr = 10 bVariablePageErr = 54 bInvalidName = 11 bAutoIncrementErr = 55 bFileNotFound = 12 bBadIndex = 56 bExtendedFileErr = 13 bExpandedMemoryErr = 57 bPreImageOpenErr = 14 bCompressBuffShort = 58 bPreImageIOErr = 15 bFileExists = 59 bExpansionErr = 16 bRejectMax = 60 bCloseErr = 17 bWorkSpaceShort = 61 bDiskFull = 18 bDescriptorErr = 62 bUnRecoverableErr = 19 bExtInsertBuffErr = 63 bNotLoaded = 20 bFilterLimit = 64 bKeyBufferShort = 21 bFieldOffsetErr = 65 bDataBufferShort = 22 bTTSabort = 74 bPosBlockShort = 23 bDeadlock = 78 bPageSizeErr = 24 bConflict = 80 bCreateIOErr = 25 bLockErr = 81 bNumberKeys = 26 bLostPosition = 82 bInvalidKeyPos = 27 bOutOfTransaction = 83 bRecordLenErr = 28 bRecordInUse = 84 bKeyLenErr = 29 bFileInUse = 85 bNotBtrieveFile = 30 bFileTblFull = 86 bFileExtended = 31 bHandleTblFull = 87 bExtendIOErr = 32 bBadModeErr = 88 22 bExtendNameErr = 34 bDeviceTableFull = 90 bDirectoryErr = 35 bServerErr = 91 bTransactionErr = 36 bTranTableFull = 92 bTransactionActive = 37 bBadLockType = 93 bTransactionFileErr = 38 bPermissionErr = 94 bTransactionEndErr = 39 bSessionInvalid = 95 bTransactionMaxFiles= 40 bCommunicationErr = 96 bOpNotAllowed = 41 bDataMessageShort = 97 bAcceleratedErr = 42 bInternalTTSerr = 98 bInvalidAddress = 43 The follwing are special BTV.PAS defined errors. Use the constant names, since the numeric value could well change if Novell adds more error codes. bOutOfMemory = 120 Indicates that buffers could not be allocated due to low memory. bDuplicateFilename = bOutOfMemory + 1 The filename passed to Clone, Recover, Save, Load is the same as the file's name. bLoadInputErr = bDuplicateFilename + 1 Something is wrong with the data that Load is trying to read. bLastError = bLoadInputErr Use if you need the last valid error number for error trapping. The following are BTV.PAS defined constants. bNormal = 0 bRJustify = 1 bLJustify = 2 These are the two types of key string justifications. The following is a Btrieve defined file create mode. bNoOverWrite = -1 The following are Btrieve defined file owner access modes. bReadAccess = 1 bReadAccessEncrypt = 3 bWriteAccessEncrypt = 2 The following are Btrieve defined file attribute flags. bVariableLen = 1 bKeyOnly = 16 bBlankTruncate = 2 b10Free = 64 23 bPreallocate = 4 b20Free = 128 bDataCompress = 8 b30Free = 192 The following are Btrieve defined file open modes. bAccelerated = -1 bVerify = -3 bReadOnly = -2 bExclusive = -4 The following are Btrieve defined key attribute flags. bDuplicates = 1 bAltSequence = 32 bModifiable = 2 bDescending = 64 bBinary = 4 bSupplemental = 128 bNull = 8 bExtended = 256 bSegmented = 16 bManual = 512 The following are Btrieve defined key types. bString = 0 bLogical = 7 bInteger = 1 bNumeric = 8 bFloat = 2 bBfloat = 9 bDate = 3 bLstring = 10 bTime = 4 bZstring = 11 bDecimal = 5 bUnsigned = 14 bMoney = 6 bAutoIncrement = 15 The following are Btrieve defined lock types. bNoLock = 0 bMultipleWait = 300 bSingleWait = 100 bMultipleNoWait = 400 bSingleNoWait = 200 24 APPENDIX B - Revision History and Notes Date Ver What ============================================================================= 02/01/92 1.01 Changed DataSize, BytesRead, BytesToWrite from Integer to Word so variable length records can be up to 64K. 02/04/92 Check that memory allocation size > 0 before issuing an out of memory error. Added ErrorHandler calls for out of memory errors. 02/08/92 Added error setting routines to the file object, so calls through the error handler object pointer are not needed. 02/20/92 Fixed bug in Clone. Wrong file name being used caused lockup. 02/28/92 1.10 Added Recover, Save and Load methods. 03/14/92 1.11 Open was not calculating the largest key correctly. 04/25/92 1.15 Added the FillKeyBuffer method. 05/13/92 Fixed problem with KeyStart buffer not being setup when key segments not defined before opening a file. Changed Error Handler and Error Display in fields in all objects, and the corresponding parameters in methods, to pointers. This allows nil error objects. PLEASE NOTE : This change will cause a type mismatch when you recompile. Just stick a "@" before any error object parameters and try it again. 25