Syntaxe de CREATE FUNCTION/DROP FUNCTION
<<<		 Ajouter une nouvelle fonction définie par l'utilisateur (UDF) Ajouter de nouvelles fonctions natives
>>>
23.2 Ajouter des fonctions à MySQL
23 Etendre MySQL
 Manuel de Référence MySQL 4.1 : Version Française
. Syntaxe de CREATE FUNCTION/DROP FUNCTION
->Ajouter une nouvelle fonction définie par l'utilisateur (UDF)
. Ajouter de nouvelles fonctions natives

23.2.2 Ajouter une nouvelle fonction définie par l'utilisateur (UDF)

Pour que le mécanisme UDF fonctionne, les fonctions doivent êtres écrites en C ou C++ et votre système doit supporter le chargement dynamique. Les sources de MySQL incluent un fichier sql/udf_example.cc qui définit 5 nouvelles fonctions. Consultez ce fichier pour voir comment marchent les conventions d'appels des UDF.

Pour que mysqld puisse utiliser les fonctions UDF, vous devez configurer MySQL avec l'option --with-mysqld-ldflags=-rdynamic . La raison est que sur diverses plate-formes, (Linux inclus) vous pouvez charger une librairie dynamique (avec dlopen() ) depuis un programme statique lié, que vous pouvez obtenir si vous utilisez l'option --with-mysql-ldflags=-all-static . Si vous voulez utiliser une UDF qui nécessite un accès aux symboles de mysqld (comme l'exemple methaphone dans sql/udf_example.cc qui utilise default_charset_info ), vous devez lier le programme avec -rdynamic (voir man dlopen ).

Pour chaque fonction que vous voulez utiliser dans SQL, vous devez définir les fonctions correspondantes en C (ou C++). Dans la discussion ci-dessous, le nom ``xxx'' est utilisé comme un exemple de nom de fonction. Pour faire la différence entre l'usage de SQL et de C/C++, XXX() (majuscules) indique l'appel d'une fonction SQL et xxx() (minuscules) indique l'appel d'une fonction C/C++.

Les fonctions C/C++ que vous écrivez pour l'implémentation de l'interface de XXX() sont :
    xxx() (requis)
    La fonction principale. C'est là où le résultat de la fonction est calculé. La correspondance entre le type de SQL et le type retourné par votre fonction C/C++ est affiché ci-dessous :
    SQL type C/C++ type
    STRING char *
    INTEGER long long
    REAL double
    xxx_init() (optionnel)
    La fonction d'initialisation de xxx() . Elle peut-être utilisée pour :
      Vérifier le nombre d'arguments de XXX() .
      Vérifier que les arguments correspondent aux types requis ou indiquer à MySQL de contraindre des arguments aux types que vous voulez quand la fonction principale est appelée.
      Allouer la mémoire requise pour la fonction principale.
      Spécifier la longueur maximale de la sortie.
      Spécifier (pour les fonctions REAL ) le nombre maximal de décimales.
      Spécifier si le résultat peut-être NULL .
    xxx_deinit() (optionnel)
    La dés-initialisation de la fonction xxx() . Elle doit dés-allouer toute la mémoire allouée par l'initialisation de la fonction.
Quand une requête SQL fait appel à XXX() , MySQL appelle l'initialisation de la fonction xxx_init() , pour laisser exécuter n'importe quelle action exigée, telle que la vérification d'arguments ou l'allocation de mémoire.

Si xxx_init() retourne une erreur, la requête SQL est annulée avec un message d'erreur et la fonction principale et la fonction de dés-initialisation ne sont pas appelées. Autrement, la fonction principale xxx() est appelée une fois pour chaque ligne. Après que toutes les lignes aient été traitées, la fonction de dés-initialisation xxx_deinit() est appelée pour procéder aux nettoyages requis.

Pour les fonctions d'agrégat (comme SUM() ), vous pouvez également ajouter les fonctions suivantes :
    xxx_reset() (requise)
    Remet la somme à zéro et insère l'argument en tant que valeur initiale pour un nouveau groupe.
    xxx_add() (requise)
    Ajoute l'argument à l'ancienne somme.
Quand vous utilisez les UDF d'agrégat, MySQL opère comme suit :All functions must be thread-safe (not just the main function, but the initialisation and deinitialisation functions as well). This means that you are not allowed to allocate any global or static variables that change! If you need memory, you should allocate it in xxx_init() and free it in xxx_deinit() .
  • Appeler xxx_init() pour laisser la fonction d'agrégat allouer la mémoire dont elle aura besoin pour stocker les résultats.
  • Trier la table en accord avec la clause GROUP BY .
  • Pour la première ligne dans un nouveau groupe, appeler la fonction xxx_reset() .
  • Pour chaque ligne appartenant à un même groupe, appeler la fonction xxx_add() .
  • Quand le groupe change ou lorsque la dernière ligne a été traitée, appeler xxx() pour obtenir le résultat de l'agrégat.
  • Répéter 3-5 tant que toutes les lignes n'ont pas été traitées.
  • Appeler xxx_deinit() pour libérer la mémoire allouée.
Toutes les fonctions doivent être sûrs pour les threads (pas seulement la fonction principale, mais les fonctions d'initialisation et de dés-initialisation également). Cela signifie que vous n'êtes pas autorisés à allouer une variable globale ou statique qui change ! Si vous avez besoin de mémoire, vous devez l'allouer avec la fonction xxx_init() et la libérer avec xxx_deinit() .

Sommaire :
<< Ajouter une nouvelle fonction définie par l'utilisateur (UDF) >>
Syntaxe de CREATE FUNCTION/DROP FUNCTION Ajouter des fonctions à MySQL Ajouter de nouvelles fonctions natives