Get First (12)

The Get First operation (B_GET_FIRST) retrieves the logical first record based on the specified key. You can use the Get Key (+50) bias to detect the presence of a value in a file. A Get Key operation is generally faster.

Parameters


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

Prerequisites

The file must be open.

The file cannot be a data-only file.

Procedure

Set the Operation Code to 12. Optionally, you can include a lock bias:

+100-Single wait record lock.

+200-Single no-wait record lock.

+300-Multiple wait record lock.

+400-Multiple no-wait record lock.

For more information about locking, refer to the Pervasive PSQL Programmer's Guide.

Pass the Position Block for the file.

Set the Data Buffer Length to a value greater than or equal to the length of the record to retrieve.

Indicate the Key Number for the key path. To use the system-defined log key (also called system data), specify 125.

Result

If the Get First operation is successful, the transactional interface returns the requested record in the Data Buffer, stores the corresponding key value in the Key Buffer, and returns the length of the record in the Data Buffer Length parameter.

If the Get First operation is unsuccessful, the transactional interface returns one of the following status codes:


3	The file is not open.
6	The key number parameter is invalid.
9	The operation encountered the end-of-file.
22	The data buffer parameter is too short.

Positioning

The Get First operation establishes the complete logical and physical currencies and makes the retrieved record the current one. The logical previous position points beyond the beginning of the file.