*** a/doc/src/sgml/libpq.sgml
--- b/doc/src/sgml/libpq.sgml
***************
*** 7233,7238 **** int PQisthreadsafe();
--- 7233,7443 ----
+
+ Alternative row processor
+
+
+ PGresult
+ PGconn
+
+
+
+ As the standard usage, rows are stored into PQresult
+ until full resultset is received. Then such completely-filled
+ PQresult is passed to user. This behaviour 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, void *param, PGrowValue *columns);
+
+ typedef struct
+ {
+ int len; /* length in bytes of the value */
+ char *value; /* actual value, without null termination */
+ } PGrowValue;
+
+
+
+
+ The columns array will have PQnfields()
+ elements, each one pointing to column value in network buffer.
+
+
+
+ This function must process or copy row values away from network
+ buffer before it returns, as next row might overwrite them.
+
+
+
+ This function must return 1 for success, and 0 for failure.
+ On failure this function should set the error message
+ with PGsetRowProcessorErrMsg if the cause
+ is other than out of memory. This funcion must not throw any
+ exception.
+
+
+
+
+ res
+
+
+ A pointer to the PGresult object.
+
+
+
+
+
+ param
+
+
+ Extra parameter that was given to PQsetRowProcessor.
+
+
+
+
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+ PQsetRowProcessorErrMsg
+
+ PQsetRowProcessorErrMsg
+
+
+
+
+ Set the message for the error occurred
+ in PQrowProcessor. If this message is not set, the
+ caller assumes the error to be out of memory.
+
+ void PQsetRowProcessorErrMsg(PGresult *res, char *msg)
+
+
+
+
+
+ res
+
+
+ A pointer to the PGresult object
+ passed to PQrowProcessor.
+
+
+
+
+ mes
+
+
+ Error message. This will be copied internally so there is
+ no need to care of the scope.
+
+
+ If res already has a message previously
+ set, it will be overritten. Set NULL to cancel the the costom
+ message.
+
+
+
+
+
+
+
+
+
+
+
Building <application>libpq</application> Programs