DbiGetRelativeRecord

C syntax

DBIResult DBIFN DbiGetRelativeRecord (hCursor, iPosOffset, [eLock], [pRecBuf], [precProps]);

Delphi syntax

function DbiGetRelativeRecord (hCursor: hDBICur; iPosOffset: Longint; eLock: DBILockType; pRecBuff: Pointer; precProps: pRECProps): DBIResult stdcall;

Description

DbiGetRelativeRecord positions the cursor on a record in the table relative to the current position of the cursor.

Parameters

hCursor Type: hDBICur (Input)
Specifies the cursor handle.

iPosOffset Type: INT32 (Input)
Specifies the (signed) offset from current record.

eLock Type: DBILockType (Input)
Specifies the lock request type. Optional.

pRecBuf Type: pBYTE (Output)
Pointer to the client buffer that receives the record data. Optional. If NULL, no data is returned.

precProps Type: pRECProps (Output)
Pointer to the client-allocated RECProps structure.

Usage

This function positions the cursor relative to the current position. The record offset (iPosOffset) can be positive or negative. If the cursor is currently positioned between records, the next or prior (depending on the direction) record is counted as 1. If the filter is active, only those records that meet the filter condition are included. For dBASE or FoxPro if Soft Delete is off, only undeleted records are included.

If a record buffer is provided, DbiGetRelativeRecord reads the data for the record into the record buffer. If the precProps argument is supplied, record properties are returned (for Paradox, FoxPro, Access, and dBASE only). If filters are active, only records that meet the filter's criteria are retrieved. The record can be locked if an explicit lock is specified (using eLock), and the function call returns an error if the requested lock cannot be acquired. See the following section for SQL-specific locking behavior information.

dBASE and FoxPro: If the precProps argument is supplied, the record number can be retrieved for the record (the iPhyRecNum field of the RECProps structure). dBASE and FoxPro do not support the concept of sequence numbers.

Paradox: If the precProps argument is supplied, the sequence number can be retrieved for the record (via the iSeqNum field of precProps). Paradox does not support the concept of record numbers.

SQL: Record properties are not supported for SQL drivers (precProps is NULL). If precProps is supplied, no properties are returned.

Completion state

If not enough records exist in the result set to move to the relative record location, a beginning of file/end of file (BOF/EOF) error is returned. An error is returned if the cursor is not bidirectional, and the cursor is moving backwards.

DbiResult	Meaning
DBIERR_NONE	The record was retrieved successfully.
DBIERR_BOF	The beginning of the file was reached.
DBIERR_EOF	The end of the file was reached.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL.
DBIERR_KEYORRECDELETED	The cursor is positioned in a crack other than BOF or EOF.
DBIERR_ALREADYLOCKED	The record is already locked by the same user in the same session.
DBIERR_FILELOCKED	The table is already locked by another user.