isc_create_blob2()
Go Up to API Function Reference
Creates and opens the Blob for write access, and optionally specifies the filters to be used to translate the Blob from one subtype to another.
Syntax
ISC_STATUS isc_create_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 |
|---|---|---|
|
|
|
Pointer to the error status vector |
|
|
|
Pointer to a database handle set by a previous call to
|
|
|
|
Pointer to the handle of the transaction in which you want the Blob to be created. |
|
|
|
Pointer to the Blob handle |
|
|
|
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. |
|
|
|
Length of the Blob parameter buffer (BPB) |
|
|
|
Pointer to the BPB |
Description
isc_create_blob2() creates a context for storing a Blob, opens a Blob for write access, and optionally specifies the filters used to translate from one Blob format to another. Subsequent calls to isc_put_segment() write data from an application buffer to the Blob.
If a Blob filter is used, it is called for each segment written to the Blob. InterBase selects the filter to be used based on the source and target subtypes specified in a previously populated Blob parameter buffer (BPB), pointed to by bpb_address.
If a Blob filter is not needed or cannot be used, a BPB is not needed; pass 0 for bpb_length and NULL for bpb_address.
The Blob handle pointed to by blob_handle must be zero when isc_create_blob2() is called. To reuse blob_handle, close the Blob with a call to isc_close_blob() to zero out the handle before calling isc_create_blob2().
On success, isc_create_blob2() assigns a unique ID to blob_handle, and a Blob identifier to blob_id. Subsequent API calls require one or both of these to identify the Blob against which they operate.
After a blob is created, data can be written to it by a sequence of calls to isc_put_segment(). When finished writing to the Blob, close it with isc_close_blob().
When you create a Blob, it is essentially an “orphan” until you assign its blob_id to a particular Blob column of a particular row of a table. You do this, after closing the Blob, by using DSQL to execute either an INSERT statement to insert a new row containing the Blob (and any other columns desired), or an UPDATE statement to replace an existing Blob with the new one.
For more information about BPBs and Blob filters, see Working with Blob Data.
Example
The following fragment declares a BPB, populates it with filter information, then creates a Blob and passes the BPB:
isc_blob_handle blob_handle; /* declare at beginning */
ISC_QUAD blob_id; /* declare at beginning */
char bpb[] = {
isc_bpb_version1,
isc_bpb_target_type,
1, /* # bytes that follow which specify target subtype */
1, /* target subtype (TEXT) */
isc_bpb_source_type,
1, /* # bytes that follow which specify source subtype */
-4, /* source subtype*/
};
. . .
isc_create_blob2(status_vector, &db_handle, &tr_handle,
&blob_handle, /* to be filled in by this function */
&blob_id, /* to be filled in by this function */
actual_bpb_length, /* length of BPB data */
& bpb /* Blob parameter buffer */
)
Return value
isc_create_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.