DbiGetNextRecord

C syntax

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

Delphi syntax

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

Description

DbiGetNextRecord retrieves the next record in the table associated with hCursor.

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, DbiGetNextRecord reads the data for the record into the record buffer. If the precProps argument is supplied, record properties are returned (dBASE, FoxPro, Access, and Paradox only). If filters are active, the next record that meets the filter criteria is 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.)

Field data can be retrieved using DbiGetField or DbiOpenBlob or DbiGetBlob for BLOB fields.

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

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

SQL: Record properties are not supported for SQL drivers. If precProps is supplied, no properties are returned. For more information on locking, see Locking Strategy

Completion state

If the cursor is at the beginning of a table (after a opening a table or calling DbiSetToBegin), DbiGetNextRecord positions the cursor on the first record of the table. If the cursor is currently positioned on the last record in the table, DbiGetNextRecord returns an EOF error.

DbiResult	Meaning
DBIERR_NONE	The next record was successfully retrieved.
DBIERR_EOF	The cursor was positioned at the crack at the end of the file or on the last record. It is now positioned at the crack at the end 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).