Declaring a UDF to a Database

Go Up to Working with UDFs and Blob Filters

Once a UDF has been written and compiled into a library, you must use the DECLARE EXTERNAL FUNCTION statement to declare each function to each database where you want to use it. Each function in a library must be declared separately, but needs to be declared only once to each database.

Declaring a UDF to a database informs the database about its location and properties:

• The UDF name as it will be used in embedded SQL statements
• The number and data types of its arguments
• The return data type
• The name of the function as it exists in the UDF module or library
• The name of the library that contains the UDF

You can use isql, IBConsole, or a script to declare your UDFs.

You can use the following syntax to execute a DECLARE EXTERNAL FUNCTION statement:

DECLARE EXTERNAL FUNCTION name [datatype ;
| CSTRING (int) | DESCRIPTOR [, datatype | CSTRING (int) ...] DESCRIPTOR]
RETURNS {datatype [BY VALUE] | CSTRING (int) | PARAMETER n}
[FREE_IT]
ENTRY_POINT 'entryname'
MODULE_NAME 'modulename';

The following describes the arguments you can append to a DECLARE EXTERNAL FUNCTION statement.

Arguments to DECLARE EXTERNAL FUNCTION

Argument	Description
<name>	Name of the UDF to use in SQL statements; can be different from the name of the function specified after the ­ENTRY_POINT keyword.
<datatype>	Data type of an input or return parameter All input parameters are passed to a UDF by reference. Return parameters can be passed by value. Cannot be an array element.
CSTRING (<int>)	Specifies a UDF that returns a null-terminated string <int> bytes in length.
DESCRIPTOR	Ensures that the InterBase server passes all the information it has about a particular data type to the function via the Descriptor control structure.
RETURNS	Specifies the return value of a function.
BY VALUE	Specifies that a return value should be passed by value rather than by reference.
PARAMETER <n>	Specifies that the <n>th input parameter is to be returned. Used when the return data type is BLOB.
FREE_IT	Frees memory of the return value after the UDF finishes running. Use only if the memory is allocated dynamically in the UDF. See also the UDF chapter in the Developer's Guide.
'<entryname>'	Quoted string specifying the name of the UDF in the source code and as stored in the UDF library.
'<modulename>'	Quoted specification identifying the library that contains the UDF. The library must reside on the same machine as the InterBase server. On any platform, the module can be referenced with no path name if it is in <<InterBase_home>>/UDF or <<InterBase_home>>/intl If the library is in a directory other than <<InterBase_home>>/UDF or <<InterBase_home>>./intl, you must specify its location in InterBase configuration file (ibconfig) using the EXTERNAL_FUNCTION_DIRECTORY parameter. It is not necessary to supply the extension to the module name.

Topics

• Defining a Sample UDF with a Descriptor Parameter
• Declaring UDFs with FREE_IT
• UDF Library Placement