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 peut être impraticable
pour les commandes renvoyant un grand nombre de lignes. Dans
de tels cas, les applications peuvent utiliser
PQsendQuery et PQgetResult dans
le mode ligne-à-ligne ou le mode
par morceau. Dans ces modes, les lignes du
résultat sont renvoyées à l'application dès qu'elles sont reçues du serveur,
une à la fois pour le mode ligne simple ou en groupes pour le mode par
morceau.
Pour entrer dans un de ces modes, appelez
PQsetSingleRowMode
ou PQsetChunkedRowsMode 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 32.4. Si la requête renvoit des lignes, elles sont renvoyées
en tant qu'un ou plusieurs objets PGresult, qui ressemblent
à des résultats de requêtes standards en dehors du fait qu'elles ont le code
de statut PGRES_SINGLE_TUPLE pour le mode ligne simple ou
PGRES_TUPLES_CHUNK pour le mode par morceau au lieu de
PGRES_TUPLES_OK. Il y a exactement une ligne de résultat
dans chaque objet PGRES_SINGLE_TUPLE alors qu'un objet
PGRES_TUPLES_CHUNK contient au moins une ligne mais pas
plus du nombre spécifié de lignes par morceau. Après la
dernière ligne, ou immédiatement
si la requête ne renvoit aucune ligne, un objet à 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.
Lors de l'utilisation du mode pipeline, le mode single-row or chunked doit être activé
pour chaque requête dans le pipeline avant de récupérer les résultats pour
cette requête avec PQgetResult. Voir Section 32.5 pour plus d' informations.
PQsetChunkedRowsMode #Sélectionne le mode par morceau pour la requête en cours d'exécution.
int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);
Cette fonction est similaire à
PQsetSingleRowMode
, sauf qu'elle demande une
récupération d'au plus chunkSize lignes par
structure PGresult, pas nécessairement juste
une ligne. Cette fonction peut seulement être appelée immédiatement après
PQsendQuery ou une de ses fonctions soeurs, avant
toute autre opération sur la connexion, telle que
PQconsumeInput ou
PQgetResult. Si elle est appelée au bon moment,
la fonction active le mode par morceau pour la requête en cours et
renvoie 1. Sinon le mode ne change pas et la fonction renvoie 0. Dans
tous les cas, le mode revient à la normale après la fin de la requête
en cours.
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 ligne-à-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 peut renvoyer quelques
lignes puis rencontrer une erreur, causant l'annulation de la requête.
D'ordinaire, la bibliothèque partagée libpq
jette ces lignes et renvoit une erreur. Avec le mode ligne-à-ligne ou le
mode par morceau,
certaines lignes ont déjà pu être envoyées à l'application. Du coup, l'application
verra quelques objets PGresult de statut
PGRES_SINGLE_TUPLE or PGRES_TUPLES_CHUNK suivis 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.