Writing a UDF
Go Up to Writing a Function Module
Contents
In the C language, a UDF is written like any standard function. The UDF can require up to ten input parameters, and can return only a single C data value. A source code module can define one or more functions and can use typedefs defined in the InterBase ibase.h header file. You must then include ibase.h when you compile.
Specifying Parameters
A UDF can accept up to ten parameters corresponding to any InterBase data type. Array elements cannot be passed as parameters. If a UDF returns a Blob, the number of input parameters is restricted to nine. All parameters are passed to the UDF by reference.
Programming language data types specified as parameters must be capable of handling corresponding InterBase data types. For example, the C function declaration for FN_ABS() accepts one parameter of type double. The expectation is that when FN_ABS() is called, it will be passed a data type of DOUBLE PRECISION by InterBase.
You can use a descriptor parameter to ensure that the InterBase server passes all of the information it has about a particular data type to the function. A descriptor parameter assists the server in probing the data type to see if any of its values are SQL NULL. For more information about the DESCRIPTOR parameter, see Defining a Sample UDF with a Descriptor Parameter.
UDFs that accept Blob parameters require special data structure for processing. A Blob is passed by reference to a Blob UDF structure. For more information about the Blob UDF structure, see Writing a Blob UDF.
Specifying a Return Value
A UDF can return values that can be translated into any InterBase data type, including a Blob, but it cannot return arrays of data types. For example, the C function declaration for FN_ABS() returns a value of type double, which corresponds to the InterBase DOUBLE PRECISION data type.
By default, return values are passed by reference. Numeric values can be returned by reference or by value. To return a numeric parameter by value, include the optional BY VALUE keyword after the return value when declaring a UDF to a database.
A UDF that returns a Blob does not actually define a return value. Instead, a pointer to a structure describing the Blob to return must be passed as the last input parameter to the UDF. See Declaring a Blob UDF.
A parameter passed as a descriptor cannot be used as a return type. This action will throw an error. For more information about the DESCRIPTOR parameter, see Defining a Sample UDF with a Descriptor Parameter.
UDF Calling Conventions
The calling convention determines how a function is called and how the parameters are passed. The called function must match the calling convention of the caller function. InterBase uses the CDECL calling convention, so all UDFs must use the same calling convention.
Note that the situation is different for calls to APIs. On UNIX, InterBase uses CDECL for all API calls. On Windows platforms InterBase uses STDCALL for all functions that have a fixed number of arguments and CDECL for functions that have a variable number of arguments. See “Programming with the InterBase API” in the API Guide for a list of these functions.
UDF Character Data Types
UDFs are written in a host language and therefore take host-language data types for both their parameters and their return values. However, when a UDF is declared, InterBase must translate them to SQL data types or to a CSTRING type of a specified maximum byte length. CSTRING is used to translate parameters of CHAR and VARCHAR data types into a null-terminated C string for processing, and to return a variable-length, null-terminated C string to InterBase for automatic conversion to CHAR or VARCHAR.
When you declare a UDF that returns a C string, CHAR or VARCHAR, you must include the FREE_IT keyword in the declaration in order to free the memory used by the return value.