Re: Error message style guide, take 2 {just for ideas to kick around...} - Mailing list pgsql-hackers

Not that I think PostgreSQL is going to adopt it, but as a reference for
any ideas of suitable use [since now is a time when things are being
revamped], here is the OpenVms message format described:

"Chapter 3
Message Utility

MESSAGE Description
The Message utility (MESSAGE) lets you supplement OpenVMS system
messages with your own messages. Your messages can indicate that an
error has occurred, or they can indicate other conditions; for example,
that a routine has run successfully or that a default value has been
assigned.

This section describes how to use the Message utility.

3.1 Message Format
Messages are displayed as a line of alphanumeric codes. The text of the
message explains the condition that caused the message to be displayed.

Messages are displayed in the following format:



%FACILITY-L-IDENT, message-text



FACILITY
Specifies the abbreviated name of the software component that issued the
message.
L
Shows the severity level of the condition that caused the message. The
five severity levels are represented by the following codes:
S  Success
I  Informational
W  Warning
E  Error
F  Fatal or severe

IDENT
Identifies a symbol of up to 15 characters that represents the message.
message-text
Explains the cause of the message. The message text can include up to
255 formatted-ASCII-output (FAO) arguments. For example, an FAO argument
can be used to display the instruction where an error occurred or a
value that you should be aware of.
% and ,
Included as delimiters if any of the first three fields---FACILITY, L,
or IDENT---are present.
If you suppress FACILITY, L, and IDENT, the first character of the
message text is capitalized by the Put Message ($PUTMSG) system service.


The following is a typical message:



%TYPE (1)-W- (2)OPENIN (3), error opening _DB0:[ROSE]STATS.FOR;(4) as
input  (5)



TYPE is the facility.
W (Warning) is the severity level.
OPENIN is the IDENT.
_DBO:[ROSE]STATS.FOR is the FAO argument.
"Error opening _DBO:[ROSE]STATS.FOR; as input" is the message text.
3.2 Constructing Messages
You construct messages by writing a message source file, compiling it
using the Message utility, and linking the resulting object module with
your facility object module. When you run your program, the Put Message
($PUTMSG) system service finds the information to use in the message by
using a message argument vector.

The message argument vector includes the message code, a 32-bit value
that uniquely identifies the message. The message code, which is created
from information defined in the message source file, consists of the
following:

The severity level defined in the severity directive or message
definition
The message number assigned automatically by a message definition or
specified with the base message number directive
The facility number defined in the facility directive
Internal control flags
Figure 3-1 shows the arrangement of the bits in the message code.

Figure 3-1 Message Code


------------------------------------------------------------------------
--------
You can refer to the message code in your programs by means of a global
symbol called the message symbol, which also is defined by information
from the message source file. The message symbol, which appears in the
compiled message file, consists of the following:

The symbol prefix defined in the facility directive
The symbol name defined in the message definition
3.2.1 The Message Source File
The message source file consists of message definition statements and
directives that define the message text, the message code values, and
the message symbol. The various elements that can be included in a
message source file are as follows:

Facility directive
Severity directive
Base message number directive
Message definition
Literal directive
Identification directive
Listing directives
End directive
Usually, the first statement in a message source file is a .TITLE
directive, which lets you specify a module name for the compiled message
file. You must specify a .FACILITY directive after the .TITLE directive.
All the messages defined after a .FACILITY directive are associated with
that facility. A .END directive or a new .FACILITY directive ends the
list of messages associated with a particular facility.

You must define a severity level for each message either by specifying a
.SEVERITY directive or by including a severity qualifier as part of the
message definition.

Each message defined in the message source file must have a facility and
a message definition associated with it. All other message source file
statements are optional. See the MESSAGE Commands section for a detailed
description of the format of each of these message source file
statements.

The TESTMSG.MSG file that follows is a sample message source file. The
messages for the associated FORTRAN program, TEST.FOR, are defined in
TESTMSG.MSG with the following lines:


.FACILITY       TEST,1 /PREFIX=MSG_ .SEVERITY       ERROR
SYNTAX          <Syntax error in string '!AS'>/FAO=1
ERRORS          <Errors encountered during processing> .END



The FORTRAN program, TEST.FOR, contains the following lines:



EXTERNAL MSG_SYNTAX,MSG_ERRORS
CALL LIB$SIGNAL(MSG_SYNTAX,%VAL(1),'ABC')
CALL LIB$SIGNAL(MSG_ERRORS)
END

In addition to defining the message data, TESTMSG.MSG also defines the
message symbols MSG_SYNTAX and MSG_ERRORS that are included as arguments
in the procedure calls of TEST.FOR. The function %VAL is a required
FORTRAN compile-time function. The first call also includes the string
ABC as an FAO argument."