DbiGetPriorRecord

C syntax

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

Delphi syntax

function DbiGetPriorRecord (hCursor: hDBICur; eLock: DBILockType; pRecBuff: Pointer; precProps: pRECProps): DBIResult stdcall;

Description

DbiGetPriorRecord retrieves the previous record in the table associated with the given cursor.

Parameters

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

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. For dBASE, FoxPro, and Paradox drivers only. Optional. If NULL, no record properties are returned.

Usage

If a record buffer is provided, DbiGetPriorRecord reads the data for the record into the record buffer. If the precProps argument is supplied, record properties are returned (for dBASE, FoxPro, Access, and Paradox 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 fails if the requested lock cannot be acquired. (Exceptions: see the discussion of SQL-specific locking behavior that follows.)

dBASE and FoxPro: If the precProps argument is supplied, the record number can be retrieved for the prior 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 prior 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.

Prerequisites

A valid cursor handle must be obtained. If a lock is requested, the call returns DBIERR_NONE only if the lock is granted. For SQL, an error is returned if the cursor is not bidirectional.

Completion state

If the cursor is currently positioned on the first record in the table and the user calls DbiGetPriorRecord, then a BOF error is returned.

DbiResult	Meaning
DBIERR_NONE	The prior record was retrieved successfully.
DBIERR_BOF	The cursor was positioned in the crack before the beginning of the file or on the first record after the crack. The cursor is now positioned in the crack at the beginning of the file.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL.
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 (Paradox, FoxPro, Access, and dBASE only).
DBIERR_NA	Cursor is unidirectional.