PostgreSQLLa base de données la plus sophistiquée au monde.

31.6. Interface à chemin rapide

PostgreSQL™ fournit une interface rapide pour envoyer des appels de fonctions simples au serveur.

[Astuce]

Astuce

Cette interface est quelque peu obsolète car vous pourriez réaliser les mêmes choses avec des performances similaires et plus de fonctionnalités en initialisant une instruction préparée pour définir l'appel de fonction. Puis, exécuter l'instruction avec une transmission binaire des paramètres et des substitutions de résultats pour un appel de fonction à chemin rapide.

La fonction PQfn demande l'exécution d'une fonction du serveur via l'interface de chemin rapide :

PGresult* PQfn(PGconn* conn,
               int fnid,
               int *result_buf,
               int *result_len,
               int result_is_int,
               const PQArgBlock *args,
               int nargs);

typedef struct
{
    int len;
    int isint;
    union
    {
        int *ptr;
        int integer;
    } u;
} PQArgBlock;

L'argument fnid est l'OID de la fonction à exécuter. args et nargs définissent les paramètres à passer à la fonction ; ils doivent correspondre à la liste d'arguments déclarés de la fonction. Quand le champ isint d'une structure est vrai, la valeur de u.integer est envoyée au serveur en tant qu'entier de la longueur indiquée (qui doit être 2 ou 4 octets) ; les bons échanges d'octets se passent. Quand isint est faux, le nombre d'octets indiqué sur *u.ptr est envoyé au traitement ; les données doivent être dans le format attendu par le serveur pour la transmission binaire du type de données de l'argument de la fonction. (La déclaration de u.ptr en tant que type int * est historique ; il serait préférable de la considérer comme un void *.) result_buf pointe vers le tampon dans lequel placer le code de retour de la fonction. L'appelant doit avoir alloué suffisamment d'espace pour stocker le code de retour (il n'y a pas de vérification !). La longueur actuelle du résultat en octet sera renvoyé dans l'entier pointé par result_len. Si un résultat sur un entier de 2 ou 4 octets est attendu, initialisez result_is_int à 1, sinon initialisez-le à 0. Initialiser result_is_int à 1 fait que libpq échange les octets de la valeur si nécessaire, de façon à ce que la bonne valeur int soit délivrée pour la machine cliente ; notez qu'un entier sur quatre octets est fourni dans *result_buf pour la taille du résultat autorisé. Quand result_is_int vaut 0, la chaîne d'octets au format binaire envoyée par le serveur est renvoyée non modifiée. (Dans ce cas, il est préférable de considérer result_buf comme étant du type void *.)

PQfn renvoie toujours un pointeur PGresult valide. L'état du résultat devrait être vérifié avant que le résultat ne soit utilisé. Le demandeur est responsable de la libération de la structure PGresult avec PQclear lorsque celle-ci n'est plus nécessaire.

Notez qu'il n'est pas possible de gérer les arguments nuls, les résultats nuls et les résultats d'ensembles nuls en utilisant cette interface.