`DECLARE EXTERNAL FUNCTION`

affectation

Déclaration d’une fonction définie par l’utilisateur (UDF) dans une base de données.

Disponible en

DSQL, ESQL

Syntaxe

DECLARE EXTERNAL FUNCTION funcname
  [{ <arg_desc_list> | ( <arg_desc_list> ) }]
  RETURNS { <return_value> | ( <return_value> ) }
  ENTRY_POINT 'entry_point' MODULE_NAME 'library_name'

<arg_desc_list> ::=
  <arg_type_decl> [, <arg_type_decl> ...]

<arg_type_decl> ::=
  <udf_data_type> [BY {DESCRIPTOR | SCALAR_ARRAY} | NULL]

<udf_data_type> ::=
    <scalar_datatype>
  | BLOB
  | CSTRING(length) [ CHARACTER SET charset ]

<return_value> ::=
    <udf_data_type> { BY VALUE | BY DESCRIPTOR [FREE_IT] | FREE_IT }
  | PARAMETER param_num

<scalar_datatype> ::=  Voir, par exemple Syntaxe des types de données scalaires

Table 1. Paramètres de l’opérateur `DECLARE EXTERNAL FUNCTION`
Paramètre	Description
funcname	Nom de la fonction externe, pouvant contenir jusqu’à 63 caractères.
entry_point	Nom de la fonction à exporter (point d’entrée).
library_name	Le nom du module dans lequel se trouve la fonction.
sqltype	Le type de données SQL ne peut pas être un tableau ou un élément de tableau.
length	Longueur maximale de la chaîne de caractères .Spécifié en octets.
charset	Encodage de la chaîne de caractères.
param_num	Le numéro du paramètre d’entrée à retourner par la fonction.

L’instruction DECLARE EXTERNAL FUNCTION rend une fonction externe définie par l’utilisateur (UDF) disponible dans la base de données.Les fonctions externes doivent être déclarées dans chaque base de données qui va les utiliser.Il n’est pas nécessaire de déclarer un UDF si vous ne l’utiliserez jamais.

Le nom de la fonction externe doit être unique parmi tous les noms de fonction.Il peut être différent du nom de la fonction spécifié dans l’argument ENTRY_POINT.

Les paramètres d’entrée des fonctions sont énumérés, séparés par des virgules juste après le nom de la fonction.Un type de données SQL est spécifié pour chaque paramètre.

En plus des types SQL, vous pouvez également spécifier le type CSTRING.Dans ce cas, le paramètre est une chaîne terminale nulle d’une longueur maximale de length octets.Il existe plusieurs mécanismes pour passer un paramètre du moteur Firebird à une fonction externe, chacun de ces mécanismes sera considéré séparément.

Par défaut, les paramètres d’entrée sont passés par référence.Il n’y a pas de phrase distincte pour indiquer explicitement qu’un paramètre est transmis par référence.

Si une valeur NULL est passée par référence, elle est convertie en un équivalent nul, comme un 0 ou une chaîne vide.Si un paramètre spécifié est suivi du mot-clé NULL, le fait de passer une valeur NULL fera en sorte qu’elle soit passée à la fonction comme un pointeur NULL.

Note

Notez que déclarer une fonction avec le mot clé NULL ne garantit pas que la fonction traitera correctement un paramètre d’entrée de valeur NULL. Toute fonction doit être écrite ou réécrite pour traiter correctement les valeurs NULL. Consultez et utilisez toujours les déclarations de fonction fournies par son développeur.

Si la clause BY DESCRIPTOR est spécifiée, le paramètre d’entrée est transmis par descripteur, auquel cas le paramètre UDF recevra un pointeur vers une structure interne connue sous le nom de descripteur, portant des informations sur le type de données, le sous-type, la précision, le jeu de caractères et le tri, l’échelle, le pointeur vers les données elles-mêmes et certains drapeaux, y compris un indicateur NULL. Notez que cette déclaration ne fonctionne que si la fonction externe est écrite en utilisant un descripteur.

Warning

Lorsqu’un paramètre de fonction est transmis par un descripteur, la valeur transmise n’est pas convertie dans le type de données déclaré.

La phrase BY SCALAR_ARRAY est utilisée quand on passe des tableaux comme paramètres d’entrée.Contrairement aux autres types, vous ne pouvez pas renvoyer un tableau à partir d’une UDF.

La clause obligatoire RETURNS décrit le paramètre de sortie renvoyé par la fonction.La fonction ne renvoie toujours qu’un seul paramètre.Le paramètre de sortie peut être n’importe quel type SQL (sauf tableau et élément de tableau) ou une chaîne de caractères terminal nul (CSTRING). Le paramètre de sortie peut être transmis par référence, par descripteur ou par valeur.

Par défaut, le paramètre de sortie est passé par référence.Si BY DESCRIPTOR est spécifié, le paramètre de sortie est passé par le descripteur.Si la phrase BY VALUE est spécifiée, le paramètre de sortie est passé par valeur.

Le mot-clé PARAMETER spécifie que la fonction retourne une valeur à partir du numéro de paramètre param_num.Ceci est nécessaire si une valeur de type BLOB doit être retournée.

Le mot-clé FREE_IT signifie que la mémoire allouée pour stocker la valeur de retour sera libérée après la fin de la fonction.S’applique uniquement si cette mémoire dans l’UDF a été allouée dynamiquement.Dans un tel UDF, la mémoire doit être allouée en utilisant la fonction ib_util_malloc du module ib_util.Ceci est nécessaire pour la compatibilité des fonctions d’allocation et de libération de la mémoire utilisées dans le code Firebird et le code UDF.

Le mot-clé ENTRY_POINT spécifie le nom du point d’entrée (nom de la fonction exportée) dans le module.

Le mot-clé MODULE_NAME spécifie le nom du module où réside la fonction exportée.La référence du module peut ne pas inclure le chemin d’accès complet et l’extension du fichier.Cela facilite le transfert de la base de données entre différentes plateformes.Par défaut, les bibliothèques de fonctions utilisateur dynamiques doivent être situées dans le dossier UDF du répertoire racine du serveur.Le UDFAccess dans firebird.conf vous permet de modifier les restrictions d’accès aux bibliothèques de fonctions externes.

Qui peut déclarer une fonction externe ?

L’instruction `DECLARE EXTERNAL FUNCTION' peut être exécutée :

administrators
Utilisateurs avec le privilège `CREATE FUNCTION'.

L’utilisateur qui déclare une fonction externe devient le propriétaire de cette fonction.

docnext count = 7

Exemples

Example 1. Déclaration d’une fonction externe avec des paramètres d’entrée et de sortie par référence

DECLARE EXTERNAL FUNCTION addDay
TIMESTAMP, INT
RETURNS TIMESTAMP
ENTRY_POINT 'addDay' MODULE_NAME 'fbudf';

Example 2. Déclaration d’une fonction externe avec transfert des paramètres d’entrée et de sortie par descripteur

DECLARE EXTERNAL FUNCTION invl
INT BY DESCRIPTOR, INT BY DESCRIPTOR
RETURNS INT BY DESCRIPTOR
ENTRY_POINT 'idNvl' MODULE_NAME 'fbudf';

Example 3. Déclaration d’une fonction externe avec paramètres d’entrée par référence, paramètres de sortie par valeur

DECLARE EXTERNAL FUNCTION isLeapYear
TIMESTAMP
RETURNS INT BY VALUE
ENTRY_POINT 'isLeapYear' MODULE_NAME 'fbudf';

Example 4. Déclaration d’une fonction externe avec des paramètres d’entrée et de sortie transmis par le descripteur. Le deuxième paramètre de la fonction est utilisé comme paramètre de sortie.

DECLARE EXTERNAL FUNCTION i64Truncate
NUMERIC(18) BY DESCRIPTOR, NUMERIC(18) BY DESCRIPTOR
RETURNS PARAMETER 2
ENTRY_POINT 'fbtruncate' MODULE_NAME 'fbudf';

Voir aussi :

ALTER EXTERNAL FUNCTION,DROP EXTERNAL FUNCTION,CREATE FUNCTION.

`ALTER EXTERNAL FUNCTION`

affectation

Modifier le point d’entrée et/ou le nom du module pour une fonction définie par l’utilisateur (UDF).

Disponible en

DSQL

Syntaxe

ALTER EXTERNAL FUNCTION funcname
[ENTRY_POINT 'new_entry_point']
[MODULE_NAME 'new_library_name'];

Table 1. Paramètres de l’opérateur `ALTER EXTERNAL FUNCTION`
Paramètre	Description
funcname	Le nom de la fonction externe.
new_entry_point	Nouveau nom de la fonction à exporter (point d’entrée).
new_library_name	Le nouveau nom du module dans lequel se trouve la fonction.

L’instruction ALTER EXTERNAL FUNCTION change le point d’entrée et/ou le nom du module pour une fonction définie par l’utilisateur (UDF). Les dépendances existantes sont conservées.

La phrase ENTRY_POINT permet de spécifier un nouveau point d’entrée (le nom de la fonction à exporter).

La proposition MODULE_NAME vous permet de spécifier un nouveau nom de module où se trouve la fonction exportée.

Qui peut modifier une fonction externe ?

L’instruction `ALTER EXTERNAL FUNCTION' peut être exécutée :

administrators.
Le propriétaire de la fonction externe ;
Les utilisateurs ayant le privilège de `ALTER ANY FUNCTION'.

Exemples

Example 1. Changement du point d’entrée d’une fonction externe

ALTER EXTERNAL FUNCTION invl ENTRY_POINT 'intNvl';

Example 2. Modification du nom du module pour une fonction externe

ALTER EXTERNAL FUNCTION invl MODULE_NAME 'fbudf2';

Voir aussi :

DECLARE EXTERNAL FUNCTION,DROP EXTERNAL FUNCTION.

`DROP EXTERNAL FUNCTION`

affectation

Suppression d’une déclaration de fonction définie par l’utilisateur (UDF) dans la base de données.

Disponible en

DSQL, ESQL.

Syntaxe

DROP EXTERNAL FUNCTION funcname

Table 1. Paramètres de l’opérateur `DROP EXTERNAL FUNCTION`
Paramètre	Description
funcname	Le nom de la fonction externe.

L’instruction DROP EXTERNAL FUNCTION supprime de la base de données une déclaration de fonction définie par l’utilisateur. S’il existe des dépendances sur une fonction externe, la suppression n’aura pas lieu et une erreur correspondante sera émise.

Qui peut supprimer une fonction externe ?

L’instruction `DROP EXTERNAL FUNCTION' peut être exécutée :

administrators.
Le propriétaire de la fonction externe ;
Utilisateurs avec le privilège `DROP ANY FUNCTION'.

Exemples

Example 1. Suppression d’une fonction externe

DROP EXTERNAL FUNCTION addDay;

Voir aussi :

DECLARE EXTERNAL FUNCTION.