From 0cb27df5c6b563b98fd656e691064a2927931e0d Mon Sep 17 00:00:00 2001
From: Neil Conway <neilc@samurai.com>
Date: Fri, 14 May 2004 18:04:02 +0000
Subject: [PATCH] Improve documentation for SQLSTATE error codes, per recent
thread on -patches.
---
doc/src/sgml/errcodes.sgml | 21 +++++++++++++--------
doc/src/sgml/libpq.sgml | 34 +++++++++++++++++++++-------------
src/include/utils/errcodes.h | 22 +++++++++++++++++++---
3 files changed, 53 insertions(+), 24 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>
diff --git a/src/include/utils/errcodes.h b/src/include/utils/errcodes.h
index c6f4e7bb971..64fa7d27187 100644
--- 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 */
--
GitLab