Your application should never perform any standard COBOL I/O against a Btrieve file. It should handle I/O through a call to Btrieve. Mer issuing an Open operation, your program can read, write, and modify files through Btrieve calls. Before terminating, your application should perform a Btrieve Close operation.
Format all calls to Btrieve from a COBOL program according to the example below:
CALL 'BTRV' USING OPERATION, B-STATUS, POSITION-BLOCK, DATA-BUFFER,DATA-LEN, KEY-BUFFER, KEY-NUMBER.
Although you must provide all parameters for every call, Btrieve does not use every parameter to perform every operation. In some cases, Btrieve ignores their value. See Chapter 6 for a more detailed description of which
parameters are relevant for each operation. The following sections describe each parameter.
OPERATION CODE
The operation parameter determines which type of Btrieve function you want to perform. The operation may be a read, write, delete, or update. Your application is responsible for specifying a valid operation code on every Btrieve call. The Record Manager never changes the code. The variable you specify must be COMP-Q type for IBM (or Microsoft) COBOL and can be any one of the legal Btrieve operation codes described in Chapter 6. See Appendix A for a complete list ofthese codes.
5-18 2011Rev1.00
Application Interfaces
STATUS CODE
All calls to Btrieve return a 2-byte integer status value (a COMP-O field for IBM or Microsoft COBOL) that corresponds to one ofthe status codes listed in Appendix B. After a Btrieve call, your application should always check the value of the status variable. A status of 0 indicates a successful operation.
The application should recognize and resolve a non-zero status.
POSITION BLOCK
A COBOL application must allocate a 128-byte record which Btrieve uses to store the file I/O structures and the positioning information described in Chapter 2. Your application must allocate a separate position block for each Btrieve file it opens. Btrieve initializes this record when your application performs the Open operation, and references and updates the data in this record on all file operations. Therefore, your application should pass the same record on all subsequent Btrieve operations for the file. It should never change the value of the position block. When an application has more than one file open at a time, Btrieve uses the position block to determine which file a particular call is for.
DATA BUFFER
The data buffer contains the records that your application transfers to and from the Btrieve file. Ensure that you allocate a large enough data buffer to accommodate the longest record in your file. If the buffer is too short, Btrieve requests may destroy data items following the data buffer.
DATA BUFFER LENGTH
For any operation that requires a data buffer, your program must pass the length of the data buffer as a 2-byte integer (COMP-O field for IBM or
Microsoft COBOL). 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
201lRev1.00 5-19
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
On each Btrieve call, your application must pass a record variable to contain the key value. If the key consists of two or more segments, list them in the correct order as individual fields under an 01 level record. Then you can pass the entire record to Btrieve as the key buffer. Depending on the operation, your application may set this variable or the Btrieve Record Manager may return it.
Btrieve cannot determine the key buffer length when you call it from an IBM (or Microsoft) COBOL program. Therefore, you must ensure that the buffer is at least as long as the key length you specified when you first created the file.
Otherwise, Btrieve requests may destroy data items following the key buffer.
KEY NUMBER
You can define up to 24 different keys when you create a Btrieve file. The application accessing the file must tell the Record Manager which access path to follow for a particular operation. The key number parameter is a 2-byte integer (COMP-O for IBM or Microsoft COBOL) with a value from 0 through 23. The Btrieve Record Manager never alters this parameter.
5-20 2011Rev1.00
/
Application Interfaces
PARAMETER LIST EXAMPLE
The code for an IBM (or Microsoft) COBOL application in Figure 4.5 below opens a Btrieve file and retrieves the data record corresponding to the first value for key 0, the name field.
IDENTIFICATION DIVISION.
PIC X(128) VALUE SPACES.
CALL 'BTRV' USING B-OPEN, B-STATUS, POSITION-BLOCK, DATA-BUFFER,BUF-LEN, FILE-NAME, KEY-NUMBER.
IF B-STATUS NOT
=
0MOVE B-STATUS TO DSP-STATUS
DISPLAY "Error opening file. Status =. DSP-STATUS STOP RUN.
DISPLAY (1, 1) ERASE.
CALL 'BTRV' USING B-GET-FIRST, B-STATUS, POSITION-BLOCK, DATA-BUFFER, BUF-LEN, KEY-BUFFER, KEY-NUMBER.
IF B-STATUS NOT
=
0MOVE B-STATUS TO DSP-STATUS
DISPLAY (5, 1) "Error reading file. Status =" DSP-STATUS ELSE
DISPLAY (5, 1) "First record in file is:" DATA-BUFFER.
STOP RUN.
FlgureS.S
Btrieve Can from IBM COBOL
2011Revl.OO 5-21
INTERFACING BTRIEVE WITH C
The Btrieve diskette contains interfaces for Microsoft and Lattice C as well as \.
several other C compilers. The format for the Btrieve calls is identical for / each. To interface with any other C compiler, refer to Appendix F, which
describes how to interface to Btrieve from assembly language.
Your Btrieve program diskette contains the source code for each ofthese interfaces. All the C interfaces are written in C.
To access a Btrieve file, your application must call the integer function, BTRV. Btrieve provides a small interface routine that links the Btrieve Record Manager with your C application. You must load the Record Manager before you start your application.