Firebird 2.5 Language ReferenceFirebird 2.5 Language ReferenceData Definition (DDL) Statements → FILTER
Firebird Firebird Prev: EXTERNAL FUNCTIONFirebird 2.5 Language ReferenceUp: Data Definition (DDL) StatementsNext: SEQUENCE (GENERATOR)

FILTER

Table of Contents

DECLARE FILTER
DROP FILTER

A BLOB FILTER filter is a database object that is actually a special type of external function, with the sole purpose of taking a BLOB object in one format and converting it to a BLOB object in another format. The formats of the BLOB objects are specifed with user-defined BLOB subtypes.

External functions for converting BLOB types are stored in dynamic libraries and loaded when necessary.

For more details on BLOB subtypes, see Binary Data Types.

DECLARE FILTER

Used for:  Declaring a BLOB filter to the database

Available in: DSQL, ESQL

Syntax: 

DECLARE FILTER filtername
INPUT_TYPE <sub_type> OUTPUT_TYPE <sub_type>
ENTRY_POINT 'function_name' MODULE_NAME 'library_name';

<sub_type> ::= number | <mnemonic>

<mnemonic> ::= binary | text | blr | acl | ranges
             | summary | format | transaction_description
             | external_file_description | user_defined
        

Table 5.30. DECLARE FILTER Statement Parameters

Parameter Description
filtername Filter name in the database. It may consist of up to 31 characters. It need not be the same name as the name exported from the filter library via ENTRY_POINT.
sub_type BLOB subtype
number BLOB SUB_TYPE number (must be negative)
mnemonic BLOB SUB_TYPE mnemonic name
function_name The exported name (entry point) of the function
library_name The name of the module where the filter is located
user_defined User-define BLOB SUB_TYPE mnemonic name


The DECLARE FILTER statement makes a BLOB filter available to the database. The name of the BLOB filter must be unique among the names of BLOB filters.

Specifying the Subtypes

The subtypes can be specified as the subtype number or as the subtype mnemonic name. Custom subtypes must be represented by negative numbers (from -1 to -32,768). An attempt to declare more than one BLOB filter with the same combination of the input and output types will fail with an error.

INPUT_TYPE:  clause defining the BLOB subtype of the object to be converted

OUTPUT_TYPE:  clause definimg the BLOB subtype of the object to be created.

[Note] Note

Mnemonic names can be defined for custom BLOB subtypes and inserted manually into the system table RDB$TYPES system table:

       INSERT INTO RDB$TYPES (RDB$FIELD_NAME, RDB$TYPE, RDB$TYPE_NAME)
       VALUES ('RDB$FIELD_SUB_TYPE', -33, 'MIDI');
          

After the transaction is confirmed, the mnemonic names can be used in declarations when you create new filters.

The value of the column RDB$FIELD_NAME must always be 'RDB$FIELD_SUB_TYPE'. If mnemonic names in upper case, they can be used case-insensitively and without quotation marks when a filter is declared.

Warning:  From Firebird 3 onward, the system tables will no longer be writable by users.

Parameters

ENTRY_POINT:  clause defining the name of the entry point (the name of the imported function) in the module.

MODULE_NAME:  The clause defining the name of the module where the exported function is located. By default, modules must be located in the UDF folder of the root directory on the server. The UDFAccess parameter in firebird.conf allows editing of access restrictions to filter libraries.

* * * * * * * * * * * * * * * * * * * * *

 Any user connected to the database can declare a BLOB filter.

Examples: 

  1. Creating a BLOB filter using subtype numbers.
    DECLARE FILTER DESC_FILTER
    INPUT_TYPE 1
    OUTPUT_TYPE -4
    ENTRY_POINT 'desc_filter'
    MODULE_NAME 'FILTERLIB';
                
  2. Creating a BLOB filter using subtype mnemonic names.
    DECLARE FILTER FUNNEL
    INPUT_TYPE blr OUTPUT_TYPE text
    ENTRY_POINT 'blr2asc' MODULE_NAME 'myfilterlib';
                

See also:  DROP FILTER

DROP FILTER

Used for:  Removing a BLOB filter declaration from the database

Available in: DSQL, ESQL

Syntax: 

DROP FILTER filtername;
        

Table 5.31. DROP FILTER Statement Parameter

Parameter Description
filtername Filter name in the database


The DROP FILTER statement removes the declaration of a BLOB filter from the database. Removing a BLOB filter from a database makes it unavailable for use rom that database. The dynamic library where the conversion function is located remains intact and the removal from one database does not affect other databases in which the same BLOB filter is still declared.

 Any user connected to the database can drop a BLOB filter.

Example:  Deleting a BLOB filter.

DROP FILTER DESC_FILTER;
          

See also:  DECLARE FILTER

Prev: EXTERNAL FUNCTIONFirebird 2.5 Language ReferenceUp: Data Definition (DDL) StatementsNext: SEQUENCE (GENERATOR)
Firebird 2.5 Language ReferenceFirebird 2.5 Language ReferenceData Definition (DDL) Statements → FILTER