Your application should never perform any standard C VO against a Btrieve file. It should handle VO through a call to Btrieve. Mter 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.
5-22 2011Revl.OO
Application Interfaces
Your application issues calls to Btrieve through the integer function, BTRV.
The result of the function is always an integer value that corresponds to one of the 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. Your application should be able to recognize and resolve a non-zero status.
The function, BTRV, expects parameters of the following types:
int BTRV (OP, POS_BLK, DATA_BUF, BUF _LEN, KEY_BUF, KEY_NUM) int OP;
Although you must provide all parameters on 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
The operation parameter determines which type of Btrieve function you wish to perform. The operation may be a read, write, delete, or update. Your application must specify a valid operation code on every Btrieve call. The Btrieve Record Manager never changes the code. The variable you specify must be an integer type and can be anyone of the legal Btrieve operation codes described in Chapter 6. Also see Appendix A for a complete list of these codes.
POSITION BLOCK
A C application allocates a 128-byte character array that Btrieve will use to store the file I/O structures and the positioning information described in Chapter 2. Btrieve initializes this array when your application performs the Open operation. Btrieve references and updates the data in this array for all file operations. Therefore, your application should pass the same array on all
201lRevl.OO 5-23
subsequent Btrieve operations for the file. It should not change the value stored in this array at any time.
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. Your application must allocate a separate position block for each Btrieve file it opens.
DATA BUFFER
The data buffer parameter is the address of an array or structure-type variable containing 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 address of an integer variable that contains the length of the data buffer. 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 the address of a variable containing the key value on every Btrieve call. If you defined the key as binary when you first created the file, you should define the variable as type int, long, or unsigned. If you originally defined the key as a string, you should define the key buffer
/
~J
variable as a structure or a character array. If the key consists of two or more '\
segments, use a structure variable that contains the segment fields in the / correct order. Depending on the operation, your application may set this
variable or the Btrieve Record Manager may return it.
5-24 2011Revl.OO
c
Application Interfaces
Btrieve cannot determine the key buffer length when called from a C
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 stored in memory following the key buffer.
KEY NUMBER
You can define up to 24 different keys when you create a Btrieve file.
Therefore, the application accessing the file 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. The Btrieve Record Manager never alters this parameter.PARAMETER LIST EXAMPLE
The C code in Figure 4.6 opens a Btrieve file and retrieves the data record corresponding to the first value for key 0, the name field.
#define B_OPEN 0
struct ADDR_REC ADDR_BUF;
int DB_LEN;
char KEY_BUF(30);
char POS_BLK(128);
int STATUS;
201lRevi.OO 5-25
STATUS = BTRV (B_OPEN, POS_BLK, &ADDR_BUF, &DB_LEN, "ADDRESS.BTR", 0);
if (STATUS!= 0) {
}
printf ("Error opening file. Status = %d", STATUS);
exit (0);
DB_LEN = sizeof (ADDR_BUF);
STATUS = BTRV (BJIRST, POS_BLK, &ADDR_BUF, &DB_LEN, KEY_BUF, 0);
if (STATUS 1= 0)
printf ("Error reading file. Status = %d", STATUS);
else };
printf ("First record in file is: %.97s", &ADDR_BUF);
Figure 5.6 Btrieve Call from C
INTERFACING WITH BTRIEVE IN ASSEMBLY LANGUAGE
,
\ /
If you are using Assembly Language or a programming language for which no / interface is provided on the Btrieve diskette, you can write an interface using
Assembly Language. Interfacing Btrieve with an Assembly Language routine requires three basic steps:
• Storing the Btrieve parameters in memory in the format expected by the Record Manager
• Verifying that the Record Manager has been loaded into memory
• Calling the Record Manager by performing an interrupt that transfers control to Btrieve