diff options
| -rw-r--r-- | doc/src/sgml/errcodes.sgml | 21 | ||||
| -rw-r--r-- | doc/src/sgml/libpq.sgml | 34 | ||||
| -rw-r--r-- | 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 */ |