Programming Filter Function Actions (Embedded SQL Guide)

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:

Testing the Function Return Value