Status and Text Reference Coding

Background

Phase I – error indicators.

The errno global variable

The 'C' language and the Unix operating system (which is written in 'C') had their origins in a 16 bit environment.  In such an environment resources are very scarce and several decisions had to be made to minimize their usage.  One set of those decisions had to do with the reporting of errors.

Assembler code typically used the 'carry' indicator that is part of the machine state to indicate an error.  Using that convention, if there was an error, there was no usable result and the cause of the error could be returned through the channel normally used to return the result.  The 'C' language did not provide a way to access the 'carry' bit; another method of indicating errors had to be invented.

Rather than consistently returning a status indicator, like the 'carry' bit, a result was always returned and special values were reserved to indicate errors.  Specifically, the NULL pointer indicated an error when a pointer was normally returned, and a negative value was returned when the normal result was restricted to a non-negative number. 

Although the negative value convention allowed for reporting the cause of an error, the NULL pointer convention did not.  Another way of communicating the cause of an error was needed.  The error communication channel adopted was the global variable errno.  Widely shared global variables are a poor communication device because it is very easy to overwrite the information it contains before that information has reached its nominal destination.

Some other environments environments, especially 32 bit and larger environments, use a different scheme.  They consistantly return a status indicator in all cases and return other results to memory locations whose addresses are passed as parameters.  This project makes such a scheme easily accessable in 'C'.

HP's OpenVMS (aka DEC's VMS)

The VMS message/status code is a 32 bit unsigned integer structured as follows:

The purpose of each field is as follows:

Sev – Severity code

3 bits.  The values mean:

0. Warning.
1. Success.
2. Error.
3. Informational.
4. Severe Error.

All other values are reserved and should not be used.  Special bits –

0. Success/failure indicator:
   0. Failure.
   1. Success.

Message ID

13 bits.  A facility specific meaning or message identifier.

Facility ID

12 bits.  A number indicating the facility that produced the status code.  Special bits –

27. Facility Identifier group:
    0. System facility (defined by the propriator. That is HP, COMPAQ or DEC).
    1. Customer's facility (which should be registered with the propriator).

Ctrl

4 bits.  Each bit has a meaning –

28. Display state:
    0. Display needed.
    1. Display done.

The other bits are currently reserved and should be 0.

Microsoft's Windows event/status/error codes.

These Windows types are 32 bit unsigned integers structured as follows:

The purpose of each field is as follows:

Code

16 bits.  The status code from the facility.  Special bits:

15. Code category:
    0. System wide code.
    1. Facility specific code.

Facility

11 bits.  A registered identifier for the origin of the Code.

r – reserved.

N – NT map

1 bit.  Meaning:

0. From other technology platforms.
1. From NT platforms.

C – Facility category

1 bit.  Meaning:

0. System facility.
1. Customer facility.

M – NT severity modifier.

1 bit.  This bit combines with the S bit to produce the following values:

0. Success.
1. Informational.
2. Warning.
3. Error.

S – Severity

1 bit.  Meaning:

0. Success.
1. Error.

Discussion.

Both of these schemes reserve half the message space for the system propriator.  This is way out of balance.  Neither used anything like a significant fraction of the number of messages allocated to them.  For non-propriatary use, the distribution of control needs to be much more even handed.

Both schemes make it fairly easy to accidently code a 'FATAL Success' message.  To say that this can cause confusion is more than a minor understatement.  Fairly obviously the 'severity' code should be part of the message selection.

Phase II

References.

HP's OpenVMS (aka DEC's VMS).

Condition code structure.

$PUTMSG system service (almost at the end of the description).

Microsoft's Windows.

Event identifiers.

Windows Error codes (about a quarter of the way down from the top).

NT Windows Error codes.

Designing COM Interfaces (about a third of the way down from the top).

Phase II – status and other code translation to text.

[TBS]

NOTE

The information on this page is mainly historical.  It may provide some information that is useful but does not really fit into the Programmer's Guide.  It should not require much in the way of maintainance.

Work List (Mostly preperation for Phase II):

• Find and document similar facilities on other platforms.
• Add references to the other OpenVMS message handling services.
• Check for similar message handling services in W32.
• Check for similar POSIX services.