*** a/doc/src/sgml/libpq.sgml
--- b/doc/src/sgml/libpq.sgml
***************
*** 7233,7238 **** int PQisthreadsafe();
--- 7233,7527 ----
+
+ Alternative row processor
+
+
+ PGresult
+ PGconn
+
+
+
+ As the standard usage, rows are stored into PGresult
+ until full resultset is received. Then such completely-filled
+ PGresult is passed to user. This behavior can be
+ changed by registering alternative row processor function,
+ that will see each row data as soon as it is received
+ from network. It has the option of processing the data
+ immediately, or storing it into custom container.
+
+
+
+ Note - as row processor sees rows as they arrive, it cannot know
+ whether the SQL statement actually finishes successfully on server
+ or not. So some care must be taken to get proper
+ transactionality.
+
+
+
+
+
+ PQsetRowProcessor
+
+ PQsetRowProcessor
+
+
+
+
+
+ Sets a callback function to process each row.
+
+ void PQsetRowProcessor(PGconn *conn, PQrowProcessor func, void *param);
+
+
+
+
+
+
+ conn
+
+
+ The connection object to set the row processor function.
+
+
+
+
+ func
+
+
+ Storage handler function to set. NULL means to use the
+ default processor.
+
+
+
+
+ param
+
+
+ A pointer to contextual parameter passed
+ to func.
+
+
+
+
+
+
+
+
+
+
+ PQrowProcessor
+
+ PQrowProcessor
+
+
+
+
+
+ The type for the row processor callback function.
+
+ int (*PQrowProcessor)(PGresult *res, PGrowValue *columns, void *param);
+
+ typedef struct
+ {
+ int len; /* length in bytes of the value, -1 if NULL */
+ char *value; /* actual value, without null termination */
+ } PGrowValue;
+
+
+
+
+ The columns array will have PQnfields()
+ elements, each one pointing to column value in network buffer.
+ The len field will contain number of
+ bytes in value. If the field value is NULL then
+ len will be -1 and value will point
+ to position where the value would have been in buffer.
+ This allows estimating row size by pointer arithmetic.
+
+
+
+ This function must process or copy away row values in network
+ buffer before it returns, as next row might overwrite them.
+
+
+
+ This function can return 1 for success for success, and -1 for failure.
+ It can also return 0 to stop parsing network data and immediate exit
+ from PQisBusy function. The supplied
+ res and columns values
+ will stay valid so row can be processed outside of callback. Caller is
+ responsible for tracking whether the PQisBusy
+ returned because callback requested it or for other reasons. Usually
+ this should happen via setting cached values to NULL before calling
+ PQisBusy.
+
+
+
+ The function is allowed to exit via exception (eg: setjmp/longjmp).
+ The connection and row are guaranteed to be in valid state.
+ The connection can later be closed
+ via PQfinish. Processing can also be
+ continued without closing the connection, either with
+ getResult or PQisBusy.
+ Then processing will continue with next row, old row that got
+ exception will be skipped. Or you can discard all remaining
+ rows by calling PQskipResult.
+
+
+
+
+
+ res
+
+
+ A pointer to PGresult object that describes
+ the row structure.
+
+
+ This object is owned by PGconn
+ so callback must not free it.
+
+
+
+
+
+ columns
+
+
+ Column values of the row to process. Column values
+ are located in network buffer, the processor must
+ copy them out from there.
+
+
+ Column values are not null-terminated, so processor cannot
+ use C string functions on them directly.
+
+
+ This pointer is owned by PGconn
+ so callback must not free it.
+
+
+
+
+
+ param
+
+
+ Extra parameter that was given to
+ PQsetRowProcessor.
+
+
+
+
+
+
+
+
+
+
+ PQgetRowProcessor
+
+ PQgetRowProcessor
+
+
+
+
+ Get row processor and its context parameter currently set to
+ the connection.
+
+ PQrowProcessor PQgetRowProcessor(PGconn *conn, void **param);
+
+
+
+
+
+ conn
+
+
+ The connection object.
+
+
+
+
+
+ param
+
+
+ Location to store the extra parameter of current row processor.
+ If NULL, then parameter is not stored.
+
+
+
+
+
+
+
+
+
+
+
+ PQskipResult
+
+ PQskipResult
+
+
+
+
+ Discard all the remaining rows in incoming resultset.
+
+ int PQskipResult(PGconn *conn, int skipAll);
+
+
+
+ The function is simple convinience method to drop one or more
+ incoming resultsets. It is useful when handling exceptions
+ from row processor. It is implementing by simply calling
+ PQgetResult once or in a loop.
+
+
+ It returns 1 if the last PQgetResult
+ retutrned non-NULL. This can happen only when
+ skipAll is false.
+
+
+
+
+
+ conn
+
+
+ The connection object.
+
+
+
+
+
+ skipAll
+
+
+ If true, then PQgetResult
+ is called until it returns NULL. That means
+ there are no more incoming resultsets.
+
+
+ If false, PQgetResult is called
+ only once. The return value shows whether
+ there was result available or not.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Building <application>libpq</application> Programs