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>