FirebirdSQL logo
 FUNCTIONPACKAGE 

DECLARE EXTERNAL FUNCTION Input Parameters

The input parameters of the function follow the name of the function and are separated with commas.Each parameter has an SQL data type specified for it.Arrays cannot be used as function parameters.In addition to the SQL types, the CSTRING type is available for specifying a null-terminated string with a maximum length of LENGTH bytes.There are several mechanisms for passing a parameter from the Firebird engine to an external function, each of these mechanisms will be discussed below.

By default, input parameters are passed by reference.There is no separate clause to explicitly indicate that parameters are passed by reference.

When passing a NULL value by reference, it is converted to the equivalent of zero, for example, a number ‘0’ or an empty string (“''”).If the keyword NULL is specified after a parameter, then with passing a NULL values, the null pointer will be passed to the external function.

Note

Declaring a function with the NULL keyword does not guarantee that the function will correctly handle a NULL input parameter.Any function must be written or rewritten to correctly handle NULL values.Always use the function declaration as provided by its developer.

If BY DESCRIPTOR is specified, then the input parameter is passed by descriptor.In this case, the UDF parameter will receive a pointer to an internal structure known as a descriptor.The descriptor contains information about the data type, subtype, precision, character set and collation, scale, a pointer to the data itself and some flags, including the NULL indicator.This declaration only works if the external function is written using a handle.

Warning

When passing a function parameter by descriptor, the passed value is not cast to the declared data type.

The BY SCALAR_ARRAY clause is used when passing arrays as input parameters.Unlike other types, you cannot return an array from a UDF.

Clauses and Keywords

RETURNS clause

(Required) specifies the output parameter returned by the function.A function is scalar, it returns one value (output parameter).The output parameter can be of any SQL type (except an array or an array element) or a null-terminated string (CSTRING).The output parameter can be passed by reference (the default), by descriptor or by value.If the BY DESCRIPTOR clause is specified, the output parameter is passed by descriptor.If the BY VALUE clause is specified, the output parameter is passed by value.

PARAMETER keyword

specifies that the function returns the value from the parameter under number param_num.It is necessary if you need to return a value of data type BLOB.

FREE_IT keyword

means that the memory allocated for storing the return value will be freed after the function is executed.It is used only if the memory was allocated dynamically in the UDF.In such a UDF, the memory must be allocated with the help of the ib_util_malloc function from the ib_util module, a requirement for compatibility with the functions used in Firebird code and in the code of the shipped UDF modules, for allocating and freeing memory.

ENTRY_POINT clause

specifies the name of the entry point (the name of the imported function), as exported from the module.

MODULE_NAME clause

defines the name of the module where the exported function is located.The link to the module should not be the full path and extension of the file, if that can be avoided.If the module is located in the default location (in the ../UDF subdirectory of the Firebird server root) or in a location explicitly configured in firebird.conf, it makes it easier to move the database between different platforms.The UDFAccess parameter in the firebird.conf file allows access restrictions to external functions modules to be configured.

Any user connected to the database can declare an external function (UDF).