---~-~--~~--Application Interfaces
If you are using Turbo Pascal, use the $1 command to include the file TURXBTRV.PAS. The Btrieve function is defined as follows:
function BTRV OP : integer;
var paS_BLOCK, var DATA_BUFFER;
var DATA_LEN : integer;
var KEY_BUFFER;
KEY_NUMBER : integer): integer;
LINKING A PASCAL APPLICATION WITH BTRIEVE
If you are using IBM (or Microsoft) Pascal, you must include the file called PASXBTRV.OBJ in your Pascal link. To link the Pascal object file
(PASPROG) with the IBM Pascal interface, you would respond to the linker prompt for object modules as follows:
Object Modules [.08J]: pasprog+pasxbtrv
If you are using Turbo Pascal, include the interface source file (TURXBTRV.PAS) with your program when you compile.
CALLING BTRIEVE FROM PASCAL
Your Pascal application should never perform any standard Pascal I/O against a Btrieve file. Your application should perform all I/O to a Btrieve file using the Btrieve function. The first Btrieve call your application must perform is an Open operation. Following that, it can read, write, and modify files through Btrieve calls. Before your application terminates, it should perform a Btrieve Close operation.
All calls to Btrieve must be performed through the BTRV function. The result of the function is always an integer value which corresponds to one of the status codes listed in Appendix B. Mter a Btrieve call, your application should always check the value of the status variable. A status of 0 indicates a successful operation. Your application should be able to recognize and resolve a non-zero status.
201 fRev 1.00 5-11
Although you must provide all parameters on every call, Btrieve does not use every parameter for every operation. See Chapter 6 for a more detailed description of which parameters are relevant for each operation. The
following sections describe the parameters.
J
OPERATION CODE
The operation parameter determines which type of Btrieve function you want to perform. Your application is responsible for specifying a valid operation code on every Btrieve call. The Record Manager never changes the operation code. The variable you specify must be an integer type and can be anyone of the legal Btrieve operation codes described in Chapter 6. Appendix A contains a complete list ofthese codes.
POSITION BLOCK
Your application must allocate a separate position block for each Btrieve file it opens. Btrieve initializes the position block when your application performs the Open operation, anq references and updates the data in the position block on all file operations. Therefore, your application should pass the same position block on all subsequent Btrieve operations for the file. When your application has more than one file open at a time, Btrieve uses the position block to determine which file is referenced in a particular call. In addition, your application should never change the values contained in the position block.
An IBM Pascal application must allocate a 128-byte string for the position block. If you are using Turbo Pascal, you should allocate the position block parameter as a 128-byte character array.
DATA BUFFER
The data buffer contains the records that your application transfers to and from the Btrieve file. Btrieve expects a string type for IBM Pascal. For Turbo Pascal, you can use any data type.
5-12 2011Rev1.00
/
(
Application! nterfaces You may want to define a record structure in Pascal to describe the data
stored in a file. To pass a record type variable in IBM Pascal, use the case option to define a string type variant for the structure. For Turbo Pascal, you can send the record itself.
When you calculate the length of the variant string, take into account the fact that odd length elements in a record may require an extra byte of storage whether or not the record is packed. This is also an important consideration when you define the record length for the CREATE utility. See your Pascal reference manual for more information on record types.
DATA BUFFER LENGTH
For any operation that requires a data buffer, your program must pass the length ofthe data buffer in an integer variable. For a file with fixed length records, this parameter should match the record length specified when you first created the file.
When you are inserting records into or updating a file with variable length records, this parameter should equal the record length specified when you first created the file, plus the number of characters included beyond the fixed length portion. When you are retrieving variable length records, this
parameter should be large enough to accommodate the longest record in the file.
KEY BUFFER
Your application must pass a string variable for IBM Pascal, or any type variable for Turbo Pascal, that will contain the key value on each Btrieve call.
Depending on the operation, your application may set this variable, or the Record Manager may return it.
For IBM Pascal, if the key is an integer, you should define it as a record structure with two variants. One variant defines the key as an integer. The other defines it as a two character string. You must use the string variant for Btrieve calls.
For Turbo Pascal, you can pass the key buffer itself, regardless of type.
201 fRev! .00 5-13
If the key consists of two or more segments, use a record structure to define the individual fields in the key. Then use a variant to pass the key buffer to Btrieve.
KEY NUMBER
You may define up to 24 different keys when you create a Btrieve file.
Therefore, your application must tell the Record Manager which access path to follow for a particular operation. The key number parameter is an integer variable with a value from
°
through 23, with 0 being the first key segment defined for the file. The Record Manager never alters this parameter.PARAMETER LIST EXAMPLE
The IBM (or Microsoft) Pascal code shown in Figure 5.3 below opens a Btrieve file and retrieves the data record corresponding to the first value for key 0, the name field.
{Structure of address file entry}
201lRevi.OO
)
;'
Application Interfaces
begin
FILE_NAME := 'B:ADDRESS.BTR ';
STATUS := BTRV (B_OPEN, POS_BLOCK, DATA_BUF.ENTIRE, DB_LEN, FILE_NAME, 0);
if STATUS <> 0 then begin
writeln (OUTPUT, 'Error opening file. Status = ',STATUS); return;
end;
DB_LEN := sizeof (ADDRESS_REC);
STATUS := BTRV (B_GETJST, POS_BLOCK, DATA_BUF.ENTIRE, DB_LEN, KEY_BUF,O);
if STATUS <> 0 then
writeln (OUTPUT, 'Error reading file. Status = ',STATUS) else
end.
writeln (OUTPUT, 'First record in file is:',DATA_BUF.ENTIRE);
Figure 5.3 (Continued) Btrieve Call from IBM Pascal
Figure 5.4 illustrates the same program written for Turbo Pascal. This is the only Turbo Pascal example in this manual. All other Pascal examples are shown for IBM (or Microsoft) Pascal.
In Figure 5.4, the application uses character arrays instead of strings for the fields in the data buffer and the key buffer because Turbo Pascal stores a binary length byte in the first position of a string field when it initializes the field. If you attempt to use such a value as a key in a Btrieve file without defining it as lstring, the results are unpredictable. When Btrieve compares key values for random or sequential searching, it compares them byte-by-byte on an absolute basis. The length byte is treated as part of the value instead of as an indicator of length, unless the key is defined as an lstring type.
Although the example in Figure 5.4 uses variant records for the position block, data buffer, and key buffer parameters, Btrieve does not require that you do this. This example simply illustrates one way of writing this program.
2011Rev1.00 5-15
5-16 {Structure of address file entry}
case integer of
Btrieve Call from Turbo Pascal
{Get first}
{Open file}
2011Rev1.00
c
Application Interfaces
begin
FNAME.VALUE := 'ADDRESS.BTR ';
STATUS := BTRV (B_OPEN, POS.START, DATA_BUF.START, DB_LEN, FNAME.START,O);
DB_LEN := sizeof (ADDRESS_REC);
STATUS := BTRV (B_GETJST, POS.START, DATA_BUF.START, DB_LEN, KBUF.START, 0);
if STATUS <> 0 then
writeln ('Error reading file. Status = " STATUS) else
end;
writeln (,First record in file is:', DATA_BUF.NAME, DATA_BUF.STREET, DATA_BUF.CITY, DATA_BUF.STATE, DATA_BUF.ZIP);
Fig ure 5.4 (Continued) Btrieve Call frol11 Turbo Pascal
INTERFACING BTRIEVE WITH COBOL
In order to access a Btrieve file, your IBM or Microsoft COBOL application must issue a CALL statement. The type offile accesses Btrieve makes when it executes the statement depends on the parameters you specifY. Btrieve provides a small assembly language routine, the COBOL interface, which you must link with your COBOL application. This interface communicates with the Record Manager, which you must load before you start your application.