---------------------------(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
+
projects / postgresql / commitdiff