libpq_rowproc_doc_20120127.patch
text/x-patch
Filename: libpq_rowproc_doc_20120127.patch
Type: text/x-patch
Part: 1
Patch
Same data as JSON:
GET /api/v1/attachments/:id/patch
the parsed metadata as JSON — format, series position, per-file stats; never the diff bytes.
API reference →
Format: unified
| File | + | − |
|---|---|---|
| doc/src/sgml/libpq.sgml | 209 | 0 |
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 72c9384..9ad3bfd 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -7233,6 +7233,215 @@ int PQisthreadsafe(); </sect1> + <sect1 id="libpq-alterrowprocessor"> + <title>Alternative row processor</title> + + <indexterm zone="libpq-alterrowprocessor"> + <primary>PGresult</primary> + <secondary>PGconn</secondary> + </indexterm> + + <para> + As the standard usage, users can get the result of command + execution from <structname>PGresult</structname> aquired + with <function>PGgetResult</function> + from <structname>PGConn</structname>. While the memory areas for + the PGresult are allocated with malloc() internally within calls of + command execution functions such as <function>PQexec</function> + and <function>PQgetResult</function>. If you have difficulties to + handle the result records in the form of PGresult, you can instruct + PGconn to pass every row to your own row processor instead of + storing into PGresult. + </para> + + <variablelist> + <varlistentry id="libpq-registerrowprocessor"> + <term> + <function>PQregisterRowProcessor</function> + <indexterm> + <primary>PQregisterRowProcessor</primary> + </indexterm> + </term> + + <listitem> + <para> + Sets a callback function to process each row. +<synopsis> +void PQregisterRowProcessor(PGconn *conn, + RowProcessor func, + void *param); +</synopsis> + </para> + + <para> + <variablelist> + <varlistentry> + <term><parameter>conn</parameter></term> + <listitem> + <para> + The connection object to set the storage handler + function. PGresult created from this connection calls this + function to process each row. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>func</parameter></term> + <listitem> + <para> + Storage handler function to set. NULL means to use the + default processor. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>param</parameter></term> + <listitem> + <para> + A pointer to contextual parameter passed + to <parameter>func</parameter>. You can get this pointer + in <type>RowProcessor</type> + by <function>PQgetRowProcessorParam</function>. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry id="libpq-rowprocessor"> + <term> + <type>RowProcessor</type> + <indexterm> + <primary>RowProcessor</primary> + </indexterm> + </term> + + <listitem> + <para> + The type for the row processor callback function. +<synopsis> +void *(*RowProcessor)(PGresult *res, + PGresAttValue *columns); +</synopsis> + </para> + + <para> + Generally this function must return NULL for failure and should + set the error message + with <function>PGsetRowProcessorErrMes</function> if the cause + is other than out of memory. This funcion must not throw any + exception. + </para> + <variablelist> + <varlistentry> + <term><parameter>res</parameter></term> + <listitem> + <para> + A pointer to the <type>PGresult</type> object. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>columns</parameter></term> + <listitem> + <para> + An column values of the row to process. + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry id="libpq-pqgetrowprocessorparam"> + <term> + <function>PQgetRowProcessorParam</function> + <indexterm> + <primary>PQgetRowProcessorParam</primary> + </indexterm> + </term> + <listitem> + <para> + Get the pointer passed to <function>PQregisterRowProcessor</function> + as <parameter>param</parameter>. +<synopsis> +void *PQgetRowProcessorParam(PGresult *res) +</synopsis> + </para> + <para> + <variablelist> + <varlistentry> + <term><parameter>res</parameter></term> + <listitem> + <para> + A pointer to the <type>PGresult</type> object. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + + <variablelist> + <varlistentry id="libpq-pqsetrowprocessorerrmes"> + <term> + <function>PQsetRowProcessorErrMes</function> + <indexterm> + <primary>PQsetRowProcessorErrMes</primary> + </indexterm> + </term> + <listitem> + <para> + Set the message for the error occurred + in <type>RowProcessor</type>. If this message is not set, the + caller assumes the error to be out of memory. +<synopsis> +void PQsetRowProcessorErrMes(PGresult *res, char *mes) +</synopsis> + </para> + <para> + <variablelist> + <varlistentry> + <term><parameter>res</parameter></term> + <listitem> + <para> + A pointer to the <type>PGresult</type> object + passed to <type>RowProcessor</type>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>mes</parameter></term> + <listitem> + <para> + A pointer to the memory block containing the error message, + which is allocated by <function>malloc()</function>. The + memory block will be freed with <function>free()</function> in + the caller of <type>RowProcessor</type> only if it returns NULL. + </para> + <para> + If <parameter>res</parameter> already has a message previously + set, it is freed and then the given message is set. Set NULL + to cancel the the costom message. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="libpq-build"> <title>Building <application>libpq</application> Programs</title>