D'habitude, libpq récupère le résultat complet
d'une commande SQL et la renvoie à l'application sous la forme d'une seule
structure PGresult
. Ce comportement peut être un
problème pour les commandes qui renvoient un grand nombre de lignes. Dans
de tels cas, les applications peuvent utiliser
PQsendQuery
et PQgetResult
dans
le mode simple ligne. Dans ce mode, les lignes du
résultat sont renvoyées à l'application une par une, au fur et à mesure
qu'elles sont reçues du serveur.
Pour entrer dans le mode simple ligne, appelez
PQsetSingleRowMode
immédiatement après un appel
réussi à PQsendQuery
(ou une fonction similaire).
Cette sélection de mode ne fonctionne que pour la requête en cours
d'exécution. Puis appelez PQgetResult
de façon répétée,
jusqu'à ce qu'elle renvoit null, comme documenté dans Section 33.4. Si la requête renvoit des lignes, ils sont renvoyées
en tant qu'objet PGresult
individuel, qui ressemble
à des résultats de requêtes standards en dehors du fait qu'elles ont le code
de statut PGRES_SINGLE_TUPLE
au lieu de
PGRES_TUPLES_OK
. Après la dernière ligne ou immédiatement
si la requête ne renvoit aucune ligne, un objet de zéro ligne avec le statut
PGRES_TUPLES_OK
est renvoyé ; c'est le signal
qu'aucune autre ligne ne va arriver. (Notez cependant qu'il est toujours
nécessaire de continuer à appeler PQgetResult
jusqu'à
ce qu'elle renvoit null.) Tous les objets PGresult
contiendront les mêmes données de description de lignes (noms de colonnes,
types, etc) qu'un objet PGresult
standard aurait
pour cette requête. Chaque objet doit être libéré avec la fonction
PQclear
comme d'ordinaire.
PQsetSingleRowMode
Sélectionne le mode ligne simple pour la requête en cours d'exécution.
int PQsetSingleRowMode(PGconn *conn);
Cette fonction peut seulement être appelée immédiatement après
PQsendQuery
ou une de ses fonctions sœurs, avant
toute autre opération sur la connexion comme
PQconsumeInput
ou
PQgetResult
. Si elle est appelée au bon moment,
la fonction active le mode simple ligne pour la requête en cours et
renvoit 1. Sinon, le mode reste inchangé et la fonction renvoit 0. Dans
tous les cas, le mode retourne à la normale après la fin de la requête
en cours.
Lors du traitement d'une requête, le serveur pourrait renvoyer quelques
lignes puis rencontrer une erreur, causant l'annulation de la requête.
D'ordinaire, la bibliothèque partagée libpq
annule ces lignes et renvoit une erreur. Avec le mode simple ligne,
des lignes ont déjà pu être envoyées à l'application. Du coup, l'application
verra quelques objets PGresult
de statut
PGRES_SINGLE_TUPLE
suivi par un objet de statut
PGRES_FATAL_ERROR
. Pour un bon comportement transactionnel,
l'application doit être conçue pour invalider ou annuler tout ce qui a été
fait avec les lignes précédemment traitées si la requête finit par échouer.