Improve documentation for SQLSTATE error codes, per recent thread on

-patches.

2 files changed, 34 insertions, 21 deletions

diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml
index 3afb85ec794..2f211f462e8 100644
--- a/doc/src/sgml/errcodes.sgml
+++ b/doc/src/sgml/errcodes.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/errcodes.sgml,v 1.3 2004/03/04 21:47:18 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/errcodes.sgml,v 1.4 2004/05/14 18:04:02 neilc Exp $ -->
 
 <appendix id="errcodes-appendix">
  <title><productname>PostgreSQL</productname> Error Codes</title>
@@ -9,13 +9,18 @@
  </indexterm>
 
  <para>
-  All messages emitted by the <productname>PostgreSQL</productname> server
-  are assigned five-character error codes that follow the SQL standard's
-  conventions for <quote>SQLSTATE</> codes.  Applications that need to know
-  which error condition has occurred should usually test the error code,
-  rather than looking at the textual error message.  The error codes are
-  less likely to change across <productname>PostgreSQL</productname> releases,
-  and also are not subject to change due to localization of error messages.
+  All messages emitted by the <productname>PostgreSQL</productname>
+  server are assigned five-character error codes that follow the SQL
+  standard's conventions for <quote>SQLSTATE</> codes.  Applications
+  that need to know which error condition has occurred should usually
+  test the error code, rather than looking at the textual error
+  message.  The error codes are less likely to change across
+  <productname>PostgreSQL</> releases, and also are not subject to
+  change due to localization of error messages. Note that some, but
+  not all, of the error codes produced by <productname>PostgreSQL</>
+  are defined by the SQL standard; some additional error codes for
+  conditions not defined by the standard have been invented or
+  borrowed from other databases.
  </para>
 
  <para>
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 99bba6059d8..2eaa4da341b 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.154 2004/04/24 22:58:40 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.155 2004/05/14 18:04:02 neilc Exp $
 -->
 
  <chapter id="libpq">
@@ -1336,12 +1336,20 @@ localized translation of one of these.  Always present.
 </varlistentry>
 
 <varlistentry>
+ <indexterm>
+  <primary>error codes</primary>
+  <secondary>libpq</secondary>
+ </indexterm>
 <term><symbol>PG_DIAG_SQLSTATE</>
 </term>
 <listitem>
 <para>
-The SQLSTATE code for the error (see <xref linkend="errcodes-appendix">).
-Not localizable.  Always present.
+The SQLSTATE code for the error. The SQLSTATE code identifies the type
+of error that has occurred; it can be used by front-end applications
+to perform specific operations (such as error handling) in response to
+a particular database error. For a list of the possible SQLSTATE
+codes, see <xref linkend="errcodes-appendix">. This field is not
+localizable, and is always present.
 </para>
 </listitem>
 </varlistentry>
@@ -1871,7 +1879,7 @@ on <function>PQfsize</function> to obtain the actual data length.
           Prints out all the rows and,  optionally,  the
           column names  to  the specified output stream.
 <synopsis>
-void PQprint(FILE* fout,      /* output stream */
+void PQprint(FILE *fout,      /* output stream */
              const PGresult *res,
              const PQprintOpt *po);
 
@@ -3217,15 +3225,15 @@ typedef enum {
 
 PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
 </synopsis>
-<function>PQsetErrorVerbosity</> sets the verbosity mode, returning the
-connection's previous setting.
-In <firstterm>terse</> mode, returned messages include severity, primary text, and position
-only; this will normally fit on a single line.  The default mode produces
-messages that include the above plus any detail, hint, or context fields
-(these may span multiple lines).  The <firstterm>VERBOSE</> mode includes all available
-fields.  Changing the verbosity does not affect the messages available from
-already-existing <structname>PGresult</> objects, only subsequently-created
-ones.
+<function>PQsetErrorVerbosity</> sets the verbosity mode, returning
+the connection's previous setting.  In <firstterm>TERSE</> mode,
+returned messages include severity, primary text, and position only;
+this will normally fit on a single line.  The default mode produces
+messages that include the above plus any detail, hint, or context
+fields (these may span multiple lines).  The <firstterm>VERBOSE</>
+mode includes all available fields.  Changing the verbosity does not
+affect the messages available from already-existing
+<structname>PGresult</> objects, only subsequently-created ones.
 </para>
 </listitem>
 </varlistentry>