Programming Filter Function Actions (Embedded SQL Guide)

From InterBase
Jump to: navigation, search

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


When an application performs a Blob access operation, InterBase passes a corresponding action message to the filter function by way of the <action> parameter. There are eight possible actions, each of which results from a particular access operation. The following list of action macro definitions are declared in the ibase.h file:

#define isc_blob_filter_open 0
#define isc_blob_filter_get_segment 1
#define isc_blob_filter_close 2
#define isc_blob_filter_create 3
#define isc_blob_filter_put_segment 4
#define isc_blob_filter_alloc 5
#define isc_blob_filter_free 6
#define isc_blob_filter_seek 7

The following table describes the Blob access operation that corresponds to each action:

Blob access operations
Action Invoked when … Use to …

isc_blob_filter_open

Application opens a Blob READ cursor.

Set the information fields of the Blob control structure.

Perform initialization tasks, such as allocating memory or opening temporary files.

Set the status variable, if necessary. The value of the status variable becomes the return value of the filter function.

isc_blob_filter_get_segment

Application executes a Blob FETCH statement.

Set the ctl_buffer and ctl_segment_length fields of the Blob control structure to contain a worth of a segment of translated data on the return of the filter function.

Perform the data translation if the filter processes the Blob segment-by-segment.

Set the status variable. The value of the status variable becomes the return value of the filter function.

isc_blob_filter_close

Application closes a Blob cursor.

Perform exit tasks, such as freeing allocated memory, closing, or removing temporary files.

isc_blob_filter_create

Application opens a Blob INSERT cursor.

Set the information fields of the Blob control structure.

Perform initialization tasks, such as allocating memory or opening temporary files.

Set the status variable, if necessary. The value of the status variable becomes the return value of the filter function.

isc_blob_filter_put_segment

Application executes a Blob INSERT statement.

Perform the data translation on the segment data passed in through the Blob control structure.

Write the segment data to the database. If the translation process changes the segment length, the new value must be reflected in the values passed to the writing function.

Set the status variable. The value of the status variable becomes the return value of the filter function.

isc_blob_filter_alloc

InterBase initializes filter processing; not a result of a particular application action.

Set the information fields of the Blob control structure.

Perform initialization tasks, such as allocating memory or opening temporary files.

Set the status variable, if necessary. The value of the status variable becomes the return value of the filter function.

isc_blob_filter_free

InterBase ends filter processing; not a result of a particular application action.

Perform exit tasks, such as freeing allocated memory, closing, or removing temporary files.

isc_blob_filter_seek

Reserved for internal filter use; not used by external filters.

Tip: Store resource pointers, such as memory pointers and file handles created by the isc_blob_filter_open handler, in the ctl_data field of the isc_blob_ctl Blob control structure. Then, the next time the filter function is called, the resource pointers are still available.

Advance To: