isc_open_blob2()

From InterBase

Go Up to API Function Reference


Opens an existing Blob for retrieval and optional filtering.

Syntax

 ISC_STATUS isc_open_blob2(
 ISC_STATUS *status_vector,
 isc_db_handle *db_handle,
 isc_tr_handle *trans_handle,
 isc_blob_handle *blob_handle,
 ISC_QUAD *blob_id,
 short bpb_length,
 char *bpb_address);
Parameter Type Description

status_vector

ISC_STATUS *

Pointer to the error status vector

db_handle

isc_db_handle *

Pointer to a database handle set by a previous call to ­isc_attach_database().

db_handle returns an error in status_vector if it is NULL.

trans_handle

isc_tr_handle *

Pointer to a transaction handle whose value has been set by a previous isc_start_transaction() call; trans_handle returns an error if NULL.

blob_handle

isc_blob_handle *

Pointer to the Blob handle, which must be NULL when you make this call.

blob_id

ISC_QUAD *

Pointer to the 64-bit system-defined Blob ID, which is stored in a field in the table and points to the first segment of the Blob or to a page of pointers to Blob fragments.

bpb_length

short

Length of the Blob parameter buffer (BPB)

bpb_address

char *

Pointer to the BPB

Description

isc_open_blob2() opens an existing Blob for retrieval and optional filtering from one Blob subtype to another.

Input and output Blob filter types are passed to isc_open_blob2() as subtype information in a previously populated BPB, pointed to by bpb_address. If Blob filters are not needed or cannot be used, a BPB is not needed; pass 0 for bpb_length and NULL for bpb_address.

The blob_id identifies which particular Blob is to be opened. This blob_id is set by a sequence of DSQL function calls.

On success, isc_open_blob2() assigns a unique ID to blob_handle. Subsequent API calls use this handle to identify the Blob against which they operate.

After a blob is opened, its data can be read by a sequence of calls to i­sc_get_segment().

When finished accessing the Blob, close it with isc_close_blob().

For more information about opening a Blob for retrieval and optional filtering, see Working with Blob Data.

Example

The following fragment is excerpted from the example file, api9.c. The example program displays job descriptions that are passed through a filter.

while ((fetch_stat = isc_dsql_fetch(status, &stmt, 1, sqlda)) == 0) {
printf("\nJOB CODE: %5s GRADE: %d", job_code, job_grade);
printf(" COUNTRY: %-20s\n\n", job_country);
/* Open the blob with the fetched blob_id. */
isc_open_blob2(status, &DB, &trans, &blob_handle, &blob_id, 9, bpb);
if (status[0] == 1 && status[1]) {
isc_print_status(status);
return(1);
}
}

Return value

isc_open_blob2() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code.

To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

See Also

Advance To: