Get Equal (5)

The Get Equal operation (B_GET_EQUAL) retrieves a record that has a key value equal to that specified in the Key Buffer. If the key allows duplicates, this operation retrieves the first record (chronologically) of a group with the same key values. 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 5. 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.

Specify the desired key value in the Key Buffer. If the key consists of multiple segments, make sure you define the key buffer to represent all segments and fill in values for all segments. If you don't have search criteria for all segments, use the GetGreaterOrEqual operation instead.

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

Result

If the Get Equal operation is successful, the transactional interface returns the requested record in the Data Buffer and the length of the record in the Data Buffer Length parameter.

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


3	The file is not open.
4	The application cannot find the key value.
6	The key number parameter is invalid.
22	The data buffer parameter is too short.

This operation returns Status Code 4 if the key contains a non-zero value in a null indicator segment. You cannot use GetEqual to find records that are NULL, because by definition NULL is indeterminate, or not equal to anything. If you need to find NULL values, use GetFirst followed by GetNext.

Positioning

The Get Equal operation establishes the complete logical and physical currencies and makes the retrieved record the current one.