Defining the Blob Control Structure

Go Up to Writing an External Blob Filter

The isc_blob_ctl Blob control structure provides the fundamental method of data exchange between InterBase and a filter.

The Blob control structure is defined as a typedef, isc_blob_ctl, in ibase.h, as follows:

typedef struct isc_blob_ctl {ISC_STATUS (*ctl_source)();
/* Internal InterBase Blob access routine. */
struct isc_blob_ctl *ctl_source_handle;
/* Instance of isc_blob_ctl to pass to internal
 * InterBase Blob access routine. */
short ctl_to_sub_type; /* Target subtype. */
short ctl_from_sub_type; /* Source subtype. */
unsigned short ctl_buffer_length; /* Length of ctl_buffer. */
unsigned short ctl_segment_length; /* Length of current segment. */
unsigned short ctl_bpb_length; /* Blob parameter buffer length. */
char *ctl_bpb; /* Pointer to Blob parameter buffer. */
unsigned char *ctl_buffer; /* Pointer to segment buffer. */
ISC_LONG ctl_max_segment; /* Length of longest Blob segment. */
ISC_LONG ctl_number_segments; /* Total number of segments. */
ISC_LONG ctl_total_length; /* Total length of Blob. */
ISC_STATUS *ctl_status; /* Pointer to status vector. */
long ctl_data[8]; /* Application-specific data. */
} *ISC_Blob_CTL;

The purpose of certain isc_blob_ctl fields depends on the action being performed.

For example, when an application calls the isc_put_segment() API function, InterBase passes an isc_blob_filter_put_segment action to the filter function. The buffer pointed to by the ctl_buffer field of the control structure, passed to the filter function, contains the segment data to be written, as specified by the application in its call to isc_put_segment(). Because the buffer contains information passed into the filter function, it is called an IN field. The filter function should include instructions in the case statement under the isc_blob_filter_put_segment case for performing the filtering and then passing the data on for writing to the database. This can be done by calling the *ctl_source internal InterBase Blob access routine. For more information about ctl_source, see the Embedded SQL Guide.

On the other hand, when an application calls the isc_get_segment() API function, the buffer pointed to by ctl_buffer in the control structure passed to a filter function is empty. In this situation, InterBase passes an isc_blob_filter_get_segment action to the filter function. The filter function isc_blob_filter_get_segment action handling should include instructions for filling ctl_buffer with segment data from the database to return to the application. This can be done by calling the *ctl_source internal InterBase Blob access routine. In this case, because the buffer is used for filter function output, it is called an OUT field.

The following table describes each of the fields in the isc_blob_ctl Blob control structure, and whether they are used for filter function input (IN), or output (OUT).

`isc_blob_ctl` Sructure Field Descriptions
Field name	Description
`(*ctl_source)`()	Pointer to the internal InterBase Blob access routine. (IN)
`*ctl_source_handle`	Pointer to an instance of `isc_blob_ctl` to be passed to the internal InterBase Blob access routine. (IN)
`ctl_to_sub_type`	Target subtype: information field provided to support multi-purpose filters that can perform more than one kind of translation; this field and the next one enable such a filter to decide which translation to perform. (IN)
`ctl_from_sub_type`	Source subtype: information field provided to support multi-purpose filters that can perform more than one kind of translation; this field and the previous one enable such a filter to decide which translation to perform. (IN)
`ctl_buffer_length`	For `isc_blob_filter_put_segment`, field is an IN field that contains the length of the segment data contained in `ctl_buffer`. For `isc_blob_filter_get_segment`, field is an IN field set to the size of the buffer pointed at by `ctl_buffer`, which is used to store the retrieved Blob data.
`ctl_segment_length`	Length of current segment. For `isc_blob_filter_put_segment`, field is not used. For `isc_blob_filter_get_segment`, field is an OUT field set to the size of the retrieved segment (or partial segment, in the case when the buffer length `ctl_buffer_length` is less than the actual segment length).
`ctl_bpb_length`	Length of the Blob parameter buffer.
`*ctl_bpb`	Pointer to the Blob parameter buffer.
`*ctl_buffer`	Pointer to segment buffer. For `isc_blob_filter_put_segment`, field is an IN field that contains the segment data. For `isc_blob_filter_get_segment`, field is an OUT field the filter function fills with segment data for return to the application.
`ctl_max_segment`	Length, in bytes, of the longest segment in the Blob. Initial value is 0. The filter function sets this field. This field is information only.
`ctl_number_segments`	Total number of segments in the Blob. Initial value is 0. The filter function sets this field. This field is information only.
`ctl_total_length`	Total length, in bytes, of the Blob. Initial value is 0. The filter function sets this field. This field is information only.
`*ctl_status`	Pointer to InterBase status vector. (`OUT`)
`ctl_data [8]`	8-element array of application-specific data. Use this field to store resource pointers, such as memory pointers and file handles created by the `isc_blob_filter_open` handler, for example. Then, the next time the filter function is called, the resource pointers will be available for use. (IN/OUT)

Advance To:

Programming Filter Function Actions