diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index d829a4b..96e3b2a 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -3947,9 +3947,13 @@ int PQsendQuery(PGconn *conn, const char *command);
After successfully calling PQsendQuery, call
PQgetResult one or more times to obtain the
- results. PQsendQuery cannot be called again
- (on the same connection) until PQgetResult
- has returned a null pointer, indicating that the command is done.
+ results. PQsendQuery may be called multiple
+ times (on the same connection), allowing query pipelining. Call
+ PQgetLastQuery to get a PGquery
+ which can be used to identify which results obtained from
+ PQgetResult belong to each pipelined query dispatch.
+ If only one query is dispatched at a time, you can call PQgetResult
+ until a NULL value is returned to indicate the end of the query.
@@ -4133,8 +4137,8 @@ PGresult *PQgetResult(PGconn *conn);
PQgetResult must be called repeatedly until
- it returns a null pointer, indicating that the command is done.
- (If called when no command is active,
+ it returns a null pointer, indicating that all dispatched commands
+ are done. (If called when no command is active,
PQgetResult will just return a null pointer
at once.) Each non-null result from
PQgetResult should be processed using the
@@ -4144,14 +4148,19 @@ PGresult *PQgetResult(PGconn *conn);
PQgetResult will block only if a command is
active and the necessary response data has not yet been read by
PQconsumeInput.
+ If query pipelining is being used, call
+ PQgetFirstQuery on a non-busy connection
+ (PQisBusy returns false) to determine which
+ query the next result belongs to.
Even when PQresultStatus indicates a fatal
- error, PQgetResult should be called until it
- returns a null pointer, to allow libpq to
- process the error information completely.
+ error, PQgetResult should be called until the
+ query has no more results (null pointer return if not using query
+ pipelining, otherwise see PQgetFirstQuery),
+ to allow libpq to process the error information completely.
@@ -4385,6 +4394,109 @@ int PQflush(PGconn *conn);
read-ready and then read the response as described above.
+
+
+
+ PQgetQueryCommand
+
+ PQgetQueryCommand
+
+
+
+
+
+ Returns the query string associated with the PGquery.
+
+const char * PQgetQueryCommand(PGquery *query);
+
+
+
+
+ When using query pipelining this function can be used to retrieve the command
+ that created the query object.
+
+
+
+
+
+
+ PQgetFirstQuery
+
+ PQgetFirstQuery
+
+
+
+
+
+ Returns the first async query to recieve results, or NULL if no
+ async queries are active.
+
+PGquery * PQgetFirstQuery(PGconn *conn);
+
+
+
+
+ When using query pipelining this function can be used to indicate
+ which query the next result of PQgetResult
+ belongs. The result is only guaranteed to be valid for the next call to
+ PQgetResult if PQisBusy
+ is false, otherwise the returned PGquery
+ may or may not have more results. The PGquery
+ remains valid after PQgetResult until the next
+ libpq call that consumes input.
+
+
+
+
+
+
+ PQgetNextQuery
+
+ PQgetNextQuery
+
+
+
+
+
+ Returns the next PGquery in the list of
+ dispatched async queries waiting for results.
+
+PGquery * PQgetNextQuery(PGquery *query);
+
+
+
+
+ This function can be used to iterate each pending async query starting
+ with the result of PQgetFirstQuery, and ending
+ with the result of PQgetLastQuery, then null.
+
+
+
+
+
+ PQgetLastQuery
+
+ PQgetLastQuery
+
+
+
+
+
+ Returns the last PGquery in the list of
+ dispatched async queries waiting for results.
+
+PGquery * PQgetLastQuery(PGquery *query);
+
+
+
+
+ Call this function after dispatching an async query to get
+ a PGquery that can be used to identify
+ the originating query for each result obtained by
+ PGgetResult.
+
+
+
@@ -4411,7 +4523,7 @@ int PQflush(PGconn *conn);
immediately after a successful call of PQsendQuery
(or a sibling function). This mode selection is effective only for the
currently executing query. Then call PQgetResult
- repeatedly, until it returns null, as documented in . If the query returns any rows, they are returned
as individual PGresult objects, which look like
normal query results except for having status code
@@ -4420,8 +4532,8 @@ int PQflush(PGconn *conn);
the query returns zero rows, a zero-row object with status
PGRES_TUPLES_OK is returned; this is the signal that no
more rows will arrive. (But note that it is still necessary to continue
- calling PQgetResult until it returns null.) All of
- these PGresult objects will contain the same row
+ calling PQgetResult until the last query result is returned.)
+ All of these PGresult objects will contain the same row
description data (column names, types, etc) that an ordinary
PGresult object for the query would have.
Each object should be freed with PQclear as usual.