Btrieve API Function Parameters

Btrieve API Function Parameters

You must provide all parameters on every call; however, the transactional interface does not use every parameter on every operation. In some cases, the transactional interface ignores their value. In general, different parameters can be sent and returned for each operation. Chapter 2, Btrieve API Operations provides a detailed description of the parameters that are relevant for each Btrieve API 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 API functions are as follows:

•

•

Status Code (BASIC and COBOL only)

•

•

•

Data Buffer Length

•

•

•

Client ID (BTRVID and BTRCALLID functions only)

•

Key Length (BTRCALL, BTRCALLID, BTRCALL32, and BTRCALLID32 functions only)

The Operation Code parameter determines what action is performed by the Btrieve API 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 API call. The transactional interface never changes the Operation Code. The value of the variable you specify can be any one of the legal Btrieve API Operation Codes described in Chapter 2, Btrieve API Operations.

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

The transactional interface returns status codes as signed integers. In most programming environments, the status code is the return value of the Btrieve API 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 API call, the application must always check the value of the status variable to determine if the call was successful.

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

•

•

Anticipated API failure

•

Unanticipated API failure

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");

/* 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 PSQL 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.)

The Position Block parameter is the address of a 128byte array that the transactional interface 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.

The transactional interface 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 API 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 transactional interface uses the Position Block to determine which file a particular call is for. Similarly, when you open the same file more than once, the transactional interface uses a different Position Block for each separate Open operation. Likewise, the transactional interface uses a different Position Block for each separate client that opens the same file. Multiple clients cannot share position blocks.

Your application transfers data to and from a file using the Data Buffer. The information passed to or from the transactional interface in the Data Buffer depends on which Btrieve API 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 API operation, the Data Buffer can contain other information, such as file or key specifications, transactional interface 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, transactional interface 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 transactional interface 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 transactional interface to overwrite memory. The Data Buffer Length should always represent the size of the allocated Data Buffer.

Your application must pass the Key Buffer parameter on every Btrieve API 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 API 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 API 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 transactional interface 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 transactional interface cannot determine the Key Buffer length when an application makes a Btrieve API 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 API 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.

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 API function never alters the Key Number parameter.

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 transactional interface to differentiate among the clients on a computer. Use the following structure for the Client ID.

Table 2

Client ID Structure

Initialize to 0.

Service Agent ID

2

Identifies each instance of your application to the transactional interface. This is a 2-character ASCII value. The value of this identifier must be greater than or equal to the ASCII value AA (0x41 0x41). The transactional interface assumes special meaning for the following values:

Used internally.

Used internally.

Used internally.

Used internally.

0x4553 (SE)
0x4353 (SC)
0x4344 (DC)
0x4544 (DE)
0x5544 (DU)

Used to identify clients originated by Scalable SQL.

Used by Btrieve Requesters.

Client Identifier

2

Establishes a client’s identity within the current instance of your application. The transactional interface uses this unique identifier for concurrency and transaction-processing purposes.

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).