Improve documentation for SQLSTATE error codes, per recent thread on

-patches.

diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml
index 3afb85ec794149bdcb2a80d50629c7f106ae6178..2f211f462e8fa3f3ed43058bc9b14d6cf7e47443 100644 (file)
--- a/doc/src/sgml/errcodes.sgml
+++ b/doc/src/sgml/errcodes.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  <productname>PostgreSQL</productname> Error Codes
@@ -9,13 +9,18 @@
  
 
  
-  All messages emitted by the PostgreSQL server
-  are assigned five-character error codes that follow the SQL standard's
-  conventions for 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 PostgreSQL releases,
-  and also are not subject to change due to localization of error messages.
+  All messages emitted by the PostgreSQL
+  server are assigned five-character error codes that follow the SQL
+  standard's conventions for 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
+  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 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.
  
 
  

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 99bba6059d8e426747694e55524fc30c4581a0a2..2eaa4da341b6565b7580a6ac07cc2d6a502b80dd 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -1336,12 +1336,20 @@ localized translation of one of these.  Always present.
 
 
 
+ 
+  error codes
+  libpq
+ 
 PG_DIAG_SQLSTATE
 
 
 
-The SQLSTATE code for the error (see ).
-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 . This field is not
+localizable, and is always present.
 
 
 
@@ -1871,7 +1879,7 @@ on PQfsize to obtain the actual data length.
           Prints out all the rows and,  optionally,  the
           column names  to  the specified output stream.
 
-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);
 
-PQsetErrorVerbosity sets the verbosity mode, returning the
-connection's previous setting.
-In 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 VERBOSE mode includes all available
-fields.  Changing the verbosity does not affect the messages available from
-already-existing PGresult objects, only subsequently-created
-ones.
+PQsetErrorVerbosity sets the verbosity mode, returning
+the connection's previous setting.  In 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 VERBOSE
+mode includes all available fields.  Changing the verbosity does not
+affect the messages available from already-existing
+PGresult objects, only subsequently-created ones.
 
 
 

diff --git a/src/include/utils/errcodes.h b/src/include/utils/errcodes.h
index c6f4e7bb9712dc880eee0aeae85ed301a08fa1a6..64fa7d271879e97f1c93cb8902a8b43f350f3b08 100644 (file)
--- a/src/include/utils/errcodes.h
+++ b/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 */