path: root/doc/TODO.detail/error

From pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 12:14:19 2001
Return-path: <pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUIEIR21802
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:14:18 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUI6ER13094
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 12:11:00 -0600 (CST)
	(envelope-from pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org)
Received: from moutvdom01.kundenserver.de (moutvdom01.kundenserver.de [195.20.224.200])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUI58m98870
	for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 13:05:08 -0500 (EST)
	(envelope-from peter_e@gmx.net)
Received: from [195.20.224.208] (helo=mrvdom01.schlund.de)
	by moutvdom01.kundenserver.de with esmtp (Exim 2.12 #2)
	id 169s27-00049P-00
	for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:07 +0100
Received: from p3e9e6fa2.dip0.t-ipconnect.de ([62.158.111.162])
	by mrvdom01.schlund.de with esmtp (Exim 2.12 #2)
	id 169s21-0001UP-00
	for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:03 +0100
Date: Fri, 30 Nov 2001 19:12:16 +0100 (CET)
From: Peter Eisentraut <peter_e@gmx.net>
X-Sender: <peter@peter.localdomain>
To: PostgreSQL Development <pgsql-hackers@postgresql.org>
Subject: [HACKERS] Backend error message style issues
Message-ID: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: ORr

Now that we've gone through nearly one development cycle with national
language support, I'd like to bring up a number of issues concerning the
style of the backend error messages that make life difficult, but probably
not only for the translators but for users as well.  Not all of these are
strictly translation issues, but the message catalogs make for a good
overview of what's going on.

I hope we can work through all of these during the next development
period.

Prefixing messages with command names
-------------------------------------

For instance,

| CREATE DATABASE: permission denied

This "command: message" style is typical for command-line programs and
it's pretty useful there if you run many commands in a pipe.  The same
usefulness could probably be derived if you run many SQL commands in a
function.  (Just "permission denied" would be very confusing there!)

If we want to use that style we should make it consistent and we should
automate it.  Via the "command tag" mechanism we already know what command
we're executing, so we can automatically prefix all messages that way.  It
could even be switched off by the user if it's deemed annoying.


Prefixing messages with function names
--------------------------------------

The function names obviously have no meaning to the user.  It is claimed
that they allow a developer to locate the place the error was raised
faster, but that's only half the truth.  Firstly, this whole thing doesn't
work if the displayed name of the function was actually passed in from
elsewhere.  Then it takes you three times longer to locate the source
because you *think* you know where it was but it's not there.  Secondly,
a developer doesn't have the need to locate every error.  For instance,

| ExecAppend: rejected due to CHECK constraint foo

There's no need to debug anything there, it's a perfectly normal use
situation.

I think the key here is to distinguish error messages that are perfectly
normal user-level events from messages which really represent an "assert
failure, but continue gracefully", such as

| initGISTstate: numberOfAttributes %d > %d

The latter could better be written something like

| BETTER_BE_TRUE(index->rd_att->natts > INDEX_MAX_KEYS);

we could lead to an error message in the style of an assert failure,
including the expression in question and file and line information (and
bug reporting suggestions).  This way the developer doesn't have to write
any message text at all but still gets much better information to locate
the source.  (E.g., note that the tested variable isn't even called
"numberOfAttributes".)

The exact API could be tuned to include some other information such as an
informal message, but I think something along these lines needs to be
worked out.


Quoting
-------

Which is better:

function '%s' not found
function "%s" not found
function %s not found

I think two kinds of quotes is looking messy.  Personal suggestion:
double quotes.


Capitalization and punctuation
------------------------------

Which one?

ERROR:  Permission denied.
ERROR:  Permission denied
ERROR:  permission denied

I have personally used the GNU-recommended way which is the third, mostly
just because it is *some* standardized way.  I don't have a strong feeling
about the initial capitalization, but I'm against the periods except when
the message is really a sentence and it contains some other punctuation
(commas, etc.) or the message consists of more than one sentence.


Grammatical structure and choice of words
-----------------------------------------

There are many others besides the above choices:

ERROR: Permission was denied.
ERROR: You don't have permission to do <task>.
ERROR: Permission to do <task> was denied.
ERROR: <task>: Permission denied

In other cases there's a sea of possibilities:

couldn't find THING
can't find THING
THING wasn't found
unable to locate THING
lookup of THING failed
THING doesn't exist

Strictly speaking, there are at least four different meanings among those
six messages, yet they're used mostly randomly.

There are a number of things to think about here: active vs passive, can
vs could, complete sentence vs telegram style, use of colons, addressing
the user with "you [cannot...]".

And please let's not have the program talk in the "I"-form ("I have rolled
back the current transaction ...").



More esoteric discussions are also possible, but I'm going to postpone
those. ;-)  However, I think it's worth working on this and perhaps
putting together a "manual of style" that applies to all parts of
PostgreSQL.  This would significantly improve the overall perceived
quality.  Some projects like KDE, GNU, and GCC have teams that discuss
these kinds of things and it's definitely showing.

-- 
Peter Eisentraut   peter_e@gmx.net


---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majordomo@postgresql.org so that your
message can get through to the mailing list cleanly

From pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 13:39:41 2001
Return-path: <pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUJdfR29066
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:39:41 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUJXkR15701
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:36:17 -0600 (CST)
	(envelope-from pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org)
Received: from corvette.mascari.com (dhcp065-024-158-068.columbus.rr.com [65.24.158.68])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJMnm01940
	for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:22:49 -0500 (EST)
	(envelope-from mascarm@mascari.com)
Received: from mascari.com (ferrari.mascari.com [192.168.2.1])
	by corvette.mascari.com (8.9.3/8.9.3) with ESMTP id OAA20637;
	Fri, 30 Nov 2001 14:16:52 -0500
Message-ID: <3C07DBAD.A9735975@mascari.com>
Date: Fri, 30 Nov 2001 14:19:09 -0500
From: Mike Mascari <mascarm@mascari.com>
Organization: Mascari Development Inc.
X-Mailer: Mozilla 4.77 [en] (WinNT; U)
X-Accept-Language: en
MIME-Version: 1.0
To: Peter Eisentraut <peter_e@gmx.net>
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] Backend error message style issues
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

Peter Eisentraut wrote:
> 
> Now that we've gone through nearly one development cycle with national
> language support, I'd like to bring up a number of issues concerning the
> style of the backend error messages that make life difficult, but probably
> not only for the translators but for users as well.  Not all of these are
> strictly translation issues, but the message catalogs make for a good
> overview of what's going on.

For what its worth, Oracle 8 ships with an error.txt file which
dictates the message standards to which their products comply.
Roughly:

Size Of Message:
---------------

Cannot exceed 76 characters, even when embedded format specifiers
are apart of the message. Only 
start-up and system-dependent messages can exceed 76 characters.

Simple Language:
---------------

Use non-cryptic messages and overly technical language.

Upper vs. Lowercase:
-------------------

Use uppercase for commands and keywords, lowercase for message
wording, including the first letter (which agrees with your use,
Peter).

Commands, Keywords, Parameter Values:
------------------------------------

When possible, give the command, keyword and parameters used in the
message. 

BAD: The relation could not be created
GOOD: CREATE TABLE failed for table "foo" because the disk is full

Period:
------

Do not end messages with a period (also agrees with your
conclusion).

Numbers:
-------

Don't enclose numbers with special characters. For example:

BAD: rows returned by subquery (3) exceeded limit (1)
GOOD: the subquery returned 3 rows exceeding the 1 row limit

Quotes:
------

Don't use single or double quotes to emphasize a text variable or
command

Single Quotes:
-------------

Never use them.

Double Quotes:
-------------

Always and only use them to identify database objects. 

BAD: Unable to drop table employees
GOOD: DROP TABLE of "employees" failed due to referential integrity
constraints

Ellipses:
--------

Don't use them. 

BAD: Unable to drop column mascarm.employees.salary
GOOD: ALTER TABLE was unable to drop the column "salary" table
"employees" schema "mascarm"

Parentheses:
-----------

Always and only use parentheses for constraint names

BAD: not null constraint ri_employees violated
GOOD: not null constraint (ri_employees) violated

Brackets:
--------

Always and only used for program arguments

Grammar:
-------

Use complete sentences whenever possible without the trailing
period. Don't use multiple sentences. Use the active voice. Don't
use an aggressive tone.

Style:
-----

Make positive suggestions. Explain what is invalid and what is
valid.

Example:

BAD: file name invalid
BETTER: COPY failed because the file name was too long

Routine names:
-------------

Do not use routine names in messages. Again, agrees with you, Peter.

FWIW, 

Mike Mascari
mascarm@mascari.com

---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org

From pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 14:09:48 2001
Return-path: <pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUK9lR02095
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 15:09:48 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUK3MR16820
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:05:48 -0600 (CST)
	(envelope-from pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org)
Received: from sss.pgh.pa.us ([192.204.191.242])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJnLm02954
	for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:49:21 -0500 (EST)
	(envelope-from tgl@sss.pgh.pa.us)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.11.4/8.11.4) with ESMTP id fAUJnEi10307;
	Fri, 30 Nov 2001 14:49:14 -0500 (EST)
To: Peter Eisentraut <peter_e@gmx.net>
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] Backend error message style issues 
In-Reply-To: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain> 
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
Comments: In-reply-to Peter Eisentraut <peter_e@gmx.net>
	message dated "Fri, 30 Nov 2001 19:12:16 +0100"
Date: Fri, 30 Nov 2001 14:49:14 -0500
Message-ID: <10303.1007149754@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

Peter Eisentraut <peter_e@gmx.net> writes:
> I hope we can work through all of these during the next development
> period.

Too bad we didn't do it *before* doing a lot of translation work :-(.

Yes, I agree that a pass of rationalizing the error messages would be
useful.  Might want to think about that old bugaboo, error codes,
while we're at it.  Also the perennial complaint that "ERROR" and
"DEBUG" macros tend to conflict with other things.  As long as we're
going to touch many/all of the elog() calls, couldn't we try to clean
up all these issues?

> Which is better:

> function '%s' not found
> function "%s" not found
> function %s not found

Given that 'x' and "x" mean very different things in SQL, I think that
the first form is just plain wrong when an identifier is involved.
Unfortunately a lot of older code uses that style.  I've tried to use
double quotes in new messages, but have restrained myself from wholesale
changes of existing messages.

> More esoteric discussions are also possible, but I'm going to postpone
> those. ;-)  However, I think it's worth working on this and perhaps
> putting together a "manual of style" that applies to all parts of
> PostgreSQL.  This would significantly improve the overall perceived
> quality.

Sounds like a plan to me: put together a style guide first, and then
make a pass through the code to try to implement it.

			regards, tom lane

---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org

From pgsql-hackers-owner+M25090@postgresql.org Wed Jul 17 14:27:47 2002
Return-path: <pgsql-hackers-owner+M25090@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HIRke20336
	for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 14:27:46 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id A5EC0475931; Wed, 17 Jul 2002 14:27:42 -0400 (EDT)
Received: from klamath.dyndns.org (CPE002078144ae0.cpe.net.cable.rogers.com [24.102.202.35])
	by postgresql.org (Postfix) with ESMTP id 8C8A74758F5
	for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 14:27:39 -0400 (EDT)
Received: by klamath.dyndns.org (Postfix, from userid 1000)
	id D98827015; Wed, 17 Jul 2002 14:27:39 -0400 (EDT)
Date: Wed, 17 Jul 2002 14:27:39 -0400
To: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: [HACKERS] error codes
Message-ID: <20020717182739.GB5542@klamath.dyndns.org>
Mail-Followup-To: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.4i
From: nconway@klamath.dyndns.org (Neil Conway)
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: ORr

I'd like to implement error codes. I think they would be pretty useful,
although there are a few difficulties in the implementation I'd like
to get some input on.

Should every elog() have an error code? I'm not sure -- there are many
elog() calls that will never been seen by the user, since the error
they represent will be caught before control reaches the elog (e.g.
parse errors, internal consistency checks, multiple elog(ERROR)
for the same user error, etc.) Perhaps for those error messages
that don't have numbers, we could just give them ERRNO_UNKNOWN or
a similar constant.

How should the backend code signal an error with an error number?
Perhaps we could report errors with error numbers via a separate
function, which would take the error number as its only param.
For example:

error(ERRNO_REF_INT_VIOLATION);

The problem here is that many errors will require more information
that that, in order for the client to handle them properly. For
example, how should a COPY indicate that an RI violation has
occured? Ideally, we'd like to allow the client application to
know that in line a, column b, the literal value 'c' was
not found in the referenced column d of the referenced table d.

How should the error number be sent to the client, and would this
require an FE/BE change? I think we can avoid that: including the
error number in the error message itself, make PQgetErrorMessage()
(and similar funcs) smart enough to remove the error number, and
add a separate function (such as PQgetErrorNumber() ) to report
the error number, if there is one.

On a related note, it would be nice to get a consistent style of
punctuation for elog() messages -- currently, some of them end
in a period (e.g. "Database xxx does not exist in the system
catalog."), while the majority do not. Which is better?

Also, I think it was Bruce who mentioned that it would be nice
to add function names, source files, and/or line numbers to error
messages, instead of the current inconsistent method of sometimes
specifying the function name in the elog() message. Would this
be a good idea? Should all errors include this information?

It would be relatively easy to replace elog() with a macro of
the form:

#define elog(...) real_elog(__FILE__, __LINE__, __VA_ARGS__)

And then adjust real_elog() to report that information as
appropriate.

Cheers,

Neil

-- 
Neil Conway <neilconway@rogers.com>
PGP Key ID: DB3C29FC

---------------------------(end of broadcast)---------------------------
TIP 2: you can get off all lists at once with the unregister command
    (send "unregister YourEmailAddressHere" to majordomo@postgresql.org)

From pgsql-hackers-owner+M25094@postgresql.org Wed Jul 17 15:58:08 2002
Return-path: <pgsql-hackers-owner+M25094@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HJw7e27032
	for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 15:58:07 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id 73DA3475C3D; Wed, 17 Jul 2002 15:58:00 -0400 (EDT)
Received: from sss.pgh.pa.us (unknown [192.204.191.242])
	by postgresql.org (Postfix) with ESMTP id BDA71475D6F
	for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 15:57:56 -0400 (EDT)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.12.5/8.12.5) with ESMTP id g6HJvuAl016463;
	Wed, 17 Jul 2002 15:57:56 -0400 (EDT)
To: nconway@klamath.dyndns.org (Neil Conway)
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] error codes 
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org> 
References: <20020717182739.GB5542@klamath.dyndns.org>
Comments: In-reply-to nconway@klamath.dyndns.org (Neil Conway)
	message dated "Wed, 17 Jul 2002 14:27:39 -0400"
Date: Wed, 17 Jul 2002 15:57:56 -0400
Message-ID: <16462.1026935876@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

nconway@klamath.dyndns.org (Neil Conway) writes:
> Should every elog() have an error code?

I believe we decided that it'd be okay to use one or two codes defined
like "internal error", "corrupted data", etc for all the elogs that are
not-supposed-to-happen conditions.  What error codes are really for is
distinguishing different kinds of user mistakes, and so that's where
you need specificness.

> How should the backend code signal an error with an error number?

Please read some of the archived discussions about this.  All the points
you mention have been brought up before.

			regards, tom lane

---------------------------(end of broadcast)---------------------------
TIP 5: Have you checked our extensive FAQ?

http://www.postgresql.org/users-lounge/docs/faq.html

From pgsql-hackers-owner+M25095@postgresql.org Wed Jul 17 16:18:08 2002
Return-path: <pgsql-hackers-owner+M25095@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HKI8e28852
	for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 16:18:08 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id 68FAB475C69; Wed, 17 Jul 2002 16:18:05 -0400 (EDT)
Received: from klamath.dyndns.org (CPE002078144ae0.cpe.net.cable.rogers.com [24.102.202.35])
	by postgresql.org (Postfix) with ESMTP id 7867847585D
	for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 16:17:57 -0400 (EDT)
Received: by klamath.dyndns.org (Postfix, from userid 1000)
	id A182C7015; Wed, 17 Jul 2002 16:17:58 -0400 (EDT)
Date: Wed, 17 Jul 2002 16:17:58 -0400
To: Tom Lane <tgl@sss.pgh.pa.us>
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] error codes
Message-ID: <20020717201758.GA6846@klamath.dyndns.org>
Mail-Followup-To: Tom Lane <tgl@sss.pgh.pa.us>,
	PostgreSQL Hackers <pgsql-hackers@postgresql.org>
References: <20020717182739.GB5542@klamath.dyndns.org> <16462.1026935876@sss.pgh.pa.us>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <16462.1026935876@sss.pgh.pa.us>
User-Agent: Mutt/1.4i
From: nconway@klamath.dyndns.org (Neil Conway)
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

On Wed, Jul 17, 2002 at 03:57:56PM -0400, Tom Lane wrote:
> nconway@klamath.dyndns.org (Neil Conway) writes:
> > Should every elog() have an error code?
> 
> I believe we decided that it'd be okay to use one or two codes defined
> like "internal error", "corrupted data", etc for all the elogs that are
> not-supposed-to-happen conditions.

Ok, makes sense to me.

> > How should the backend code signal an error with an error number?
> 
> Please read some of the archived discussions about this.  All the points
> you mention have been brought up before.

Woops -- I wasn't aware that this had been discussed before, my apologies.
I'm reading the archives now...

Peter: are you planning to implement this?

Cheers,

Neil

-- 
Neil Conway <neilconway@rogers.com>
PGP Key ID: DB3C29FC

---------------------------(end of broadcast)---------------------------
TIP 2: you can get off all lists at once with the unregister command
    (send "unregister YourEmailAddressHere" to majordomo@postgresql.org)

From pgsql-hackers-owner+M25097@postgresql.org Wed Jul 17 18:04:36 2002
Return-path: <pgsql-hackers-owner+M25097@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HM4Ze09359
	for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 18:04:35 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id AD154475D78; Wed, 17 Jul 2002 18:04:29 -0400 (EDT)
Received: from candle.pha.pa.us (216-55-132-35.dsl.san-diego.abac.net [216.55.132.35])
	by postgresql.org (Postfix) with ESMTP id 5541A475C95
	for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 18:04:21 -0400 (EDT)
Received: (from pgman@localhost)
	by candle.pha.pa.us (8.11.6/8.10.1) id g6HM4Hi09355;
	Wed, 17 Jul 2002 18:04:17 -0400 (EDT)
From: Bruce Momjian <pgman@candle.pha.pa.us>
Message-ID: <200207172204.g6HM4Hi09355@candle.pha.pa.us>
Subject: Re: [HACKERS] error codes
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
To: Neil Conway <nconway@klamath.dyndns.org>
Date: Wed, 17 Jul 2002 18:04:17 -0400 (EDT)
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
X-Mailer: ELM [version 2.4ME+ PL99 (25)]
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary=ELM1026943457-25421-1_
Content-Transfer-Encoding: 7bit
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

--ELM1026943457-25421-1_
Content-Transfer-Encoding: 7bit
Content-Type: text/plain; charset=US-ASCII


Neil, attached are three email messages dealing with error message
wording.

I like Tom's idea of coding only the messages that are common/user
errors and leaving the others with a catch-all code.

We now have more elog levels in 7.3, so it should be easier to classify
the messages.

I can see this job as several parts:

---------------------------------------------------------------------------

Cleanup of error wording, removal of function names.  See attached
emails for possible standard.

---------------------------------------------------------------------------

Reporting of file, line, function reporting using GUC/SET variable.  For
function names I see in the gcc 3.1 docs at
http://gcc.gnu.org/onlinedocs/gcc-3.1/cpp/Standard-Predefined-Macros.html:

	C99 introduces __func__, and GCC has provided __FUNCTION__ for a long
	time. Both of these are strings containing the name of the current
	function (there are slight semantic differences; see the GCC manual).
	Neither of them is a macro; the preprocessor does not know the name of
	the current function. They tend to be useful in conjunction with
	__FILE__ and __LINE__, though.

My gcc 2.95 (gcc version 2.95.2 19991024) supports both __FUNCTION__ and
__func__, even though they are not documented in the info manual pages I
have.  I think we will need a configure.in test for this because it
isn't a macro you can #ifdef.

---------------------------------------------------------------------------

Actual error code numbers/letters.  I think the new elog levels will
help with this.  We have to decide if we want error numbers, or some
pneumonic like NOATTR or CONSTVIOL.  I suggest the latter.

---------------------------------------------------------------------------

I think we have plenty of time to get this done for 7.3.

-- 
  Bruce Momjian                        |  http://candle.pha.pa.us
  pgman@candle.pha.pa.us               |  (610) 853-3000
  +  If your life is a hard drive,     |  830 Blythe Avenue
  +  Christ can be your backup.        |  Drexel Hill, Pennsylvania 19026

--ELM1026943457-25421-1_
Content-Transfer-Encoding: 7bit
Content-Type: text/plain
Content-Disposition: inline; filename="/bjm/error"

>From pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 12:14:19 2001
Return-path: <pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUIEIR21802
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:14:18 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUI6ER13094
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 12:11:00 -0600 (CST)
	(envelope-from pgsql-hackers-owner+M16120=candle.pha.pa.us=pgman@postgresql.org)
Received: from moutvdom01.kundenserver.de (moutvdom01.kundenserver.de [195.20.224.200])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUI58m98870
	for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 13:05:08 -0500 (EST)
	(envelope-from peter_e@gmx.net)
Received: from [195.20.224.208] (helo=mrvdom01.schlund.de)
	by moutvdom01.kundenserver.de with esmtp (Exim 2.12 #2)
	id 169s27-00049P-00
	for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:07 +0100
Received: from p3e9e6fa2.dip0.t-ipconnect.de ([62.158.111.162])
	by mrvdom01.schlund.de with esmtp (Exim 2.12 #2)
	id 169s21-0001UP-00
	for pgsql-hackers@postgresql.org; Fri, 30 Nov 2001 19:05:03 +0100
Date: Fri, 30 Nov 2001 19:12:16 +0100 (CET)
From: Peter Eisentraut <peter_e@gmx.net>
X-Sender: <peter@peter.localdomain>
To: PostgreSQL Development <pgsql-hackers@postgresql.org>
Subject: [HACKERS] Backend error message style issues
Message-ID: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: ORr

Now that we've gone through nearly one development cycle with national
language support, I'd like to bring up a number of issues concerning the
style of the backend error messages that make life difficult, but probably
not only for the translators but for users as well.  Not all of these are
strictly translation issues, but the message catalogs make for a good
overview of what's going on.

I hope we can work through all of these during the next development
period.

Prefixing messages with command names
-------------------------------------

For instance,

| CREATE DATABASE: permission denied

This "command: message" style is typical for command-line programs and
it's pretty useful there if you run many commands in a pipe.  The same
usefulness could probably be derived if you run many SQL commands in a
function.  (Just "permission denied" would be very confusing there!)

If we want to use that style we should make it consistent and we should
automate it.  Via the "command tag" mechanism we already know what command
we're executing, so we can automatically prefix all messages that way.  It
could even be switched off by the user if it's deemed annoying.


Prefixing messages with function names
--------------------------------------

The function names obviously have no meaning to the user.  It is claimed
that they allow a developer to locate the place the error was raised
faster, but that's only half the truth.  Firstly, this whole thing doesn't
work if the displayed name of the function was actually passed in from
elsewhere.  Then it takes you three times longer to locate the source
because you *think* you know where it was but it's not there.  Secondly,
a developer doesn't have the need to locate every error.  For instance,

| ExecAppend: rejected due to CHECK constraint foo

There's no need to debug anything there, it's a perfectly normal use
situation.

I think the key here is to distinguish error messages that are perfectly
normal user-level events from messages which really represent an "assert
failure, but continue gracefully", such as

| initGISTstate: numberOfAttributes %d > %d

The latter could better be written something like

| BETTER_BE_TRUE(index->rd_att->natts > INDEX_MAX_KEYS);

we could lead to an error message in the style of an assert failure,
including the expression in question and file and line information (and
bug reporting suggestions).  This way the developer doesn't have to write
any message text at all but still gets much better information to locate
the source.  (E.g., note that the tested variable isn't even called
"numberOfAttributes".)

The exact API could be tuned to include some other information such as an
informal message, but I think something along these lines needs to be
worked out.


Quoting
-------

Which is better:

function '%s' not found
function "%s" not found
function %s not found

I think two kinds of quotes is looking messy.  Personal suggestion:
double quotes.


Capitalization and punctuation
------------------------------

Which one?

ERROR:  Permission denied.
ERROR:  Permission denied
ERROR:  permission denied

I have personally used the GNU-recommended way which is the third, mostly
just because it is *some* standardized way.  I don't have a strong feeling
about the initial capitalization, but I'm against the periods except when
the message is really a sentence and it contains some other punctuation
(commas, etc.) or the message consists of more than one sentence.


Grammatical structure and choice of words
-----------------------------------------

There are many others besides the above choices:

ERROR: Permission was denied.
ERROR: You don't have permission to do <task>.
ERROR: Permission to do <task> was denied.
ERROR: <task>: Permission denied

In other cases there's a sea of possibilities:

couldn't find THING
can't find THING
THING wasn't found
unable to locate THING
lookup of THING failed
THING doesn't exist

Strictly speaking, there are at least four different meanings among those
six messages, yet they're used mostly randomly.

There are a number of things to think about here: active vs passive, can
vs could, complete sentence vs telegram style, use of colons, addressing
the user with "you [cannot...]".

And please let's not have the program talk in the "I"-form ("I have rolled
back the current transaction ...").



More esoteric discussions are also possible, but I'm going to postpone
those. ;-)  However, I think it's worth working on this and perhaps
putting together a "manual of style" that applies to all parts of
PostgreSQL.  This would significantly improve the overall perceived
quality.  Some projects like KDE, GNU, and GCC have teams that discuss
these kinds of things and it's definitely showing.

-- 
Peter Eisentraut   peter_e@gmx.net


---------------------------(end of broadcast)---------------------------
TIP 3: if posting/reading through Usenet, please send an appropriate
subscribe-nomail command to majordomo@postgresql.org so that your
message can get through to the mailing list cleanly

>From pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 13:39:41 2001
Return-path: <pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUJdfR29066
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:39:41 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUJXkR15701
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 13:36:17 -0600 (CST)
	(envelope-from pgsql-hackers-owner+M16128=candle.pha.pa.us=pgman@postgresql.org)
Received: from corvette.mascari.com (dhcp065-024-158-068.columbus.rr.com [65.24.158.68])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJMnm01940
	for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:22:49 -0500 (EST)
	(envelope-from mascarm@mascari.com)
Received: from mascari.com (ferrari.mascari.com [192.168.2.1])
	by corvette.mascari.com (8.9.3/8.9.3) with ESMTP id OAA20637;
	Fri, 30 Nov 2001 14:16:52 -0500
Message-ID: <3C07DBAD.A9735975@mascari.com>
Date: Fri, 30 Nov 2001 14:19:09 -0500
From: Mike Mascari <mascarm@mascari.com>
Organization: Mascari Development Inc.
X-Mailer: Mozilla 4.77 [en] (WinNT; U)
X-Accept-Language: en
MIME-Version: 1.0
To: Peter Eisentraut <peter_e@gmx.net>
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] Backend error message style issues
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

Peter Eisentraut wrote:
> 
> Now that we've gone through nearly one development cycle with national
> language support, I'd like to bring up a number of issues concerning the
> style of the backend error messages that make life difficult, but probably
> not only for the translators but for users as well.  Not all of these are
> strictly translation issues, but the message catalogs make for a good
> overview of what's going on.

For what its worth, Oracle 8 ships with an error.txt file which
dictates the message standards to which their products comply.
Roughly:

Size Of Message:
---------------

Cannot exceed 76 characters, even when embedded format specifiers
are apart of the message. Only 
start-up and system-dependent messages can exceed 76 characters.

Simple Language:
---------------

Use non-cryptic messages and overly technical language.

Upper vs. Lowercase:
-------------------

Use uppercase for commands and keywords, lowercase for message
wording, including the first letter (which agrees with your use,
Peter).

Commands, Keywords, Parameter Values:
------------------------------------

When possible, give the command, keyword and parameters used in the
message. 

BAD: The relation could not be created
GOOD: CREATE TABLE failed for table "foo" because the disk is full

Period:
------

Do not end messages with a period (also agrees with your
conclusion).

Numbers:
-------

Don't enclose numbers with special characters. For example:

BAD: rows returned by subquery (3) exceeded limit (1)
GOOD: the subquery returned 3 rows exceeding the 1 row limit

Quotes:
------

Don't use single or double quotes to emphasize a text variable or
command

Single Quotes:
-------------

Never use them.

Double Quotes:
-------------

Always and only use them to identify database objects. 

BAD: Unable to drop table employees
GOOD: DROP TABLE of "employees" failed due to referential integrity
constraints

Ellipses:
--------

Don't use them. 

BAD: Unable to drop column mascarm.employees.salary
GOOD: ALTER TABLE was unable to drop the column "salary" table
"employees" schema "mascarm"

Parentheses:
-----------

Always and only use parentheses for constraint names

BAD: not null constraint ri_employees violated
GOOD: not null constraint (ri_employees) violated

Brackets:
--------

Always and only used for program arguments

Grammar:
-------

Use complete sentences whenever possible without the trailing
period. Don't use multiple sentences. Use the active voice. Don't
use an aggressive tone.

Style:
-----

Make positive suggestions. Explain what is invalid and what is
valid.

Example:

BAD: file name invalid
BETTER: COPY failed because the file name was too long

Routine names:
-------------

Do not use routine names in messages. Again, agrees with you, Peter.

FWIW, 

Mike Mascari
mascarm@mascari.com

---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org

>From pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org Fri Nov 30 14:09:48 2001
Return-path: <pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org>
Received: from rs.postgresql.org (server1.pgsql.org [64.39.15.238] (may be forged))
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id fAUK9lR02095
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 15:09:48 -0500 (EST)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by rs.postgresql.org (8.11.6/8.11.6) with ESMTP id fAUK3MR16820
	for <pgman@candle.pha.pa.us>; Fri, 30 Nov 2001 14:05:48 -0600 (CST)
	(envelope-from pgsql-hackers-owner+M16130=candle.pha.pa.us=pgman@postgresql.org)
Received: from sss.pgh.pa.us ([192.204.191.242])
	by postgresql.org (8.11.3/8.11.4) with ESMTP id fAUJnLm02954
	for <pgsql-hackers@postgresql.org>; Fri, 30 Nov 2001 14:49:21 -0500 (EST)
	(envelope-from tgl@sss.pgh.pa.us)
Received: from sss2.sss.pgh.pa.us (tgl@localhost [127.0.0.1])
	by sss.pgh.pa.us (8.11.4/8.11.4) with ESMTP id fAUJnEi10307;
	Fri, 30 Nov 2001 14:49:14 -0500 (EST)
To: Peter Eisentraut <peter_e@gmx.net>
cc: PostgreSQL Development <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] Backend error message style issues 
In-Reply-To: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain> 
References: <Pine.LNX.4.30.0111292302020.609-100000@peter.localdomain>
Comments: In-reply-to Peter Eisentraut <peter_e@gmx.net>
	message dated "Fri, 30 Nov 2001 19:12:16 +0100"
Date: Fri, 30 Nov 2001 14:49:14 -0500
Message-ID: <10303.1007149754@sss.pgh.pa.us>
From: Tom Lane <tgl@sss.pgh.pa.us>
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

Peter Eisentraut <peter_e@gmx.net> writes:
> I hope we can work through all of these during the next development
> period.

Too bad we didn't do it *before* doing a lot of translation work :-(.

Yes, I agree that a pass of rationalizing the error messages would be
useful.  Might want to think about that old bugaboo, error codes,
while we're at it.  Also the perennial complaint that "ERROR" and
"DEBUG" macros tend to conflict with other things.  As long as we're
going to touch many/all of the elog() calls, couldn't we try to clean
up all these issues?

> Which is better:

> function '%s' not found
> function "%s" not found
> function %s not found

Given that 'x' and "x" mean very different things in SQL, I think that
the first form is just plain wrong when an identifier is involved.
Unfortunately a lot of older code uses that style.  I've tried to use
double quotes in new messages, but have restrained myself from wholesale
changes of existing messages.

> More esoteric discussions are also possible, but I'm going to postpone
> those. ;-)  However, I think it's worth working on this and perhaps
> putting together a "manual of style" that applies to all parts of
> PostgreSQL.  This would significantly improve the overall perceived
> quality.

Sounds like a plan to me: put together a style guide first, and then
make a pass through the code to try to implement it.

			regards, tom lane

---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org


--ELM1026943457-25421-1_
Content-Type: text/plain
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0


---------------------------(end of broadcast)---------------------------
TIP 1: subscribe and unsubscribe commands go to majordomo@postgresql.org

--ELM1026943457-25421-1_--

From pgsql-hackers-owner+M25104@postgresql.org Wed Jul 17 18:30:49 2002
Return-path: <pgsql-hackers-owner+M25104@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6HMUme12537
	for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 18:30:48 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id BF5D6475D9D; Wed, 17 Jul 2002 18:30:42 -0400 (EDT)
Received: from mail.gmx.net (mail.gmx.net [213.165.64.20])
	by postgresql.org (Postfix) with SMTP id 20611475DCB
	for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 18:30:35 -0400 (EDT)
Received: (qmail 9427 invoked by uid 0); 17 Jul 2002 22:30:37 -0000
Received: from pd902f0de.dip0.t-ipconnect.de (217.2.240.222)
  by mail.gmx.net (mp007-rz3) with SMTP; 17 Jul 2002 22:30:37 -0000
Date: Thu, 18 Jul 2002 00:33:22 +0200 (CEST)
From: Peter Eisentraut <peter_e@gmx.net>
X-X-Sender: peter@localhost.localdomain
To: Neil Conway <nconway@klamath.dyndns.org>
cc: PostgreSQL Hackers <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] error codes
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
Message-ID: <Pine.LNX.4.44.0207172108290.9047-100000@localhost.localdomain>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

Neil Conway writes:

> I'd like to implement error codes. I think they would be pretty useful,
> although there are a few difficulties in the implementation I'd like
> to get some input on.

OK, allow me to pass on to you the accumulated wisdom on this topic. :-)

> Should every elog() have an error code?

The set of error codes should primarily be that defined by SQL99 part 2
clause 22 "Status codes" and PostgreSQL extensions that follow that
spirit.  That means that all those "can't happen" or "all is lost anyway"
types should be lumped (perhaps in some implicit way) under "internal
error".  That means, yes, an error code should be returned in every case
of an error, but it doesn't have to be a distinct error code for every
condition.

> How should the backend code signal an error with an error number?

> The problem here is that many errors will require more information
> that that, in order for the client to handle them properly. For
> example, how should a COPY indicate that an RI violation has
> occured? Ideally, we'd like to allow the client application to
> know that in line a, column b, the literal value 'c' was
> not found in the referenced column d of the referenced table d.

Precisely.  You will find that SQL99 part 2 clause 19 "Diagnostics
management" defines all the fields that form part of a diagnostic (i.e.,
error or notice).  This includes for example, fields that contain the name
and schema of the table that was involved, if appropriate.  (Again,
appropriate PostgreSQL extensions could be made.)  It is recommendable
that this scheme be followed, so PL/pgSQL and ECPG, to name some
candidates, could implement the GET DIAGNOSTICS statement as in the
standard.  (Notice that, for example, a diagnostic still contains a text
message in addition to a code.)

> How should the error number be sent to the client, and would this
> require an FE/BE change? I think we can avoid that: including the
> error number in the error message itself, make PQgetErrorMessage()
> (and similar funcs) smart enough to remove the error number, and
> add a separate function (such as PQgetErrorNumber() ) to report
> the error number, if there is one.

I would advise against trying to cram everything into a string.  Consider
the extra fields explained above.  Consider being nice to old clients.
Also, libpq allows that more than one error message might arrive per query
cycle.  Currently, the error messages are concatenated.  That won't work
anymore.  You need a new API anyway.  You need a new API for notices, too.

One possiblity to justify a protocol change is to break something else
with it, like a new copy protocol.

> On a related note, it would be nice to get a consistent style of
> punctuation for elog() messages -- currently, some of them end
> in a period (e.g. "Database xxx does not exist in the system
> catalog."), while the majority do not. Which is better?

Yup, we've talked about that some time ago.  I have a style guide mostly
worked out for discussion.

> It would be relatively easy to replace elog() with a macro of
> the form:
>
> #define elog(...) real_elog(__FILE__, __LINE__, __VA_ARGS__)
>
> And then adjust real_elog() to report that information as
> appropriate.

And it would be relatively easy to break every old compiler that way...

-- 
Peter Eisentraut   peter_e@gmx.net


---------------------------(end of broadcast)---------------------------
TIP 6: Have you searched our list archives?

http://archives.postgresql.org

From pgsql-hackers-owner+M25114@postgresql.org Wed Jul 17 21:57:52 2002
Return-path: <pgsql-hackers-owner+M25114@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6I1vpe07438
	for <pgman@candle.pha.pa.us>; Wed, 17 Jul 2002 21:57:52 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id 0E63047593C; Wed, 17 Jul 2002 21:57:47 -0400 (EDT)
Received: from houston.familyhealth.com.au (i231-006.nv.iinet.net.au [203.59.231.6])
	by postgresql.org (Postfix) with ESMTP id BA91F47585D
	for <pgsql-hackers@postgresql.org>; Wed, 17 Jul 2002 21:57:41 -0400 (EDT)
Received: (from root@localhost)
	by houston.familyhealth.com.au (8.11.6/8.11.6) id g6I1viW22817
	for pgsql-hackers@postgresql.org; Thu, 18 Jul 2002 09:57:44 +0800 (WST)
	(envelope-from chriskl@familyhealth.com.au)
Received: from mariner (mariner.internal [192.168.0.101])
	by houston.familyhealth.com.au (8.11.6/8.9.3) with SMTP id g6I1vhV22728;
	Thu, 18 Jul 2002 09:57:43 +0800 (WST)
From: "Christopher Kings-Lynne" <chriskl@familyhealth.com.au>
To: "Neil Conway" <nconway@klamath.dyndns.org>,
   "PostgreSQL Hackers" <pgsql-hackers@postgresql.org>
Subject: Re: [HACKERS] error codes
Date: Thu, 18 Jul 2002 09:57:56 +0800
Message-ID: <GNELIHDDFBOCMGBFGEFOOEDECDAA.chriskl@familyhealth.com.au>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
X-Priority: 3 (Normal)
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2910.0)
In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org>
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2600.0000
Importance: Normal
X-scanner: scanned by Inflex 0.1.5c - (http://www.inflex.co.za/)
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Status: OR

> Should every elog() have an error code? I'm not sure -- there are many
> elog() calls that will never been seen by the user, since the error
> they represent will be caught before control reaches the elog (e.g.
> parse errors, internal consistency checks, multiple elog(ERROR)
> for the same user error, etc.) Perhaps for those error messages
> that don't have numbers, we could just give them ERRNO_UNKNOWN or
> a similar constant.

It might be cool to a little command utility "pg_error" or whatever that you
pass an error code to and it prints out a very detailed description of the
problem...

Chris


---------------------------(end of broadcast)---------------------------
TIP 6: Have you searched our list archives?

http://archives.postgresql.org

From pgsql-hackers-owner+M25119@postgresql.org Thu Jul 18 04:01:40 2002
Return-path: <pgsql-hackers-owner+M25119@postgresql.org>
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by candle.pha.pa.us (8.11.6/8.10.1) with ESMTP id g6I81de14995
	for <pgman@candle.pha.pa.us>; Thu, 18 Jul 2002 04:01:40 -0400 (EDT)
Received: from postgresql.org (postgresql.org [64.49.215.8])
	by postgresql.org (Postfix) with SMTP
	id 38C49475E0D; Thu, 18 Jul 2002 04:01:33 -0400 (EDT)
Received: from smxsat1.smxs.net (smxsat1.smxs.net [213.150.10.1])
	by postgresql.org (Postfix) with ESMTP id 82A1B475DB6
	for <pgsql-hackers@postgresql.org>; Thu, 18 Jul 2002 04:01:26 -0400 (EDT)
Received: from m01x1.s-mxs.net [10.3.55.201]
	by smxsat1.smxs.net
	over TLS secured channel
	with XWall v3.21e ;
	Thu, 18 Jul 2002 10:01:23 +0200
Received: from m0102.s-mxs.net [10.3.55.2]
	by m01x1.s-mxs.net
	with XWall v3.21b ;
	Thu, 18 Jul 2002 10:01:21 +0200
Received: from m0114.s-mxs.net ([10.3.55.14]) by m0102.s-mxs.net with Microsoft SMTPSVC(5.0.2195.4453);
  Thu, 18 Jul 2002 10:01:20 +0200
X-MimeOLE: Produced By Microsoft Exchange V6.0.5762.3
content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Subject: Re: [HACKERS] error codes
Date: Thu, 18 Jul 2002 10:01:20 +0200
Message-ID: <46C15C39FEB2C44BA555E356FBCD6FA4961E24@m0114.s-mxs.net>
Thread-Topic: [HACKERS] error codes
Thread-Index: AcIt3fXLfLUm5ueDTfKp02tm+iyO0AAUPF/Q
From: "Zeugswetter Andreas SB SD" <ZeugswetterA@spardat.at>
To: "Bruce Momjian" <pgman@candle.pha.pa.us>,
   "Neil Conway" <nconway@klamath.dyndns.org>
cc: "PostgreSQL Hackers" <pgsql-hackers@postgresql.org>
X-OriginalArrivalTime: 18 Jul 2002 08:01:20.0584 (UTC) FILETIME=[4D5A6480:01C22E31]
Precedence: bulk
Sender: pgsql-hackers-owner@postgresql.org
Content-Transfer-Encoding: 8bit
X-MIME-Autoconverted: from quoted-printable to 8bit by candle.pha.pa.us id g6I81de14995
Status: ORr


Bruce wrote:
> Actual error code numbers/letters.  I think the new elog levels will
> help with this.  We have to decide if we want error numbers, or some
> pneumonic like NOATTR or CONSTVIOL.  I suggest the latter.

Since there is an actual standard for error codes, I would strongly suggest 
to adhere. The standardized codes are SQLSTATE a char(5) (well standardized
for many classes of db errors). Also common, but not so standardized is SQLCODE 
a long (only a very few are standardized, like 100 = 'no data found').
And also sqlca. Also look at ecpg for sqlcode and sqlca.

A Quote from dec rdb:
--------------------------------------------------------------------
   o  SQLCODE-This is the original SQL error handling mechanism.
      It is an integer value. SQLCODE differentiates among errors
      (negative numbers), warnings (positive numbers), succesful
      completion (0), and a special code of 100, which means no
      data. SQLCODE is a deprecated feature of the ANSI/ISO SQL
      standard.

   o  SQLCA-This is an extension of the SQLCODE error handling
      mechanism. It contains other context information that
      supplements the SQLCODE value. SQLCA is not part of the
      ANSI/ISO SQL standard. However, many foreign databases such
      as DB2 and ORACLE RDBMS have defined proprietary semantics and
      syntax to implement it.

   o  SQLSTATE-This is the error handling mechanism for the ANSI/ISO
      SQL standard. The SQLSTATE value is a character string that is
      associated with diagnostic information. To use the SQLSTATE
      status parameter, you must specify the SQL92 dialect and
      compile your module using DEC Rdb Version 6.0.
--------------------------------------------------------------------

Andreas

---------------------------(end of broadcast)---------------------------
TIP 4: Don't 'kill -9' the postmaster