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 you are 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
1
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 PSQL Programmer's Guide.
2
Pass the position block for the file.
3
Store the 4-byte position of the requested record in the first 4 bytes of the data buffer.
4
Set the data buffer length to a value greater than or equal to the length of the record to retrieve.
5
Set the key number to the key number of the path for which you want the MicroKernel Engine to establish logical currency. Specify -1 if you do not want the MicroKernel Engine 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 Engine 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 Engine cannot return the requested record, the MicroKernel Engine 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 Engine 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.