PostgreSQL fournit une interface rapide pour envoyer des appels de fonctions simples au serveur.
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, avec un statut
PGRES_COMMAND_OK
en cas de succès et
PGRES_FATAL_ERROR
si un problème a été rencontré. 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.
Pour passer un argument NULL à la fonction, configurez le champ
len
de cette structure à
-1
; les champs isint
et u
sont alors hors sujet.
(Cependant, ceci ne fonctionne que pour les connexions en protocole
3.0 et ultérieures.)
Si la fonction renvoie NULL, *result_len
est
configuré à -1
, et *result_buf
n'est pas modifié. (Ceci fonctionne seulement pour les connexions en
protocole 3.0 et ultérieures ; avec le protocole 2.0, ni
*result_len
ni *result_buf
ne
sont modifiés.)
Notez qu'il n'est pas possible de gérer des ensembles de résultats en utilisant cette interface. De plus, la fonction doit être une fonction standard, par une fonction d'agrégat ou une fonction de fenêtrage.