Using an External Blob Filter
Go Up to Filtering Blob Data (Embedded SQL Guide)
Contents
Unlike the standard InterBase filters that convert between sub-type 0 and sub-type 1, an external Blob filter is generally part of a library of routines you create and link to your application. To use an external filter, you must first write it, compile and link it, then declare it to the database that contains the Blob data you want processed.
Declaring an External Filter to the Database
To declare an external filter to a database, use the DECLARE FILTER statement. For example, the following statement declares the filter, SAMPLE:
EXEC SQL DECLARE FILTER SAMPLE INPUT_TYPE -1 OUTPUT_TYPE -2 ENTRY_POINT 'FilterFunction' MODULE_NAME 'filter.dll';
In the example, the input sub-type of the filter is defined as -1 and its output sub-type as -2. In this example, INPUT_TYPE specifies lowercase text and OUTPUT_TYPE specifies uppercase text. The purpose of filter, SAMPLE, therefore, is to translate Blob data from lowercase text to uppercase text.
The ENTRY_POINT and MODULE_NAME parameters specify the external routine that InterBase calls when the filter is invoked. The MODULE_NAME parameter specifies filter.dll, the dynamic link library containing the executable code of the filter. The ENTRY_POINT parameter specifies the entry point into the DLL. The example shows only a simple file name. It is good practice to specify a fully-qualified path name, since users of your application need to load the file.
Using a Filter to Read and Write Blob Data
The following illustration shows the default behavior of the SAMPLE filter that translates from lowercase text to uppercase text.
Similarly, when reading data, the SAMPLE filter can easily read Blob data of sub-type -2, and translate it to data of sub-type -1.
Invoking a Filter in an Application
To invoke a filter in an application, use the FILTER option when declaring a Blob cursor. Then, when the application performs operations using the cursor, InterBase automatically invokes the filter.
For example, the following INSERT cursor definition specifies that the filter, SAMPLE, is to be used in any operations involving the cursor, BCINS1:
EXEC SQL DECLARE BCINS1 CURSOR FOR INSERT Blob Blob1 INTO TABLE1 FILTER FROM -1 TO -2;
When InterBase processes this declaration, it searches a list of filters defined in the current database for a filter with matching FROM and TO sub-types. If such a filter exists, InterBase invokes it during Blob operations that use the cursor, BCINS1. If InterBase cannot locate a filter with matching FROM and TO sub-types, it returns an error to the application.