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.