Add macros for error result fields to libpq.

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 8284d4b5f8d9aba2bdbb4d971948f94a611d124e..b7d3584171e1691eb705492fa60c6e4065a3a740 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.131 2003/08/13 16:29:03 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.132 2003/08/24 18:36:38 petere Exp $
 -->
 
  <chapter id="libpq">
@@ -1283,20 +1283,138 @@ Returns an individual field of an error report.
 <synopsis>
 char *PQresultErrorField(const PGresult *res, int fieldcode);
 </synopsis>
-<parameter>fieldcode</> is an error field identifier defined by the
-<productname>PostgreSQL</> protocol (see <xref
-linkend="protocol-error-fields">), for example <literal>'C'</> for
-the SQLSTATE error code.  NULL is returned if the
+<parameter>fieldcode</> is an error field identifier; see the symbols
+listed below.  <symbol>NULL</symbol> is returned if the
 <structname>PGresult</structname> is not an error or warning result,
 or does not include the specified field.  Field values will normally
 not include a trailing newline.
 </para>
 
 <para>
-Errors generated internally by libpq will have severity and primary message,
-but typically no other fields.  Errors returned by a pre-3.0-protocol server
-will include severity and primary message, and sometimes a detail message,
-but no other fields.
+The following field codes are available:
+<variablelist>
+
+<varlistentry>
+<term><symbol>PG_DIAG_SEVERITY</></term>
+<listitem>
+<para>
+The severity; the field contents are <literal>ERROR</>,
+<literal>FATAL</>, or <literal>PANIC</> (in an error message), or
+<literal>WARNING</>, <literal>NOTICE</>, <literal>DEBUG</>,
+<literal>INFO</>, or <literal>LOG</> (in a notice message), or a
+localized translation of one of these.  Always present.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_SQLSTATE</>
+</term>
+<listitem>
+<para>
+The SQLSTATE code for the error (a 5-character string following SQL
+spec conventions).  Not localizable.  Always present.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_MESSAGE_PRIMARY</></term>
+<listitem>
+<para>
+The primary human-readable error message (typically one line).  Always
+present.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_MESSAGE_DETAIL</></term>
+<listitem>
+<para>
+Detail: an optional secondary error message carrying more detail about
+the problem.  May run to multiple lines.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_MESSAGE_HINT</></term>
+<listitem>
+<para>
+Hint: an optional suggestion what to do about the problem.  This is
+intended to differ from detail in that it offers advice (potentially
+inappropriate) rather than hard facts.  May run to multiple lines.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_STATEMENT_POSITION</></term>
+<listitem>
+<para>
+A string containing a decimal integer indicating an error cursor
+position as an index into the original statement string.  The first
+character has index 1, and positions are measured in characters not
+bytes.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_CONTEXT</></term>
+<listitem>
+<para>
+An indication of the context in which the error occurred.  Presently
+this includes a call stack traceback of active PL functions.  The
+trace is one entry per line, most recent first.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_SOURCE_FILE</></term>
+<listitem>
+<para>
+The file name of the source-code location where the error was
+reported.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_SOURCE_LINE</></term>
+<listitem>
+<para>
+The line number of the source-code location where the error was
+reported.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_SOURCE_FUNCTION</></term>
+<listitem>
+<para>
+The name of the source-code function reporting the error.
+</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</para>
+
+<para>
+The client is responsible for formatting displayed information to meet
+its needs; in particular it should break long lines as needed.
+Newline characters appearing in the error message fields should be
+treated as paragraph breaks, not line breaks.
+</para>
+
+<para>
+Errors generated internally by <application>libpq</application> will
+have severity and primary message, but typically no other fields.
+Errors returned by a pre-3.0-protocol server will include severity and
+primary message, and sometimes a detail message, but no other fields.
 </para>
 
 <para>

diff --git a/src/interfaces/ecpg/ecpglib/connect.c b/src/interfaces/ecpg/ecpglib/connect.c
index 6574216a6068c3019bee5199882dde3479b357a0..4b7683633bda727f0d2d25680616946f9e82d40c 100644 (file)
--- a/src/interfaces/ecpg/ecpglib/connect.c
+++ b/src/interfaces/ecpg/ecpglib/connect.c
@@ -1,4 +1,4 @@
-/* $Header: /cvsroot/pgsql/src/interfaces/ecpg/ecpglib/connect.c,v 1.16 2003/08/08 13:16:20 petere Exp $ */
+/* $Header: /cvsroot/pgsql/src/interfaces/ecpg/ecpglib/connect.c,v 1.17 2003/08/24 18:36:38 petere Exp $ */
 
 #define POSTGRES_ECPG_INTERNAL
 #include "postgres_fe.h"
@@ -158,8 +158,8 @@ ECPGsetconn(int lineno, const char *connection_name)
 static void
 ECPGnoticeReceiver(void *arg, const PGresult *result)
 {
-       char       *sqlstate = PQresultErrorField(result, 'C');
-       char       *message = PQresultErrorField(result, 'M');
+       char       *sqlstate = PQresultErrorField(result, PG_DIAG_SQLSTATE);
+       char       *message = PQresultErrorField(result, PG_DIAG_MESSAGE_PRIMARY);
        struct sqlca_t *sqlca = ECPGget_sqlca();
 
        int                     sqlcode;

diff --git a/src/interfaces/ecpg/ecpglib/error.c b/src/interfaces/ecpg/ecpglib/error.c
index 82f2ccca3665c08371315d704065bd31a37634b6..48b879d5462436ce6a50b7f2f965dc4ac5359a10 100644 (file)
--- a/src/interfaces/ecpg/ecpglib/error.c
+++ b/src/interfaces/ecpg/ecpglib/error.c
@@ -1,4 +1,4 @@
-/* $Header: /cvsroot/pgsql/src/interfaces/ecpg/ecpglib/error.c,v 1.7 2003/08/08 13:16:20 petere Exp $ */
+/* $Header: /cvsroot/pgsql/src/interfaces/ecpg/ecpglib/error.c,v 1.8 2003/08/24 18:36:38 petere Exp $ */
 
 #define POSTGRES_ECPG_INTERNAL
 #include "postgres_fe.h"
@@ -164,10 +164,10 @@ ECPGraise_backend(int line, PGresult *result, PGconn *conn, int compat)
 
        if (result)
        {
-               sqlstate = PQresultErrorField(result, 'C');
+               sqlstate = PQresultErrorField(result, PG_DIAG_SQLSTATE);
                if (sqlstate == NULL)
                        sqlstate = ECPG_SQLSTATE_ECPG_INTERNAL_ERROR;
-               message = PQresultErrorField(result, 'M');
+               message = PQresultErrorField(result, PG_DIAG_MESSAGE_PRIMARY);
        }
        else
        {

diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
index 6843bb7e981b79a1a9692ab76828b89547bda5cf..3e068cc6dc942f53f1435e9ed920ae756a5ec7fc 100644 (file)
--- a/src/interfaces/libpq/libpq-fe.h
+++ b/src/interfaces/libpq/libpq-fe.h
@@ -7,7 +7,7 @@
  * Portions Copyright (c) 1996-2003, PostgreSQL Global Development Group
  * Portions Copyright (c) 1994, Regents of the University of California
  *
- * $Id: libpq-fe.h,v 1.98 2003/08/13 16:29:03 tgl Exp $
+ * $Id: libpq-fe.h,v 1.99 2003/08/24 18:36:38 petere Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -104,6 +104,18 @@ typedef enum
        PQERRORS_VERBOSE                        /* all the facts, ma'am */
 } PGVerbosity;
 
+/* for PQresultErrorField() */
+#define PG_DIAG_SEVERITY               'S'
+#define PG_DIAG_SQLSTATE               'C'
+#define PG_DIAG_MESSAGE_PRIMARY        'M'
+#define PG_DIAG_MESSAGE_DETAIL 'D'
+#define PG_DIAG_MESSAGE_HINT   'H'
+#define PG_DIAG_STATEMENT_POSITION 'P'
+#define PG_DIAG_CONTEXT                        'W'
+#define PG_DIAG_SOURCE_FILE            'F'
+#define PG_DIAG_SOURCE_LINE            'L'
+#define PG_DIAG_SOURCE_FUNCTION        'R'
+
 /* PGconn encapsulates a connection to the backend.
  * The contents of this struct are not supposed to be known to applications.
  */