Break up PQexec() result functions into subsections to be clearer. Both

libpq and libpq++ reorganized.

diff --git a/doc/src/sgml/libpq++.sgml b/doc/src/sgml/libpq++.sgml
index 06ab5238a8afd9361ed9766cc98abc6973ba1f49..5e899d5c5464ec84ca80c227f08e3ca4b06d797f 100644 (file)
--- a/doc/src/sgml/libpq++.sgml
+++ b/doc/src/sgml/libpq++.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:01 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.26 2001/04/30 17:38:00 momjian Exp $
 -->
 
  <chapter id="libpqplusplus">
@@ -283,6 +283,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
 
   <sect1 id="libpqpp-exec">
    <title>Query Execution Functions</title>
+
+<sect2 id="libpqpp-exec-main">
+  <title>Main Routines</title>
    <para>  
     <itemizedlist>
      <listitem>
@@ -352,6 +355,13 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
        </synopsis>
       </para>
      </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="libpqpp-exec-select-info">
+  <title>Retrieving SELECT Result Information</title>
+
+<itemizedlist>
      <listitem>
       <para>
        <function>Tuples</function>
@@ -361,16 +371,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
        </synopsis>
       </para>
      </listitem>
-     <listitem>
-      <para>
-       <function>CmdTuples</function>
-              Returns the number of rows affected after an INSERT, UPDATE or DELETE. 
-              If the command was anything else, it returns -1. 
-       <synopsis>
-      int PgDatabase::CmdTuples()
-       </synopsis>
-      </para>
-     </listitem>
      <listitem>
       <para>
        <function>Fields</function>
@@ -451,6 +451,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
        variable size.
       </para>
      </listitem>
+</itemizedlist>
+</sect2>
+
+
+<sect2 id="libpqpp-exec-select-values">
+  <title>Retrieving SELECT Result Values</title>
+
+<itemizedlist>
      <listitem>
       <para>
        <function>GetValue</function>
@@ -541,27 +549,52 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
        </synopsis>
       </para>
      </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="libpqpp-exec-nonselect">
+  <title>Retrieving Non-SELECT Result Information</title>
+
+<itemizedlist>
      <listitem>
       <para>
-       <function>GetLine</function>
+       <function>CmdTuples</function>
+              Returns the number of rows affected after an INSERT, UPDATE or DELETE. 
+              If the command was anything else, it returns -1. 
        <synopsis>
-       int PgDatabase::GetLine(char* string, int length)
+      int PgDatabase::CmdTuples()
        </synopsis>
       </para>
      </listitem>
+
      <listitem>
       <para>
-       <function>PutLine</function>
+       <function>OidStatus</function>
        <synopsis>
-       void PgDatabase::PutLine(const char* string)
+       const char *PgDatabase::OidStatus()
        </synopsis>
       </para>
      </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="libpqpp-exec-copy">
+  <title>Handling COPY Queries</title>
+
+<itemizedlist>
      <listitem>
       <para>
-       <function>OidStatus</function>
+       <function>GetLine</function>
        <synopsis>
-       const char *PgDatabase::OidStatus()
+       int PgDatabase::GetLine(char* string, int length)
+       </synopsis>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       <function>PutLine</function>
+       <synopsis>
+       void PgDatabase::PutLine(const char* string)
        </synopsis>
       </para>
      </listitem>
@@ -575,7 +608,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpq++.sgml,v 1.25 2001/04/30 04:26:
      </listitem>
     </itemizedlist>
    </para>
-  </sect1>
+</itemizedlist>
+</sect2>
+</sect1>
 
   <sect1 id="libpqpp-notify">
    <title>Asynchronous Notification</title>

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 003a4dd5c142907b5080f8f485b5ea14ae9c7edc..94fdd42a01d082db3ee5a046240e42c89655e738 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.59 2001/03/21 19:09:03 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.60 2001/04/30 17:38:00 momjian Exp $
 -->
 
  <chapter id="libpq">
@@ -696,6 +696,8 @@ SSL *PQgetssl(const PGconn *conn);
 Once a connection to a database server has been successfully
 established, the functions described here are used to perform
 SQL queries and commands.
+<sect2 id="libpq-exec-main">
+  <title>Main Routines</title>
 <itemizedlist>
 <listitem>
 <para>
@@ -807,6 +809,46 @@ when you want to know the status from the latest operation on the connection.
 </para>
 </listitem>
 
+<listitem>
+<para>
+<function>PQclear</function>
+          Frees  the  storage  associated with the PGresult.
+          Every query result should be freed via PQclear  when
+          it  is  no  longer needed.
+<synopsis>
+void PQclear(PQresult *res);
+</synopsis>
+          You can keep a PGresult object around for as long as you
+          need it; it does not go away when you issue a new query,
+          nor even if you close the connection.  To get rid of it,
+          you must call <function>PQclear</function>.  Failure to do this will
+          result in memory leaks in  the  frontend  application.
+</para>
+</listitem>
+
+<listitem>
+<para>
+<function>PQmakeEmptyPGresult</function>
+          Constructs an empty PGresult object with the given status.
+<synopsis>
+PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
+</synopsis>
+This is libpq's internal routine to allocate and initialize an empty
+PGresult object.  It is exported because some applications find it
+useful to generate result objects (particularly objects with error
+status) themselves.  If conn is not NULL and status indicates an error,
+the connection's current errorMessage is copied into the PGresult.
+Note that PQclear should eventually be called on the object, just
+as with a PGresult returned by libpq itself.
+</para>
+</listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="libpq-exec-select-info">
+  <title>Retrieving SELECT Result Information</title>
+
+<itemizedlist>
 <listitem>
 <para>
 <function>PQntuples</function>
@@ -829,23 +871,11 @@ int PQnfields(const PGresult *res);
 </para>
 </listitem>
 
-<listitem>
-<para>
-<function>PQbinaryTuples</function>
-          Returns 1 if the PGresult contains binary tuple data,
-         0 if it contains ASCII data.
-<synopsis>
-int PQbinaryTuples(const PGresult *res);
-</synopsis>
-Currently, binary tuple data can only be returned by a query that
-extracts data from a <acronym>BINARY</acronym> cursor.
-</para>
-</listitem>
 
 <listitem>
 <para>
 <function>PQfname</function>
- Returns the field (attribute) name associated with the given field  index.
+ Returns the field (attribute) name associated with the given field index.
  Field  indices start at 0.
 <synopsis>
 char *PQfname(const PGresult *res,
@@ -888,6 +918,19 @@ in the source tree.
 </para>
 </listitem>
 
+<listitem>
+<para>
+<function>PQfmod</function>
+          Returns  the type-specific modification data of the field
+          associated with the given field index.
+          Field indices start at 0.
+<synopsis>
+int PQfmod(const PGresult *res,
+           int field_index);
+</synopsis>
+</para>
+</listitem>
+
 <listitem>
 <para>
 <function>PQfsize</function>
@@ -902,21 +945,28 @@ int PQfsize(const PGresult *res,
        tuple, in other words the size of the server's binary representation
        of the data type.  -1 is returned if the field is variable size.
 </para>
+
 </listitem>
 
 <listitem>
 <para>
-<function>PQfmod</function>
-          Returns  the type-specific modification data of the field
-          associated with the given field index.
-          Field indices start at 0.
+<function>PQbinaryTuples</function>
+          Returns 1 if the PGresult contains binary tuple data,
+         0 if it contains ASCII data.
 <synopsis>
-int PQfmod(const PGresult *res,
-           int field_index);
+int PQbinaryTuples(const PGresult *res);
 </synopsis>
+Currently, binary tuple data can only be returned by a query that
+extracts data from a <acronym>BINARY</acronym> cursor.
 </para>
 </listitem>
+</itemizedlist>
+</sect2>
+
+<sect2 id="libpq-exec-select-values">
+  <title>Retrieving SELECT Result Values</title>
 
+<itemizedlist>
 <listitem>
 <para>
 <function>PQgetvalue</function>
@@ -945,10 +995,27 @@ be used past the lifetime of the  PGresult  structure itself.
 </para>
 </listitem>
 
+<listitem>
+<para>
+<function>PQgetisnull</function>
+           Tests a field for a NULL entry.
+           Tuple and field indices start at 0.
+<synopsis>
+int PQgetisnull(const PGresult *res,
+                int tup_num,
+                int field_num);
+</synopsis>
+            This function returns  1 if the field contains a NULL, 0 if
+            it contains a non-null value.  (Note that PQgetvalue
+            will return an empty string, not a null pointer, for a NULL
+            field.)
+</para>
+</listitem>
+
 <listitem>
 <para>
 <function>PQgetlength</function>
-          Returns   the   length  of  a  field (attribute) in bytes.
+          Returns   the   length  of  a  field (attribute) value in bytes.
           Tuple and field indices start at 0.
 <synopsis>
 int PQgetlength(const PGresult *res,
@@ -963,21 +1030,39 @@ values, this size has little to do with the binary size reported by PQfsize.
 
 <listitem>
 <para>
-<function>PQgetisnull</function>
-           Tests a field for a NULL entry.
-           Tuple and field indices start at 0.
-<synopsis>
-int PQgetisnull(const PGresult *res,
-                int tup_num,
-                int field_num);
-</synopsis>
-            This function returns  1 if the field contains a NULL, 0 if
-            it contains a non-null value.  (Note that PQgetvalue
-            will return an empty string, not a null pointer, for a NULL
-            field.)
+<function>PQprint</function>
+          Prints out all the  tuples  and,  optionally,  the
+          attribute  names  to  the specified output stream.
+       <synopsis>
+void PQprint(FILE* fout,      /* output stream */
+             const PGresult *res,
+             const PQprintOpt *po);
+
+struct {
+    pqbool  header;      /* print output field headings and row count */
+    pqbool  align;       /* fill align the fields */
+    pqbool  standard;    /* old brain dead format */
+    pqbool  html3;       /* output html tables */
+    pqbool  expanded;    /* expand tables */
+    pqbool  pager;       /* use pager for output if needed */
+    char    *fieldSep;   /* field separator */
+    char    *tableOpt;   /* insert to HTML <replaceable>table ...</replaceable> */
+    char    *caption;    /* HTML <replaceable>caption</replaceable> */
+    char    **fieldName; /* null terminated array of replacement field names */
+} PQprintOpt;
+       </synopsis>
+This function was formerly used by <application>psql</application>
+to print query results, but this is no longer the case and this
+function is no longer actively supported.
 </para>
 </listitem>
+</itemizedlist>
+</sect2>
 
+<sect2 id="libpq-exec-nonselect">
+  <title>Retrieving Non-SELECT Result Information</title>
+
+<itemizedlist>
 <listitem>
 <para>
 <function>PQcmdStatus</function>
@@ -1032,70 +1117,9 @@ and is not thread-safe.
 </para>
 </listitem>
 
-<listitem>
-<para>
-<function>PQprint</function>
-          Prints out all the  tuples  and,  optionally,  the
-          attribute  names  to  the specified output stream.
-       <synopsis>
-void PQprint(FILE* fout,      /* output stream */
-             const PGresult *res,
-             const PQprintOpt *po);
-
-struct {
-    pqbool  header;      /* print output field headings and row count */
-    pqbool  align;       /* fill align the fields */
-    pqbool  standard;    /* old brain dead format */
-    pqbool  html3;       /* output html tables */
-    pqbool  expanded;    /* expand tables */
-    pqbool  pager;       /* use pager for output if needed */
-    char    *fieldSep;   /* field separator */
-    char    *tableOpt;   /* insert to HTML <replaceable>table ...</replaceable> */
-    char    *caption;    /* HTML <replaceable>caption</replaceable> */
-    char    **fieldName; /* null terminated array of replacement field names */
-} PQprintOpt;
-       </synopsis>
-This function was formerly used by <application>psql</application>
-to print query results, but this is no longer the case and this
-function is no longer actively supported.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>PQclear</function>
-          Frees  the  storage  associated with the PGresult.
-          Every query result should be freed via PQclear  when
-          it  is  no  longer needed.
-<synopsis>
-void PQclear(PQresult *res);
-</synopsis>
-          You can keep a PGresult object around for as long as you
-          need it; it does not go away when you issue a new query,
-          nor even if you close the connection.  To get rid of it,
-          you must call <function>PQclear</function>.  Failure to do this will
-          result in memory leaks in  the  frontend  application.
-</para>
-</listitem>
-
-<listitem>
-<para>
-<function>PQmakeEmptyPGresult</function>
-          Constructs an empty PGresult object with the given status.
-<synopsis>
-PGresult* PQmakeEmptyPGresult(PGconn *conn, ExecStatusType status);
-</synopsis>
-This is libpq's internal routine to allocate and initialize an empty
-PGresult object.  It is exported because some applications find it
-useful to generate result objects (particularly objects with error
-status) themselves.  If conn is not NULL and status indicates an error,
-the connection's current errorMessage is copied into the PGresult.
-Note that PQclear should eventually be called on the object, just
-as with a PGresult returned by libpq itself.
-</para>
-</listitem>
 
 </itemizedlist>
+</sect2>
 </para>
 </sect1>