affectation
Déclaration d’une fonction définie par l’utilisateur (UDF) dans une base de données.
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.
