Defining the Blob Control Structure (Embedded SQL Guide)

From InterBase

Go Up to Defining the Filter Function (Embedded SQL Guide)


The Blob control structure, isc_blob_ctl, provides the fundamental method of data exchange between InterBase and a filter. The declaration for the isc_blob_ctl control structure is in the InterBase include file, ibase.h.

The isc_blob_ctl structure is used in two ways:

  1. When the application performs a Blob access operation, InterBase calls the filter function and passes it an instance of isc_blob_ctl.
  2. Internal filter functions can pass an instance of isc_blob_ctl to internal InterBase access routines.

In either case, the purpose of certain isc_blob_ctl fields depends on the action being performed.

For example, when an application attempts a Blob INSERT, InterBase passes an isc_blob_filter_put_segment action to the filter function. The filter function passes an instance of the control structure to InterBase. The ctl_buffer of the structure contains the segment data to be written, as specified by the application in its Blob INSERT statement. Because the buffer contains information to pass 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 write to the database.

In a different case, for instance when an application attempts a FETCH operation, the case of an isc_blob_filter_get_segment action should include instructions for filling ctl_buffer with segment data from the database to return to the application. 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 structure 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 sub-type. 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 sub-type. 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 to by ctl_buffer, which is used to store the retrieved Blob data.

ctl_segment_length

Length of the current segment. This field is not used for isc_blob_filter_put_segment.

For isc_blob_filter_get_segment, the 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. Reserved for future enhancement.

  • ctl_bpb

Pointer to a Blob parameter buffer. Reserved for future enhancement.

  • ctl_buffer

Pointer to a segment buffer. For isc_blob_filter_put_segment, field is an in field that contains the segment data.

For isc_blob_filter_get_segment, the field is an OUT field the filter function fills with segment data for return to the application.

ctl_max_segment

Length of longest segment in the Blob. Initial value is 0. The filter function sets this field. This field is informational only.

ctl_number_segments

Total number of segments in the Blob. Initial value is 0. The filter function sets this field. This field is informational only.

ctl_total_length

Total length of the Blob. Initial value is 0. The filter function sets this field. This field is informational only.

  • ctl_status

Pointer to the 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)

Setting control structure information field values

The isc_blob_ctl structure contains three fields that store information about the Blob currently being accessed: ctl_max_segment, ctl_number_segments, and ­ctl_total_length.

You should attempt to maintain correct values for these fields in the filter function, whenever possible. Depending on the purpose of the filter, maintaining correct values for the fields is not always possible. For example, a filter that compresses data on a segment-by-segment basis cannot determine the size of ­ctl_max_segment until it processes all segments.

These fields are informational only. InterBase does not use the values of these fields in internal processing.

Advance To:

Retrieved from "https://docwiki.embarcadero.com/InterBase/2020/e/index.php?title=Defining_the_Blob_Control_Structure_(Embedded_SQL_Guide)&oldid=31206"