27.6. Interface � chemin rapide

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

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 1, 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. result_buf est le tampon dans lequel placer le code de retour. 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 sera renvoy� dans l'entier point� par result_len. Si un r�sultat sur un entier de 1, 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. 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.

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.