Minor updates to libpq documentation.

Author: tglsfdc

doc/src/sgml/libpq.sgml

@@ -430,6 +430,24 @@ PGRES_FATAL_ERROR
 </Para>
 </ListItem>
 
+<ListItem>
+<Para>
+<Function>PQresStatus</Function>
+	Converts the enumerated type returned by PQresultStatus into
+	a string constant describing the status code.
+<synopsis>
+const char *PQresStatus(ExecStatusType status);
+</synopsis>
+Older code may perform this same operation by direct access to a constant
+string array inside libpq,
+<synopsis>
+extern const char * const pgresStatus[];
+</synopsis>
+However, using the function is recommended instead, since it is more portable
+and will not fail on out-of-range values.
+</Para>
+</ListItem>
+
 <ListItem>
 <Para>
 <Function>PQresultErrorMessage</Function>
@@ -910,8 +928,7 @@ terms is readable data on the file descriptor identified by PQsocket.
 When the main loop detects input ready, it should call PQconsumeInput
 to read the input.  It can then call PQisBusy, followed by PQgetResult
 if PQisBusy returns FALSE.  It can also call PQnotifies to detect NOTIFY
-messages (see "Asynchronous Notification", below).  An example is given
-in the sample programs section.
+messages (see "Asynchronous Notification", below).
 </Para>
 
 <Para>
@@ -1230,10 +1247,10 @@ int PQendcopy(PGconn *conn);
 As an example:
 
 <ProgramListing>
-PQexec(conn, "create table foo (a int4, b char16, d float8)");
+PQexec(conn, "create table foo (a int4, b char(16), d float8)");
 PQexec(conn, "copy foo from stdin");
-PQputline(conn, "3&lt;TAB&gt;hello world&lt;TAB&gt;4.5\n");
-PQputline(conn,"4&lt;TAB&gt;goodbye world&lt;TAB&gt;7.11\n");
+PQputline(conn, "3\thello world\t4.5\n");
+PQputline(conn,"4\tgoodbye world\t7.11\n");
 ...
 PQputline(conn,"\\.\n");
 PQendcopy(conn);
@@ -1671,22 +1688,25 @@ main()
 <Para>
 <ProgramListing>
 /*
- * testlibpq2.c Test of the asynchronous notification interface
- *
- * populate a database with the following:
+ * testlibpq2.c
+ *  Test of the asynchronous notification interface
  *
- * CREATE TABLE TBL1 (i int4);
+ * Start this program, then from psql in another window do
+ *   NOTIFY TBL2;
  *
- * CREATE TABLE TBL2 (i int4);
+ * Or, if you want to get fancy, try this:
+ * Populate a database with the following:
  *
- * CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values
- * (new.i); NOTIFY TBL2];
+ *   CREATE TABLE TBL1 (i int4);
  *
- * Then start up this program After the program has begun, do
+ *   CREATE TABLE TBL2 (i int4);
  *
- * INSERT INTO TBL1 values (10);
+ *   CREATE RULE r1 AS ON INSERT TO TBL1 DO
+ *     (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
  *
+ * and do
  *
+ *   INSERT INTO TBL1 values (10);
  *
  */
 #include &lt;stdio.h&gt;

src/man/libpq.3

@@ -1,6 +1,6 @@
 .\" This is -*-nroff-*-
 .\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.26 1999/04/17 17:18:41 momjian Exp $
+.\" $Header: /cvsroot/pgsql/src/man/Attic/libpq.3,v 1.27 1999/05/21 00:36:01 tgl Exp $
 .TH LIBPQ INTRO 08/08/98 PostgreSQL PostgreSQL
 .SH DESCRIPTION
 Current documentation for this topic is available in the new Programmer's Guide
@@ -266,9 +266,44 @@ PGRES_NONFATAL_ERROR,
 PGRES_FATAL_ERROR
 .fi
 .IP
-If the result status is PGRES_TUPLES_OK, then the following routines can
-be used to retrieve the tuples returned by the query.
+If  the result status is PGRES_TUPLES_OK, then the
+routines described below can be  used  to  retrieve  the
+tuples returned by the query.  Note that a SELECT that
+happens to retrieve zero tuples still shows PGRES_TUPLES_OK.
+PGRES_COMMAND_OK is for commands that can never return tuples.
+.PP
+.B PQresStatus
+.IP
+Converts the enumerated type returned by PQresultStatus into
+a string constant describing the status code.
+.nf
+const char *PQresStatus(ExecStatusType status);
+.fi
+.IP
+Older code may perform this same operation by direct access to a constant
+string array inside libpq,
+.nf
+extern const char * const pgresStatus[];
+.fi
+.IP
+However, using the function is recommended instead, since it is more portable
+and will not fail on out-of-range values.
+.PP
+.B PQresultErrorMessage
+.IP
+returns the error message associated with the query, or an empty string
+if there was no error.
+.nf
+const char *PQresultErrorMessage(PGresult *res);
+.fi
 .IP
+Immediately following a PQexec or PQgetResult call, PQerrorMessage
+(on the connection) will return the same string as PQresultErrorMessage
+(on the result).  However, a PGresult will retain its error message
+until destroyed, whereas the connection's error message will change when
+subsequent operations are done.  Use PQresultErrorMessage when you want to
+know the status associated with a particular PGresult; use PQerrorMessage
+when you want to know the status from the latest operation on the connection.
 
 .B PQntuples
 returns the number of tuples (instances) in the query result.
@@ -558,8 +593,7 @@ terms is readable data on the file descriptor identified by PQsocket.
 When the main loop detects input ready, it should call PQconsumeInput
 to read the input.  It can then call PQisBusy, followed by PQgetResult
 if PQisBusy returns FALSE.  It can also call PQnotifies to detect NOTIFY
-messages (see "Asynchronous Notification", below).  An example is given
-in the sample programs section.
+messages (see "Asynchronous Notification", below).
 
 .PP
 A frontend that uses PQsendQuery/PQgetResult can also attempt to cancel
@@ -789,12 +823,12 @@ int PQendcopy(PGconn *conn);
 .fi
 As an example:
 .nf
-PQexec(conn, "create table foo (a int4, b name, d float8)");
+PQexec(conn, "create table foo (a int4, b char(16), d float8)");
 PQexec(conn, "copy foo from stdin");
-PQputline(conn, "3<TAB>hello world<TAB>4.5\en");
-PQputline(conn,"4<TAB>goodbye world<TAB>7.11\en");
+PQputline(conn, "3\ethello world\et4.5\en");
+PQputline(conn,"4\etgoodbye world\et7.11\en");
 \&...
-PQputline(conn,"\\.\en");
+PQputline(conn,"\e\e.\en");
 PQendcopy(conn);
 .fi
 .PP
@@ -1048,20 +1082,22 @@ main()
  * testlibpq2.c
  *  Test of the asynchronous notification interface
  *
-   populate a database with the following:
-
-CREATE TABLE TBL1 (i int4);
-
-CREATE TABLE TBL2 (i int4);
-
-CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];
-
- * Then start up this program
- * After the program has begun, do
-
-INSERT INTO TBL1 values (10);
-
+ * Start this program, then from psql in another window do
+ *   NOTIFY TBL2;
+ *
+ * Or, if you want to get fancy, try this:
+ * Populate a database with the following:
+ *
+ *   CREATE TABLE TBL1 (i int4);
+ *
+ *   CREATE TABLE TBL2 (i int4);
+ *
+ *   CREATE RULE r1 AS ON INSERT TO TBL1 DO
+ *     (INSERT INTO TBL2 values (new.i); NOTIFY TBL2);
+ *
+ * and do
  *
+ *   INSERT INTO TBL1 values (10);
  *
  */
 #include <stdio.h>