rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve documentation for SQLSTATE error codes, per recent thread on 

-patches.
This commit is contained in:
Neil Conway 2004-05-14 18:04:02 +00:00
parent 9f944f0443
commit 0cb27df5c6
3 changed files with 53 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
doc/src/sgml/errcodes.sgml
View File

@ -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>

34
doc/src/sgml/libpq.sgml
View File

@ -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>

22
src/include/utils/errcodes.h
View File

@ -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 */