From 60ba30d13a3b2fb2a95d0f9b2a450b21b3a93bb8 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Mon, 30 Apr 2001 17:38:00 +0000
Subject: [PATCH] Break up PQexec() result functions into subsections to be
clearer. Both libpq and libpq++ reorganized.
---
doc/src/sgml/libpq++.sgml | 71 +++++++++----
doc/src/sgml/libpq.sgml | 214 +++++++++++++++++++++-----------------
2 files changed, 172 insertions(+), 113 deletions(-)
diff --git a/doc/src/sgml/libpq++.sgml b/doc/src/sgml/libpq++.sgml
index 06ab5238a8a..5e899d5c546 100644
--- 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 003a4dd5c14..94fdd42a01d 100644
--- 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>
--
GitLab