Declaring a UDF to a Database

From InterBase

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 [data_type ;
| CSTRING (int) | DESCRIPTOR [, data_type | CSTRING (int) ...] DESCRIPTOR]
RETURNS {data_type [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.

<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.

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

Advance To:

Retrieved from "https://docwiki.embarcadero.com/InterBase/2020/e/index.php?title=Declaring_a_UDF_to_a_Database&oldid=26946"