Get Direct/Record (23)

The Get Direct/Record operation (B_GET_DIRECT) retrieves a record using its physical location in the file instead of using one of the defined key paths.

Use Get Direct/Record to accomplish the following:

Retrieve a record faster using its physical location instead of its key value.

Use the Get Position operation (22) to retrieve the 4-byte location of a record, save the location, and use Get Direct/Record to return directly to that location after performing other operations that affect currency.

Use the 4-byte location to retrieve a record in a chain of duplicates without rereading all the records from the beginning of the chain.

Change the current key path. A Get Position operation, followed by a Get Direct/Record operation with a different key number, establishes positioning for the current record in a different index path. A subsequent Get Next returns the next record in the file based on the new key path.

Parameters


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

Note
The Key Number parameter is not needed when performing a Get Direct/Record operation on a data-only file.

Prerequisites

The file must be open.

You must provide the 4-byte physical location of the record. You can retrieve this location with a Get Position operation (22), which returns the physical address of the current record.

Procedure

Set the Operation Code to 23. 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.SQL Programmer's Guide.

Pass the Position Block for the file.

Store the 4-byte position of the requested record in the first 4 bytes of the Data Buffer.

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

Set the Key Number to the key number of the path for which you want the MicroKernel to establish logical currency. Specify -1 if you do not want the MicroKernel to establish logical currency. To use the system-defined log key (also called system data), specify 125.

Result

If the Get Direct/Record operation is successful, the MicroKernel returns the requested record in the Data Buffer, the length of the record in the Data Buffer Length parameter, and the key value for the specified key path in the Key Buffer.

If the Get Direct/Record operation is unsuccessful and the MicroKernel cannot return the requested record, the MicroKernel returns one of the following status codes:


22	The data buffer parameter is too short. (Logical currency is still established.)
43	The specified record address is invalid. (Logical currency is not established.)
44	The specified key path is invalid. (Logical currency is not established.)
82	The MicroKernel lost positioning. (Logical currency is not established.)

Positioning

The Get Direct/Record operation erases any existing logical currency information and establishes the new logical currency according to the Key Number specified. It has no effect on the physical currency information.