From cf0be7fe5ec560ab48ad69c898d05c75aecf51bd Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Tue, 27 Aug 2002 15:31:32 +0000 Subject: [PATCH] Add error code emails. --- doc/TODO.detail/error | 960 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 960 insertions(+) diff --git a/doc/TODO.detail/error b/doc/TODO.detail/error index 2ff38b995a..7daf315463 100644 --- a/doc/TODO.detail/error +++ b/doc/TODO.detail/error @@ -403,3 +403,963 @@ make a pass through the code to try to implement it. ---------------------------(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: +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 ; 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 ; 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 +Subject: [HACKERS] error codes +Message-ID: <20020717182739.GB5542@klamath.dyndns.org> +Mail-Followup-To: PostgreSQL Hackers +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 +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: +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 ; 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 ; 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 +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 +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: +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 ; 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 ; 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 +cc: PostgreSQL Hackers +Subject: Re: [HACKERS] error codes +Message-ID: <20020717201758.GA6846@klamath.dyndns.org> +Mail-Followup-To: Tom Lane , + PostgreSQL Hackers +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 +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: +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 ; 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 ; 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 +Message-ID: <200207172204.g6HM4Hi09355@candle.pha.pa.us> +Subject: Re: [HACKERS] error codes +In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org> +To: Neil Conway +Date: Wed, 17 Jul 2002 18:04:17 -0400 (EDT) +cc: PostgreSQL Hackers +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: +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 ; 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 ; 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 ; 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 +X-Sender: +To: PostgreSQL Development +Subject: [HACKERS] Backend error message style issues +Message-ID: +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 . +ERROR: Permission to do was denied. +ERROR: : 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: +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 ; 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 ; 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 ; 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 +Organization: Mascari Development Inc. +X-Mailer: Mozilla 4.77 [en] (WinNT; U) +X-Accept-Language: en +MIME-Version: 1.0 +To: Peter Eisentraut +cc: PostgreSQL Development +Subject: Re: [HACKERS] Backend error message style issues +References: +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: +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 ; 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 ; 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 ; 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 +cc: PostgreSQL Development +Subject: Re: [HACKERS] Backend error message style issues +In-Reply-To: +References: +Comments: In-reply-to Peter Eisentraut + 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 +Precedence: bulk +Sender: pgsql-hackers-owner@postgresql.org +Status: OR + +Peter Eisentraut 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: +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 ; 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 ; 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 +X-X-Sender: peter@localhost.localdomain +To: Neil Conway +cc: PostgreSQL Hackers +Subject: Re: [HACKERS] error codes +In-Reply-To: <20020717182739.GB5542@klamath.dyndns.org> +Message-ID: +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: +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 ; 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 ; 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" +To: "Neil Conway" , + "PostgreSQL Hackers" +Subject: Re: [HACKERS] error codes +Date: Thu, 18 Jul 2002 09:57:56 +0800 +Message-ID: +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: +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 ; 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 ; 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" +To: "Bruce Momjian" , + "Neil Conway" +cc: "PostgreSQL Hackers" +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 +