isc_blob_lookup_desc2()

Go Up to API Function Reference

Determines the subtype, character set, and segment size of a Blob, given a table name and Blob column name. For more information about Blob descriptors, see Working with Blob Data.

Syntax

 ISC_STATUS isc_blob_lookup_desc(
 ISC_STATUS *status_vector,
 isc_db_handle **db_handle,
 isc_tr_handle **trans_handle,
 unsigned char *table_name,
 unsigned char *column_name,
 ISC_BLOB_DESC_V2 *desc,
 unsigned char *global);

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`.
`table_name`	`unsigned char *`	Name of the table containing the Blob column
`column_name`	`unsigned char *`	Name of the Blob column
`desc`	`ISC_BLOB_DESC_V2` `*`	Pointer to the Blob descriptor to which the function returns information.
`global`	`unsigned char *`	Global column name, returned by this function.

Description

isc_blob_lookup_desc2() uses the system tables of a database to determine the subtype, character set, and segment size of a Blob given a table name and Blob column name.

isc_blob_lookup_desc2() and three related functions, isc_blob_default_desc2(), isc_blob_gen_bpb2(), and isc_blob_set_desc2() provide dynamic access to Blob information. In particular, you can use these functions to define and access information about Blob data for filtering purposes, such as character set information for text Blob data, and subtype information for text and non-text Blob data.

Note: The ISC_BLOB_DESC_V2 structure supports long metadata names of length METADATALENGTH. The older ISC_BLOB_DESC structure supports only metadata names of 32 bytes or less.

isc_blob_lookup_desc2() stores the requested information about the Blob into the desc Blob descriptor structure. The following table describes the desc structure:

Blob descriptor fields
Parameter	Type	Description
blob_desc_version	short	Set to `BLOB_DESC_CURRENT_VERSION`
`blob_desc_subtype`	`short`	Subtype of the Blob filter
`blob_desc_charset`	`short`	Character set being used
`blob_desc_segment_size`	`short`	Blob segment size
`blob_desc_field_name` [`METADATALENGTH`]	`char`	Array containing the name of the Blob column
`blob_desc_relation_name` [`METADATALENGTH`]	`char`	Array containing the name of the table in which the Blob is stored.

The blob_desc_version field is set to BLB_DESC_CURRENT_VERSION by isc_blob_default_desc2(), isc_blob_lookup_desc2(), and isc_blob_set_desc2(). isc_blob_gen_bpb2() requires that the user set the blob_desc_version to BLB_DESC_CURRENT_VERSION explicitly.

Example

The following fragment retrieves information into a Blob descriptor:

isc_blob_lookup_desc2(status, &db_handle, &tr_handle, &relation_name,
f&field_name, &desc, &global);

Return value

isc_blob_lookup_desc2() 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.

Advance To:

isc_blob_set_desc()