FILTER

Table of Contents

DECLARE FILTER

Tip

Find a more recent version at Firebird 5.0 Language Reference: FILTER

DECLARE FILTER

Available in: DSQL, ESQL

Changed in: 2.0

Description: Makes a BLOB filter available to the database.

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
In Firebird 2 and up, no two BLOB filters in a database may have the same combination of input and output type. Declaring a filter with an already existing input-output type combination will fail. Restoring pre-2.0 databases that contain such “duplicate” filters will also fail.

The possibility to indicate the BLOB types with their mnemonics instead of numbers was added in Firebird 2. The binary mnemonic for subtype 0 was also added in Firebird 2. The predefined mnemonics are case-insensitive.

Example:

declare filter Funnel
  input_type blr output_type text
  entry_point 'blr2asc' module_name 'myfilterlib'

User-defined mnemonics: If you want to define mnemonics for your own BLOB subtypes, you can add them to the RDB$TYPES system table as shown below. Once committed, the mnemonics can be used in subsequent filter declarations.

insert into rdb$types (rdb$field_name, rdb$type, rdb$type_name)
  values ('RDB$FIELD_SUB_TYPE', -33, 'MIDI')

The value for rdb$field_name must always be 'RDB$FIELD_SUB_TYPE'. If you define your mnemonics in all-uppercase, you can use them case-insensitively and unquoted in your filter declarations.