libpq_altstore_doc_20120117.patch

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 72c9384..8803999 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -7233,6 +7233,293 @@ int PQisthreadsafe();
  </sect1>
 
 
+ <sect1 id="libpq-alterstorage">
+  <title>Alternative result storage</title>
+
+  <indexterm zone="libpq-alterstorage">
+   <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 store them into your own storage instead of PGresult.
+  </para>
+
+  <variablelist>
+   <varlistentry id="libpq-registerstorehandler">
+    <term>
+     <function>PQregisterStoreHandler</function>
+     <indexterm>
+      <primary>PQregisterStoreHandler</primary>
+     </indexterm>
+    </term>
+
+    <listitem>
+     <para>
+       Sets a callback function to allocate memory for each tuple and
+       column values, and add the complete tuple into the alternative
+       result storage.
+<synopsis>
+void PQregisterStoreHandler(PGconn *conn,
+                            StoreHandler 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 store the result instead of storing into its
+	       internal storage.
+	     </para>
+	   </listitem>
+	 </varlistentry>
+	 <varlistentry>
+	   <term><parameter>func</parameter></term>
+	   <listitem>
+	     <para>
+	       Storage handler function to set. NULL means to use the
+	       default storage.
+	     </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 poiner
+	       in <type>StoreHandler</type>
+	       by <function>PQgetStoreHandlerParam</function>.
+	     </para>
+	   </listitem>
+	 </varlistentry>
+       </variablelist>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <variablelist>
+   <varlistentry id="libpq-storehandler">
+    <term>
+     <type>Storehandler</type>
+     <indexterm>
+      <primary>StoreHandler</primary>
+     </indexterm>
+    </term>
+
+    <listitem>
+     <para>
+       The type for the storage handler callback function.
+<synopsis>
+typedef enum 
+{
+  PQSF_ALLOC_TEXT,
+  PQSF_ALLOC_BINARY,
+  PQSF_ADD_TUPLE
+} PQStoreFunc;
+
+void *(*StoreHandler)(PGresult *res,
+                      PQStoreFunc func,
+                      int id,
+                      size_t size);
+</synopsis>
+     </para>
+
+     <para>
+       Generally this function must return NULL for failure and should
+       set the error message
+       with <function>PGsetStoreHandlerErrMes</function> if the cause
+       is other than out of memory. This funcion must not throw any
+       exception. This function is called in the sequence following.
+
+       <itemizedlist spacing="compact">
+	 <listitem>
+	   <simpara>Call with <parameter>func</parameter>
+	   = <firstterm>PQSF_ALLOC_BINARY</firstterm>
+	   and <parameter>id</parameter> = -1 to request the memory
+	   for a tuple to be used as an array
+	   of <type>PGresAttValue</type>. </simpara>
+	 </listitem>
+	 <listitem>
+	   <simpara>Call with <parameter>func</parameter>
+	   = <firstterm>PQSF_ALLOC_TEXT</firstterm>
+	   or <firstterm>PQSF_ALLOC_BINARY</firstterm>
+	   and <parameter>id</parameter> is zero to the number of columns
+	   - 1 to request the memory for each column value in current
+	   tuple.</simpara>
+	 </listitem>
+	 <listitem>
+	   <simpara>Call with <parameter>func</parameter>
+	   = <firstterm>PQSF_ADD_TUPLE</firstterm> to request the
+	   constructed tuple to be stored.</simpara>
+	 </listitem>
+       </itemizedlist>
+     </para>
+     <para>
+       Calling <type>StoreHandler</type>
+       with <parameter>func</parameter> =
+       <firstterm>PQSF_ALLOC_TEXT</firstterm> is telling to return a
+        memory block with at least <parameter>size</parameter> bytes
+        which may not be aligned to the word boundary.
+       <parameter>id</parameter> is a zero or positive number
+       distinguishes the usage of requested memory block, that is the
+       position of the column for which the memory block is used.
+     </para>
+     <para>
+       When <parameter>func</parameter>
+       = <firstterm>PQSF_ALLOC_BINARY</firstterm>, this function is
+       telled to return a memory block with at
+       least <parameter>size</parameter> bytes which is aligned to the
+       word boundary.
+       <parameter>id</parameter> is the identifier distinguishes the
+       usage of requested memory block. -1 means that it is used as an
+       array of <type>PGresAttValue</type> to store the tuple. Zero or
+       positive numbers have the same meanings as for
+       <firstterm>PQSF_ALLOC_BINARY</firstterm>.
+     </para>
+     <para>When <parameter>func</parameter>
+       = <firstterm>PQSF_ADD_TUPLE</firstterm>, this function is
+       telled to store the <type>PGresAttValue</type> structure
+       constructed by the caller into your storage. The pointer to the
+       tuple structure is not passed so you should memorize the
+       pointer to the memory block passed back the caller on
+       <parameter>func</parameter>
+       = <parameter>PQSF_ALLOC_BINARY</parameter>
+       with <parameter>id</parameter> is -1. This function must return
+       any non-NULL values for success. You must properly put back the
+       memory blocks passed to the caller in this function if needed.
+     </para>
+     <variablelist>
+       <varlistentry>
+	 <term><parameter>res</parameter></term>
+	 <listitem>
+	   <para>
+	     A pointer to the <type>PGresult</type> object.
+	   </para>
+	 </listitem>
+       </varlistentry>
+       <varlistentry>
+	 <term><parameter>func</parameter></term>
+	 <listitem>
+	   <para>
+	     An <type>enum</type> value telling the function to perform.
+	   </para>
+	 </listitem>
+       </varlistentry>
+       <varlistentry>
+	 <term><parameter>param</parameter></term>
+	 <listitem>
+	   <para>
+	     A pointer to contextual parameter passed to func.
+	   </para>
+	 </listitem>
+       </varlistentry>
+     </variablelist>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
+  <variablelist>
+   <varlistentry id="libpq-pqgetstorehandlerparam">
+    <term>
+     <function>PQgetStoreHandlerParam</function>
+     <indexterm>
+      <primary>PQgetStoreHandlerParam</primary>
+     </indexterm>
+    </term>
+    <listitem>
+      <para>
+	Get the pointer passed to <function>PQregisterStoreHandler</function>
+	as <parameter>param</parameter>.
+<synopsis>
+void *PQgetStoreHandlerParam(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-pqsetstorehandlererrmes">
+    <term>
+     <function>PQsetStoreHandlerErrMes</function>
+     <indexterm>
+      <primary>PQsetStoreHandlerErrMes</primary>
+     </indexterm>
+    </term>
+    <listitem>
+      <para>
+	Set the message for the error occurred
+	in <type>StoreHandler</type>.  If this message is not set, the
+	caller assumes the error to be out of memory.
+<synopsis>
+void PQsetStoreHandlerErrMes(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>StoreHandler</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>StoreHandler</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>