libpq/libpq++ result function reorganization - Mailing list pgsql-patches

I have applied the following patch to the docs.  Previously, all the
PQexec() result functions where listed in one long list which I found
hard to understand.

I created subsections, <sect2>, for main routines, SELECT information
routines, SELECT value routines, and non-SELECT routines.

I did this for libpq and libpq++.  The other interfaces didn't have this
problem.

Tweeking welcomed.  I tested the HTML output here with my old sgmltools
install and it looked OK.

--
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026
Index: doc/src/sgml/libpq++.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/libpq++.sgml,v
retrieving revision 1.25
diff -c -r1.25 libpq++.sgml
*** doc/src/sgml/libpq++.sgml    2001/04/30 04:26:01    1.25
--- doc/src/sgml/libpq++.sgml    2001/04/30 17:18:22
***************
*** 283,288 ****
--- 283,291 ----

    <sect1 id="libpqpp-exec">
     <title>Query Execution Functions</title>
+
+ <sect2 id="libpqpp-exec-main">
+   <title>Main Routines</title>
     <para>
      <itemizedlist>
       <listitem>
***************
*** 352,357 ****
--- 355,367 ----
         </synopsis>
        </para>
       </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="libpqpp-exec-select-info">
+   <title>Retrieving SELECT Result Information</title>
+
+ <itemizedlist>
       <listitem>
        <para>
         <function>Tuples</function>
***************
*** 363,378 ****
       </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>
         Returns the number of fields (attributes) in each tuple of the query result.
         <synopsis>
--- 373,378 ----
***************
*** 451,456 ****
--- 451,464 ----
         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,567 ****
         </synopsis>
        </para>
       </listitem>
       <listitem>
        <para>
!        <function>GetLine</function>
         <synopsis>
!     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>
       <listitem>
        <para>
!        <function>OidStatus</function>
         <synopsis>
!     const char *PgDatabase::OidStatus()
         </synopsis>
        </para>
       </listitem>
--- 549,600 ----
         </synopsis>
        </para>
       </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="libpqpp-exec-nonselect">
+   <title>Retrieving Non-SELECT Result Information</title>
+
+ <itemizedlist>
       <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>OidStatus</function>
         <synopsis>
!     const char *PgDatabase::OidStatus()
         </synopsis>
        </para>
       </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="libpqpp-exec-copy">
+   <title>Handling COPY Queries</title>
+
+ <itemizedlist>
       <listitem>
        <para>
!        <function>GetLine</function>
         <synopsis>
!     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,581 ****
       </listitem>
      </itemizedlist>
     </para>
!   </sect1>

    <sect1 id="libpqpp-notify">
     <title>Asynchronous Notification</title>
--- 608,616 ----
       </listitem>
      </itemizedlist>
     </para>
! </itemizedlist>
! </sect2>
! </sect1>

    <sect1 id="libpqpp-notify">
     <title>Asynchronous Notification</title>
Index: doc/src/sgml/libpq.sgml
===================================================================
RCS file: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/libpq.sgml,v
retrieving revision 1.59
diff -c -r1.59 libpq.sgml
*** doc/src/sgml/libpq.sgml    2001/03/21 19:09:03    1.59
--- doc/src/sgml/libpq.sgml    2001/04/30 17:18:33
***************
*** 696,701 ****
--- 696,703 ----
  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>
***************
*** 809,814 ****
--- 811,856 ----

  <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>
            Returns the number of tuples (rows)
            in the query result.
***************
*** 829,851 ****
  </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.
   Field  indices start at 0.
  <synopsis>
  char *PQfname(const PGresult *res,
--- 871,881 ----
  </para>
  </listitem>


  <listitem>
  <para>
  <function>PQfname</function>
!  Returns the field (attribute) name associated with the given field index.
   Field  indices start at 0.
  <synopsis>
  char *PQfname(const PGresult *res,
***************
*** 890,895 ****
--- 920,938 ----

  <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>
            Returns  the  size  in bytes of the field
            associated with the given field index.
***************
*** 902,922 ****
      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.
  <synopsis>
! int PQfmod(const PGresult *res,
!            int field_index);
  </synopsis>
  </para>
  </listitem>

  <listitem>
  <para>
  <function>PQgetvalue</function>
--- 945,972 ----
      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>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>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="libpq-exec-select-values">
+   <title>Retrieving SELECT Result Values</title>

+ <itemizedlist>
  <listitem>
  <para>
  <function>PQgetvalue</function>
***************
*** 947,954 ****

  <listitem>
  <para>
  <function>PQgetlength</function>
!           Returns   the   length  of  a  field (attribute) in bytes.
            Tuple and field indices start at 0.
  <synopsis>
  int PQgetlength(const PGresult *res,
--- 997,1021 ----

  <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) value in bytes.
            Tuple and field indices start at 0.
  <synopsis>
  int PQgetlength(const PGresult *res,
***************
*** 963,983 ****

  <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>PQcmdStatus</function>
--- 1030,1068 ----

  <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>
+ </itemizedlist>
+ </sect2>

+ <sect2 id="libpq-exec-nonselect">
+   <title>Retrieving Non-SELECT Result Information</title>
+
+ <itemizedlist>
  <listitem>
  <para>
  <function>PQcmdStatus</function>
***************
*** 1032,1101 ****
  </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>
  </para>
  </sect1>

--- 1117,1125 ----
  </para>
  </listitem>


  </itemizedlist>
+ </sect2>
  </para>
  </sect1>