Btrieve Function Parameters

You must provide all parameters on every call; however, the MicroKernel does not use every parameter on every operation. In some cases, the MicroKernel ignores their value. In general, different parameters can be sent and returned for each operation. Chapter 2, Btrieve Operations provides a detailed description of the parameters that are relevant for each Btrieve operation.

---

Note
C developers: Refer to BTITYPES.H for a description of the platform-independent data types and pointers used in the C language interface.

---

The parameters to the Btrieve functions are as follows:

Operation Code

The Operation Code parameter determines what action is performed by the Btrieve function. For example, the operation may read, write, delete, or update one or more records. Your application must specify a valid Operation Code on every Btrieve call. The MicroKernel never changes the Operation Code. The value of the variable you specify can be any one of the legal Btrieve Operation Codes described in Chapter 2, Btrieve Operations.

---

Note
C developers: The variable you specify must be BTI_WORD (an unsigned short integer), and is passed by value.

---

Status Code

Btrieve returns status codes as signed integers. In most programming environments, the status code is the return value of the Btrieve function call. However, some BASIC and COBOL language interfaces require a Status Code parameter. This parameter is a 2-byte integer containing a coded value that indicates whether any errors occurred during the operation. After a Btrieve call, the application must always check the value of the status variable to determine if the call was successful.

Pervasive.SQL components return status codes from calls to their APIs. When you write to these APIs, you should provide handling for three conditions:

Following is a C code example that handles all three conditions.

status = BTRVID(B_VERSION, posBlock1, 
&versionBuffer, &dataLen, keyBuf1, keyNum, 
(BTI_BUFFER_PTR) &clientID); 
if (status == B_NO_ERROR) 
{ 
    /* continue normal operation */ 
    status = BTRVID(...); 
} 
else if (status == B_RECORD_MANAGER_INACTIVE) 
{ 
    /* handle known error */ 
    printf("Btrieve Get Version() returned 
B_RECORD_MANAGER_INACTIVE\n"); 
} 
else 
{ 
    /* unanticipated error */ 
    printf("Btrieve Get Version() returned %d\n", 
status); 
} /* end if-else */ 

By following this method of status code handling, you can help Pervasive Software ensure your application's future stability. Pervasive Software encourages and incorporates developer feedback in order to continuously improve our products. For example, in Pervasive.SQL 7, status code 20 was differentiated into several additional status codes based on customer feedback. Applications that handle status information as demonstrated here can accept such enhancements gracefully. (For more information about the differentiation of status codes, refer to Status Codes and Messages.)

Position Block

The Position Block parameter is the address of a 128byte array that the MicroKernel uses to store file I/O structures and the positioning information associated with an Open (0) operation. Each time your application opens a file, it must allocate a unique Position Block.

Btrieve initializes the Position Block when your application performs the Open operation, then references and updates it during file operations. Therefore, your application must specify the same Position Block on all subsequent Btrieve operations for the file.

---

Note
Do not write to the Position Block. Doing so could result in a lost position error, other errors, or damage to the file.

---

When you open more than one file at a time, the MicroKernel uses the Position Block to determine which file a particular call is for. Similarly, when you open the same file more than once, the MicroKernel uses a different Position Block for each separate Open operation. Likewise, the MicroKernel uses a different Position Block for each separate client that opens the same file. Multiple clients cannot share position blocks.

Data Buffer

Your application transfers data to and from a file using the Data Buffer. The information passed to or from the MicroKernel in the Data Buffer depends on which Btrieve operation is being performed. Frequently, the Data Buffer contains one or more records that your application is transferring to or from a file. However, depending on the Btrieve operation, the Data Buffer can contain other information, such as file or key specifications, MicroKernel version information, and so on.

Be sure to allocate a large enough Data Buffer to accommodate the longest record in your file. If your Data Buffer Length parameter specifies a value larger than the allocated size of your Data Buffer, Btrieve modification operations may destroy data following the Data Buffer.

Data Buffer Length

For any operation that requires a Data Buffer, your application must pass a variable that indicates the size (in bytes) of the Data Buffer, which should be large enough to contain data that the operation returns.

---

Note
BASIC developers: Your application must pass the Data Buffer Length parameter ByRef as a Long integer.

C, COBOL, and Pascal developers: Your application must pass the Data Buffer Length parameter as a pointer to a 2-byte unsigned integer.

---

When you are inserting records into or updating a file with variable-length records, the Data Buffer Length 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, the Data Buffer Length should be large enough to accommodate the longest record in the file. If a record is longer than 64 KB, you must use a chunk operation to operate on a portion of the record.

The MicroKernel uses the Data Buffer Length parameter to determine how much space is available in the Data Buffer. If you pass a Data Buffer Length that is longer than the Data Buffer you have allocated, you may cause the MicroKernel to overwrite memory. The Data Buffer Length should always represent the size of the allocated Data Buffer.

Key Buffer

Your application must pass the Key Buffer parameter on every Btrieve operation, even if that operation does not use a Key Buffer. Depending on the operation, your application may set the data in the Key Buffer, or the Btrieve function may return it.

---

Note
BASIC developers: Your application must pass the Key Buffer as a string. If the key value is an integer, your application should convert it to a string using the MKI$ statement before calling the Btrieve function. If a key consists of two or more segments, you must concatenate them into a single string variable and pass the variable as the Key Buffer.

The MicroKernel returns an error if the string variable passed as the Key Buffer is shorter than the key's defined length. If your application's first call does not require initialization of the Key Buffer, assign the string variable the value SPACE$(x), where x represents the key's defined length. Until your application assigns some value in BASIC to the string variable, it has a length of 0.

C developers: Your application must pass the Key Buffer as the address of a variable containing the key value. The file BTITYPES.H defines the Key Buffer as a VOID pointer (BTI_VOID_PTR). Your application can then define the Key Buffer type as needed.

COBOL developers: Your application must pass the Key Buffer as a record variable. 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 as the Key Buffer.

Pascal developers: Your application must pass the Key Buffer as a variable containing a key value. If a key consists of two or more segments, use a record structure to define the individual fields in the key.

---

In most environments, the MicroKernel cannot determine the Key Buffer length when an application makes a Btrieve call. Therefore, you must ensure that the buffer is at least as long as the key length you specified when you first created the key. Otherwise, Btrieve operations may destroy data stored in memory following the Key Buffer. It is best to always have a 255-byte Key Buffer, because 255 is the maximum length for a key.

Key Number

The information passed in the Key Number parameter depends on which operation is being performed. Most often, the Key Number contains a value that indicates which of up to 119 key (access) paths to follow for a particular operation. However, other information can be sent or returned in the Key Number parameter, such as a value indicating in what mode a file is to be opened.

For BTRV and BTRVID functions, the Key Number parameter is a 2-byte integer. For BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 functions, the Key Number parameter is a 1-byte signed CHARACTER (BTI_CHAR). In all functions, the Key Number parameter has a value range of 0 through 118. A Btrieve function never alters the Key Number parameter.

Client ID

The Client ID parameter is used only in the BTRVID and BTRCALLID functions. The Client ID parameter is the address of a 16-byte structure that allows the MicroKernel to differentiate among the clients on a computer. Use the following structure for the Client ID.

Key Length

The Key Length parameter is used only in the BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 functions.

When using these functions, you must pass the Key Length parameter as an unsigned char (BTI_BYTE), with a value of the allocated length of your Key Buffer. The maximum length you can specify is 255 (the maximum length of any key).