Improve documentation for SQLSTATE error codes, per recent thread on

-patches.

Author: Neil Conway

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>

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>

src/include/utils/errcodes.h

@@ -11,7 +11,7 @@
  *
  * Copyright (c) 2003, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/include/utils/errcodes.h,v 1.8 2004/03/04 21:47:18 neilc Exp $
+ * $PostgreSQL: pgsql/src/include/utils/errcodes.h,v 1.9 2004/05/14 18:04:02 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -30,8 +30,24 @@
  * class (the first two characters of the code value identify the class).
  * The listing is organized by class to make this prominent.
  *
- * The generic '000' class code should be used for an error only when there
- * is not a more-specific code defined.
+ * The generic '000' subclass code should be used for an error only
+ * when there is not a more-specific subclass code defined.
+ *
+ * The SQL spec requires that all the elements of a SQLSTATE code be
+ * either digits or upper-case ASCII characters.
+ *
+ * Classes that begin with 0-4 or A-H are defined by the
+ * standard. Within such a class, subclass values defined by the
+ * standard must begin with 0-4 or A-H. To define a new error code,
+ * ensure that it is either in an "implementation-defined class" (it
+ * begins with 5-9 or I-Z), or its subclass falls outside the range of
+ * error codes that could be present in future versions of the
+ * standard (i.e. the subclass value begins with 5-9 or I-Z).
+ *
+ * The convention is that new error codes defined by PostgreSQL in a
+ * class defined by the standard have a subclass value that begins
+ * with 'P'. In addition, error codes defined by PostgreSQL clients
+ * (such as ecpg) have a class value that begins with 'Y'.
  */
 
 /* Class 00 - Successful Completion */