DbiOpenBlob

C syntax

DBIResult DBIFN DbiOpenBlob (hCursor, pRecBuf, iField, eOpenMode);

Delphi syntax

function DbiOpenBlob (hCursor: hDBICur; pRecBuf: Pointer; iField: Word; eOpenMode: DBIOpenMode): DBIResult stdcall;

Description

DbiOpenBlob prepares the cursor's record buffer to access a BLOB field. The BLOB is opened and the BLOB handle is stored in the record buffer, which can then be passed to DbiGetBlob, DbiPutBlob, and other BLOB functions.

Parameters

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

pRecBuf Type: pBYTE (Input)
Pointer to the record buffer.

iField Type: UINT16 (Input)
Specifies the ordinal number of the BLOB field within the record.

eOpenMode Type: DBIOpenMode (Input)
Specifies the BLOB open mode.

If dbiREADWRITE is specified, both the database and the table must be opened in dbiREADWRITE mode.

Usage

DbiOpenBlob opens the BLOB and stores the supplied BLOB handle in pRecBuf so that all or portions of the BLOB field can be retrieved, modified, deleted, or inserted, and the size of the field can be determined. The BLOB field can be opened in either read-only or read-write mode, depending on the value specified in eOpenMode.

DbiOpenBlob must be called prior to calling the BLOB functions DbiGetBlobSize, DbiGetBlob, DbiPutBlob, DbiTruncateBlob, or DbiFreeBlob.

Standard: It is advisable to lock the record before opening the BLOB in read-write mode. This ensures that another client application does not lock the record or update the BLOB, preventing the record from being updated.

SQL: This function is supported by SQL drivers. However, for SQL servers that do not support BLOB handles for random reads and writes, full BLOB support requires uniquely identifiable rows. Most SQL servers limit a single sequential BLOB read to less than the maximum size of a BLOB. In cases with no row uniqueness and without BLOB handles, an entire BLOB may not be available.

Completion state

DbiOpenBlob fails if the client application does not have sufficient rights to access the BLOB field. To close a BLOB field after it has been opened with DbiOpenBlob, a call to DbiFreeBlob must be made.

DbiResult	Meaning
DBIERR_NONE	The BLOB field was successfully opened.
DBIERR_INVALIDHNDL	The specified cursor handle is invalid or NULL.
DBIERR_INVALIDPARAM	The specified record buffer is NULL.
DBIERR_OUTOFRANGE	The specified field number is equal to zero, or is greater than the number of fields in the table.
DBIERR_BLOBOPENED	The specified BLOB field is already open.
DBIERR_NOTABLOB	The specified field number does not correspond to a BLOB field.
DBIERR_OPENBLOBLIMIT	The allowed number of open BLOB handles for the current driver has been exceeded.
DBIERR_TABLEREADONLY	The BLOB cannot be opened in read-write mode; the table is read-only.