27.3. Fonctions de commandes d'exécution

Soumet une commande au serveur et attend le résultat.

PGresult *PQexec(PGconn *conn, const char *command);

Renvoie un pointeur PGresult ou peut-être un pointeur NULL. Un pointeur non NULL est généralement renvoyé sauf dans des conditions de manque de mémoire ou d'erreurs sérieuses telles que l'incapacité à envoyer la commande au serveur. Si un pointeur NULL est renvoyé, il devrait être traité comme un résultat PGRES_FATAL_ERROR. Utilisez PQerrorMessage pour obtenir plus d'informations sur l'erreur.

Soumet une commande au serveur et attend le résultat, avec la possibilité de passer des paramètres séparément du texte de la commande SQL.

PGresult *PQexecParams(PGconn *conn,
                       const char *command,
                       int nParams,
                       const Oid *paramTypes,
                       const char * const *paramValues,
                       const int *paramLengths,
                       const int *paramFormats,
                       int resultFormat);

PQexecParams est identique à PQexec mais offre des fonctionnalités supplémentaires : des valeurs de paramètres peuvent être spécifiées séparément de la chaîne de commande et les résultats de la requête peuvent être demandés soit au format texte soit au format binaire. PQexecParams est supportée seulement dans les connexion avec le protocole 3.0 et ultérieurs ; elle échouera lors de l'utilisation du protocole 2.0.

Si les paramètres sont utilisés, ils sont référencés dans la chaîne de commande avec $1, $2, etc. nParams correspond au nombre de paramètres fournis ; il a la longueur des tableaux paramTypes[], paramValues[], paramLengths[] et paramFormats[]. (Les pointeurs de tableaux peuvent être NULL lorsque nParams vaut zéro.) paramTypes[] spécifie, par OID, les types de données à affecter aux symboles de paramètres. Si paramTypes est NULL ou si tout autre élément du tableau vaut zéro, le serveur assigne un type de données au symbole de paramètre de la même façon qu'il le ferait pour une chaîne littérale non typée. paramValues[] spécifie les valeurs réelles des paramètres. Un pointeur nul dans ce tableau signifie que le paramètre correspondant est nul ; sinon, le pointeur pointe vers une chaîne textuelle terminée avec un zéro (pour le format texte) ou des données binaires dans le format attendu par le serveur (pour le format binaire). paramLengths[] spécifie les longueurs réelles des données des paramètres au format binaire. Il est ignoré pour les paramètres NULL et les paramètres au format texte. Le pointeur de tableau peut être NULL lorsqu'il n'y a pas de paramètres binaires. paramFormats[] spécifie si les paramètres sont de type texte (place un zéro dans le tableau ) ou binaire (place un un dans le tableau ). Si le pointeur de tableau est NULL, alors tous les paramètres sont supposés être du type texte. resultFormat vaut zéro pour obtenir les résultats au format texte ou un pour obtenir des résultats au format binaire. (Il n'existe actuellement aucune méthode pour obtenir des colonnes de résultats différents dans des formats différents bien que cela soit possible dans le protocole sous-jacent.)

Envoie une requête pour exécuter une instruction séparée avec les paramètres donnés, et attend le résultat.

PGresult *PQexecPrepared(PGconn *conn,
                         const char *stmtName,
                         int nParams,
                         const char * const *paramValues,
                         const int *paramLengths,
                         const int *paramFormats,
                         int resultFormat);

PQexecPrepared est identique à PQexecParams, mais la commande à exécuter est spécifiée en nommant une instruction précédemment préparée au lieu de donner une chaîne de requête. Cette fonctionnalité permet aux commandes qui seront utilisées de façon répétée de n'être analysées et planifiées qu'une seule fois plutôt qu'à chaque fois qu'elles sont exécutées. PQexecPrepared est supporté seulement dans les connexions du protocole 3.0 et ultérieur ; elle échouera lors de l'utilisation du protocole 2.0.

Les paramètres sont identiques à PQexecParams, sauf que le nom d'une instruction préparée est donné au lieu d'une chaîne de requête et le paramètre paramTypes[] n'est pas présente (il n'est pas nécessaire car les types des paramètres de l'instruction préparée ont été déterminés à la création).

Renvoie l'état du résultat d'une commande.

ExecStatusType PQresultStatus(const PGresult *res);

PQresultStatus peut renvoyer une des valeurs suivantes :

Si le statut du résultat est PGRES_TUPLES_OK, alors les fonctions décrites ci-dessous peuvent être utilisées pour récupérer les lignes renvoyées pas la requête. Notez qu'une commande SELECT qui ne récupère aucune ligne affichera toujours PGRES_TUPLES_OK. PGRES_COMMAND_OK est utilisé par les commandes qui ne peuvent jamais renvoyer de lignes (INSERT, UPDATE, etc.). Une réponse PGRES_EMPTY_QUERY pourrait indiquer un bogue dans le logiciel client.

Un résultat de statut PGRES_NONFATAL_ERROR ne sera jamais renvoyé directement par PQexec ou d'autres fonctions d'exécution de requêtes ; les résultats de ce type sont passés au processeur de notifications (voir Section 27.9).

Convertit le type énuméré renvoyé par PQresultStatus en une constante de type chaîne décrivant le code d'état.

char *PQresStatus(ExecStatusType status);

Renvoie le message d'erreur associé à la commande ou une chaîne vide s'il n'y a pas eu d'erreurs.

char *PQresultErrorMessage(const PGresult *res);

S'il y a eu une erreur, la chaîne renvoyée inclue un retour chariot en fin.

Suivant immédiatement un appel à PQexec ou PQgetResult, PQerrorMessage (sur la connexion) renvoie la même chaîne que PQresultErrorMessage (sur le résultat). Néanmoins, un PGresult conserve son message d'erreur jusqu'à destruction alors que le message d'erreur de la connexion change lorsque des opérations suivantes sont réalisées. Utilisez PQresultErrorMessage quand vous voulez connaître le statut associé à un PGresult particulier ; utilisez PQerrorMessage lorsque vous souhaitez connaître le statut de la dernière opération sur la connexion.

Renvoie un champ individuel d'un rapport d'erreur.

char *PQresultErrorField(const PGresult *res, int fieldcode);

fieldcode est un identifiant de champ d'erreur ; voir les symboles listés ci-dessous. NULL est renvoyé si PGresult n'est pas un résultat d'erreur ou d'avertissement, ou n'inclue pas le champ spécifié. Les valeurs de champ n'incluent normalement pas un retour chariot en fin.

Les codes de champs suivants sont disponibles :

Le client est responsable du formatage des informations affichées pour correspondre à ses besoins ; en particulier, il doit supprimer les longues lignes si nécessaires. Les caractères de retour chariot apparaissant dans les champs de message d'erreur doivent être traités comme des changements de paragraphes, pas comme des changements de lignes.

Les erreurs générées en interne par libpq ont une sévérité et un message principal mais aucun autre champ. Les erreurs renvoyées par un serveur utilisant un protocole antérieure à la 3.0 incluent la sévérité et le message principal, et quelques fois un message détaillé, mais aucun autre champ.

Notez que les champs d'erreurs sont seulement disponibles pour les objets PGresult, et non pas pour les objets PGconn ; il n'existe pas de fonction PQerrorField.

Libère le stockage associé à un PGresult. Chaque résultat de commande doit être libéré via PQclear lorsqu'il n'est plus nécessaire.

void PQclear(PQresult *res);

Vous pouvez conserver un objet PGresult aussi longtemps que vous en avez besoin ; il ne disparait pas lorsque vous lancez une nouvelle commande, même pas si vous fermez la connexion. Pour vous en débarrasser, vous devez appeler PQclear. En cas d'oubli, votre application souffrira de fuites de mémoire.

Construit un objet PGresult vide avec le statut donné.

PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);

Il s'agit d'une fonction interne de libpq pour allouer et initialiser un objet PGresult vide. Elle est exportée car certaines applications la trouvent utiles pour générer eux-même des objets résultats (particulièrement des objets avec des statuts d'erreur). Si conn n'est pas NULL et que status indique une erreur, le message d'erreur actuel pour la connexion spécifiée est copié dans PGresult. Notez que PQclear doit être appelée sur l'objet, comme avec un PGresult renvoyé par libpq elle-même.

Renvoie le nombre de lignes (tuples) du résultat de la requête.

int PQntuples(const PGresult *res);

Renvoie le nombre de colonnes (champs) de chaque ligne du résultat de la requête.

int PQnfields(const PGresult *res);

Renvoie le nom de la colonne associée avec le numéro de colonne donnée. Les numéros de colonnes commencent à zéro.

char *PQfname(const PGresult *res,
              int column_number);

NULL est renvoyé si le numéro de colonne est en dehors de la plage.

Renvoie le numéro de colonne associé au nom de la colonne donné.

int PQfnumber(const PGresult *res,
              const char *column_name);

-1 est renvoyé si le nom donné ne correspond à aucune colonne.

Le nom donné est traité comme un identifiant dans une commande SQL, c'est-à-dire qu'il est mis en minuscule sauf s'il est entre des guillemets doubles. Par exemple, pour le résultat de la requête suivante

select 1 as FOO, 2 as "BAR";

nous obtenons les résultats suivants :

PQfname(res, 0)              foo
PQfname(res, 1)              BAR
PQfnumber(res, "FOO")        0
PQfnumber(res, "foo")        0
PQfnumber(res, "BAR")        -1
PQfnumber(res, "\"BAR\"")    1

Renvoie l'OID de la table à partir de laquelle la colonne donnée a été récupérée. Les numéros de colonnes commencent à zéro.

Oid PQftable(const PGresult *res,
             int column_number);

InvalidOid est renvoyé si le numéro de colonne est en dehors de la plage ou si la colonne spécifiée n'est pas une référence simple à une colonne de table, ou lors de l'utilisation d'un protocole antérieur à la version 3.0. Vous pouvez lancer des requêtes vers la table système pg_class pour déterminer exactement quelle table est référencée.

Le type Oid et la constante InvalidOid sont définis lorsque vous incluez le fichier d'en-tête libpq. Ils ont le même type entier.

Renvoie le numéro de colonne (à l'intérieur de la table) de la colonne correspondant à la colonne spécifiée de résultat de la requête. Les numéros de colonnes resultat commencent à 0.

int PQftablecol(const PGresult *res,
                int column_number);

Zéro est renvoyé si le numéro de colonne est en dehors de la plage, ou si la colonne spécifiée n'est pas une simple référence à une colonne de table, ou lors de l'utilisation d'un protocole antérieur à la version 3.0.

Renvoie le code de format indiquant le format de la colonne donné. Les numéros de colonnes commencent à zéro.

int PQfformat(const PGresult *res,
              int column_number);

Le code de format zéro indique une représentation textuelle des données alors qu'un code de format un indique une représentation binaire. (Les autres codes sont réservés pour des définitions futures.)

Renvoie le type de données associé avec le numéro de colonne donné. L'entier renvoyé est le numéro OID interne du type. Les numéros de colonnes commencent à zéro.

Oid PQftype(const PGresult *res,
            int column_number);

Vous pouvez lancer des requêtes sur la table système pg_type pour obtenir les noms et propriétés des différents types de données. Les OID des types de données intégrés sont définis dans le fichier src/include/catalog/pg_type.h de la distribution des sources.

Renvoie le modifieur de type de la colonne associée avec le numéro de colonne donné. Les numéros de colonnes commencent à zéro.

int PQfmod(const PGresult *res,
           int column_number);

L'interprétation des valeurs du modificateur est spécifique au type ; elles indiquent la précision ou les limites de taille. La valeur -1 est utilisée pour indiquer qu'<< aucune information n'est disponible >>. La plupart des types de données n'utilisent pas les modificateurs, auquel cas la valeur est toujours -1.

Renvoie la taille en octets de la colonne associée avec le numéro de colonne donné. Les numéros de colonnes commencent à zéro.

int PQfsize(const PGresult *res,
            int column_number);

PQfsize renvoie l'espace alloué pour cette colonne dans une ligne de la base de données, en d'autres termes la taille de la représentation interne du serveur du type de données. (De façon cohérente, ce n'est pas réellement utile pour les clients.) Une valeur négative indique que les types de données ont une longueur variable.

Renvoie 1 si PGresult contient des données binaires et 0 s'il contient des données texte.

int PQbinaryTuples(const PGresult *res);

Cette fonction est obsolète (sauf dans le cas d'une utilisation en relation avec COPY) car un PGresult peut contenir du texte dans certaines colonnes et des données binaires dans d'autres. PQfformat est la fonction préférée. PQbinaryTuples renvoie 1 seulement si toutes les colonnes du résultat sont dans un format binaire (format 1).

Renvoie la valeur d'un seul champ d'une (seule) ligne d'un PGresult. Les numéros de lignes et de colonnes commencent à zéro.

char* PQgetvalue(const PGresult *res,
                 int row_number,
                 int column_number);

Pour les données au format texte, la valeur renvoyée par PQgetvalue est une représentation au format chaîne de caractères terminée par un octet nul de la valeur du champ. Pour les données au format binaire, la valeur est dans la représentation binaire déterminée par les fonctions typsend et typreceive de la donnée. (La valeur est en fait suivie d'un octet zéro dans ce cas aussi mais ce n'est pas réellement utile car la valeur elle même peut contenir des octets nuls.)

Une chaîne vide est renvoyée si la valeur du champ est nulle. Voir PQgetisnull pour distinguer les valeurs nulles des valeurs de chaîne vide.

Le pointeur renvoyé par PQgetvalue pointe vers un espace mémoire de la structure PGresult. Il ne faut pas modifier les données vers lesquelles il pointe. Il faut recopier ces données si on souhaite les utiliser après la disparition de la structure PGresult.

Teste un champ pour savoir s'il est nul. Les numéros de lignes et de colonnes commencent à zéro.

int PQgetisnull(const PGresult *res,
                int row_number,
                int column_number);

Cette fonction renvoie 1 si le champ est nul et 0 s'il contient une valeur non nulle. (Notez que PQgetvalue renvoie une chaîne vide, et non pas un pointeur nul, pour un champ nul.)

Renvoie la longueur réelle de la valeur d'un champ en octet. Les numéros de lignes et de colonnes commencent à zéro.

int PQgetlength(const PGresult *res,
                int row_number,
                int column_number);

C'est la longueur réelle des données pour la valeur particulière des données, c'est-à-dire la taille de l'objet pointé par PQgetvalue. Pour le format textuel, c'est identique à strlen(). Pour le format binaire, c'est une information essentielle. Notez qu'il ne faut pas se fier à PQfsize pour obtenir la taille réelle des données.

Affiche toutes les lignes et, optionnellement, les noms des colonnes dans le flux de sortie spécifié.

void PQprint(FILE* fout,      /* flux de sortie */
             const PGresult *res,
             const PQprintOpt *po);

typedef struct {
    pqbool  header;      /* affiche le en-têtes des champs et le nombre de
                            lignes */
    pqbool  align;       /* aligne les champs */
    pqbool  standard;    /* vieux format (mort) */
    pqbool  html3;       /* affiche les tables en HTML */
    pqbool  expanded;    /* étend les tables */
    pqbool  pager;       /* utilise le paginateur pour la sortie si nécessaire
                            */
    char    *fieldSep;   /* séparateur de champ */
    char    *tableOpt;   /* attributs des éléments de table HTML */
    char    *caption;    /* titre de la table HTML */
    char    **fieldName; /* Tableau terminé par un NULL des noms de remplacement
                            des champs */
} PQprintOpt;

Cette fonction était auparavant utilisée par psql pour afficher les résultats des requêtes mais ce n'est plus le cas. Notez qu'elle suppose que les données sont dans un format textuel.

Renvoie l'état de la commande depuis l'instruction SQL qui a généré le PGresult.

char * PQcmdStatus(PGresult *res);

souvent, c'est juste le nom de la commande mais elle peut inclure des données supplémentaires comme le nombre de lignes traitées.

Renvoie le nombre de lignes affectées par la commande SQL.

char * PQcmdTuples(PGresult *res);

Si la commande SQL qui a généré PGresult était une instruction INSERT, UPDATE, DELETE, MOVE ou FETCH, cette fonction renvoie une chaîne contenant le nombre de lignes affectées. Si la commande était autre chose, elle renvoie une chaîne vide.

Renvoie l'OID de la ligne insérée, si la commande SQL était une instruction INSERT qui a inséré exactement une ligne dans un table comprenant des OIDs. Sinon, renvoie InvalidOid.

Oid PQoidValue(const PGresult *res);

Renvoie une chaîne avec l'OID de la ligne insérée si la commande SQL était une instruction INSERT. (La chaîne vaut 0 si l'instruction INSERT a inséré plusieurs lignes ou si la table cible n'a pas d'OIDs.) Si la commande n'était pas un INSERT, renvoie une chaîne vide.

char * PQoidStatus(const PGresult *res);

Cette fonction est obsolète et remplacée par PQoidValue. Elle n'est pas compatible avec les threads.

Échappe des données binaires à utiliser à l'intérieur d'une commande SQL avec le type bytea. Comme avec PQescapeStringConn, PQescapeBytea est seulement utilisée pour insérer des données directement dans une chaîne de commande SQL.

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

Certaines valeurs d'octets doivent être échappées (mais toutes les valeurs d'octets peuvent être échappées) lorsqu'elles font partie d'un littéral bytea dans une instruction SQL. En général, pour échapper un octet, il est converti dans en un nombre à trois chiffres correspondant à sa valeur octale et précédé par un ou deux anti-slashs. Le guillemet simple et caractère anti-slash ont des séquences d'échappements alternatives. Voir Section 8.4 pour plus d'informations. PQescapeByteaConn réalise cette opération en échappant seulement les octets requis.

Le paramètre from pointe sur le premier octet de la chaîne à échapper et le paramètre from_length donne le nombre d'octets de cette chaîne binaire. (Un octet zéro de terminaison n'est ni nécessaire ni compté.) Le paramètre to_length pointe vers une variable qui contiendra la longueur de la chaîne échappée résultante. Cette longueur inclue l'octet zéro de terminaison.

PQescapeByteaConn renvoie une version échappée du paramètre from dans de la mémoire allouée avec malloc(). Cette mémoire doit être libérée avec PQfreemem lorsque le résultat n'est plus nécessaire. Tous les caractères spéciaux de la chaîne de retour sont remplacés de façon à ce qu'ils puissent être traités proprement par l'analyseur de chaînes littérales de PostgreSQL et par l'entrée bytea de la fonction. Un octet zéro de terminaison est aussi ajouté. Les guillemets simples qui englobent les chaînes littérales de PostgreSQL ne font pas partie de la chaîne résultante.

En cas d'erreur, un pointeur NULL est renvoyé et un message d'erreur adéquat est stocké dans l'objet conn. Actuellement, la seule erreur possible est une mémoire insuffisante pour stocker la chaîne résultante.

PQescapeBytea est une version obsolète de PQescapeByteaConn.

unsigned char *PQescapeBytea(const unsigned char *from,
                             size_t from_length,
                             size_t *to_length);

La seule différence avec PQescapeByteaConn est que PQescapeBytea ne prend pas de paramètre PGconn. À cause de ceci, il ne peut ajuster son comportement suivant les propriétés de la connexion (en particulier si les chaînes conformes au standard sont activées) et, du coup, il pourrait donner de mauvais résultats. De plus, il n'a aucun moyen de renvoyer un message d'erreur en cas d'échec.

PQescapeBytea peut être utilisé en toute sécurité dans les programmes clients avec un seul thread et fonctionnant avec une seule connexion PostgreSQL en même temps (dans ce cas, il peut trouver ce dont il a besoin de savoir << en arrière-plan >>). Dans d'autres contextes, il devrait être remplacé par PQescapeByteaConn.

Convertit une représentation de la chaîne en donnés binaires -- l'inverse de PQescapeBytea. Ceci est nécessaire lors de la récupération de données bytea en format texte, mais pas lors de leur récupération au format binaire.

unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);

Le paramètre from pointe vers une chaîne de telle façon qu'elle pourrait provenir de PQgetvalue lorsque la colonne est de type bytea. PQunescapeBytea convertit cette représentation de la chaîne en sa représentation binaire. Elle renvoie une pointeur vers un tampon alloué avec malloc(), ou NULL en cas d'erreur, et place la taille du tampon dans to_length. Le résultat doit être libéré en utilisant PQfreemem lorsqu'il n'est plus nécessaire.

La conversion n'est pas l'inverse exacte de PQescapeBytea car la chaîne n'est pas échappée avec PQgetvalue. Cela signifie en particulier qu'il n'y a pas besoin de réfléchir à la mise entre guillemets de la chaîne, et donc pas besoin d'un paramètre PGconn.

Libère la mémoire allouée par libpq.

void PQfreemem(void *ptr);

Libère la mémoire allouée par libpq, particulièrement PQescapeByteaConn, PQescapeBytea, PQunescapeBytea, et PQnotifies. C'est nécessaire pour Microsoft Windows, qui ne peut pas libérer la mémoire des DLL, sauf dans le cas où des DLL multithreadés (/MD dans VC6) sont utilisées. Pour les autres plateformes, cette fonction est identique à la fonction free() de la bibliothèque standard.