From c3664c0c007931102727a016208ca604123622e0 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sun, 24 Aug 2003 18:36:38 +0000 Subject: [PATCH] Add macros for error result fields to libpq. --- doc/src/sgml/libpq.sgml | 136 ++++++++++++++++++++++++-- src/interfaces/ecpg/ecpglib/connect.c | 6 +- src/interfaces/ecpg/ecpglib/error.c | 6 +- src/interfaces/libpq/libpq-fe.h | 14 ++- 4 files changed, 146 insertions(+), 16 deletions(-) diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 8284d4b5f8..b7d3584171 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ @@ -1283,20 +1283,138 @@ Returns an individual field of an error report. char *PQresultErrorField(const PGresult *res, int fieldcode); -fieldcode is an error field identifier defined by the -PostgreSQL protocol (see ), for example 'C' for -the SQLSTATE error code. NULL is returned if the +fieldcode is an error field identifier; see the symbols +listed below. NULL is returned if the PGresult is not an error or warning result, or does not include the specified field. Field values will normally not include a trailing newline. -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: + + + +PG_DIAG_SEVERITY + + +The severity; the field contents are ERROR, +FATAL, or PANIC (in an error message), or +WARNING, NOTICE, DEBUG, +INFO, or LOG (in a notice message), or a +localized translation of one of these. Always present. + + + + + +PG_DIAG_SQLSTATE + + + +The SQLSTATE code for the error (a 5-character string following SQL +spec conventions). Not localizable. Always present. + + + + + +PG_DIAG_MESSAGE_PRIMARY + + +The primary human-readable error message (typically one line). Always +present. + + + + + +PG_DIAG_MESSAGE_DETAIL + + +Detail: an optional secondary error message carrying more detail about +the problem. May run to multiple lines. + + + + + +PG_DIAG_MESSAGE_HINT + + +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. + + + + + +PG_DIAG_STATEMENT_POSITION + + +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. + + + + + +PG_DIAG_CONTEXT + + +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. + + + + + +PG_DIAG_SOURCE_FILE + + +The file name of the source-code location where the error was +reported. + + + + + +PG_DIAG_SOURCE_LINE + + +The line number of the source-code location where the error was +reported. + + + + + +PG_DIAG_SOURCE_FUNCTION + + +The name of the source-code function reporting the error. + + + + + + + +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. + + + +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. diff --git a/src/interfaces/ecpg/ecpglib/connect.c b/src/interfaces/ecpg/ecpglib/connect.c index 6574216a60..4b7683633b 100644 --- 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 82f2ccca36..48b879d546 100644 --- 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 6843bb7e98..3e068cc6dc 100644 --- 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. */