DbiGetRecord

C syntax

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

Delphi syntax

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

Description

DbiGetRecord retrieves the current record, if any, 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 Paradox, FoxPro, and dBASE drivers only. Optional. If NULL, no record properties are returned.

Usage

If NULL pointers are supplied for pRecBuf and pRecProps, DbiGetRecord can be used to validate the current cursor position (on a current record, or on a crack).

If filters are active, the record is retrieved only if it meets the filter's criteria. 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. Also see Locking.)

If the cursor is currently positioned on a record, and that record is subsequently deleted or the record's key value is changed, then the cursor is left on a crack between records. At this point, a call to DbiGetRecord returns the DBIERR_KEYORRECDELETED error.

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

Paradox: If precProps is supplied, the sequence number can be retrieved for the current 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.

Note:

DbiGetRecordCount is not supported for cursors that reference query results or reference remote tables without a unique index; an error of DBIERR_NOTABLESUPPORT is returned.

DbiResult	Meaning
DBIERR_NONE	The record was successfully retrieved.
DBIERR_BOF	At beginning of file.
DBIERR_EOF	At end of file.
DBIERR_NOCURRREC	No current record.
DBIERR_KEYORRECDELETED	The cursor is positioned on a record that has been deleted, or the key value was changed.
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_LOCKED	The table is already locked by another user (Paradox, FoxPro, Access, and dBASE only).
DBIERR_NOTABLESUPPORT	The cursor is referencing a query result or a remote table without a unique index.