DECLARE EXTERNAL FUNCTION

Go Up to Statement and Function Reference (Language Reference Guide)

Declares an existing user-defined function (UDF) to a database. Available in gpre, DSQL, and isql.

DECLARE EXTERNAL FUNCTION name [data_type 
| CSTRING (<int>) [, data_type | CSTRING (<int>) …]]
RETURNS {data_type [BY VALUE] | CSTRING (<int>) | PARAMETER <n}> [FREE_IT]
ENTRY_POINT 'entryname' MODULE_NAME 'modulename';

Important:
In SQL statements passed to DSQL, omit the terminating semicolon. In embedded applications written in C and C++, and in isql, the semicolon is a terminating symbol for the statement, so it must be included.

Note:
Whenever a UDF returns a value by reference to dynamically allocated memory, you must declare it using the FREE_IT keyword in order to free the allocated memory.

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.
<data_type>	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.
`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 Error Codes and Messages.
'<entryname>'	Quoted string that contains the function name as it is stored in the library that is referenced by the UDF.
'<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 configuration file (`ibconfig`) of InterBase using the `EXTERNAL_FUNCTION_DIRECTORY` parameter. It is not necessary to supply the extension to the module name.

Description: DECLARE EXTERNAL FUNCTION provides information about a UDF to a database: where to find it, its name, the input parameters it requires, and the single value it returns. Each UDF in a library must be declared once to each database where it will be used. As long as the entry point and module name do not change, there is no need to redeclare a UDF, even if the function itself is modified.

entryname is the actual name of the function as stored in the UDF library. It does not have to match the name of the UDF as stored in the database.

Important:
The module name does not need to include a path. However, the module must either be placed in <<InterBase_home>>/UDF or be listed in the InterBase configuration file using the EXTERNAL_FUNCTION_DIRECTORY parameter.

To specify a location for UDF libraries in the InterBase configuration file, enter a line of the following form for Windows platforms:

EXTERNAL_FUNCTION_DIRECTORY D:\Mylibraries\InterBase

For UNIX, the line does not include a drive letter:

EXTERNAL_FUNCTION_DIRECTORY \Mylibraries\InterBase

The InterBase configuration file is called ibconfig on all platforms.

Examples: The following isql statement declares the TOPS() UDF to a database:

DECLARE EXTERNAL FUNCTION TOPS
CHAR(256), INTEGER, BLOB
RETURNS INTEGER BY VALUE
ENTRY_POINT 'te1' MODULE_NAME 'tm1';

This example does not need the FREE_IT keyword because only cstrings, CHAR, and VARCHAR return types require memory allocation.

The next example declares the LOWERS() UDF and frees the memory allocated for the return value:

DECLARE EXTERNAL FUNCTION LOWERS VARCHAR(256)
RETURNS CSTRING(256) FREE_IT
ENTRY POINT 'fn_lower' MODULE_NAME 'udflib';

Advance To:

DECLARE FILTER

DECLARE EXTERNAL FUNCTION

See Also

Advance To: