DbiReadBlock

C syntax

DBIResult DBIFN DbiReadBlock (hCursor, piRecords, pBuf);

Delphi syntax

function DbiReadBlock (hCursor: hDBICur; var iRecords: Longint; pBuf: Pointer): DBIResult stdcall;

Description

DbiReadBlock reads a specified number of records (starting from the current position of the cursor) into a buffer.

Parameters

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

piRecords Type: pUINT32 (Input/Output)
On input, specifies the number of records to read. On output, pointer to the client variable that receives the number of actual records that were read.

pBuf Type: pBYTE (Output)
Pointer to the client buffer that receives the record data.

Usage

This function is equivalent to doing a loop with DbiGetNextRecord for the specified number in piRecords, though it can be considered significantly faster than a DbiGetNextRecord loop.

If filters are active, DbiReadBlock reads only the records that meet filter criteria; all others are skipped. The records are not locked. The number of records read may differ from the number of records requested due to conditions such as end of table.

DbiReadBlock can access data in blocks larger than 64Kb, depending on the size you allocate for the buffer.

Completion state

The variable, piRecords, contains the number of actual records read after the function completes. The cursor position is updated according to the actual number of records read.

DbiResult	Meaning
DBIERR_NONE	The block of records was successfully read.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL, or piRecords is NULL, or pBuf is NULL.
DBIERR_EOF	An attempt was made to read beyond the end of the file. The cursor is positioned in the crack at the end of the file. piRecords contains the number of records, if any, that were read before the end of file was reached.