Status and Text Reference Coding

Programmers' Guide

Introduction

The purpose of this project is to make code maintenance easier.  One aspect of code maintenance is reading and checking the code.  To that end, this project includes a header and library that makes it easier to read code. 

The code is the ultimate authority on what the computer will do.  As a result, someone, possibly yourself, will need to read the code after it has been written, with the possible (but not probable) exceptions of very small personal projects.  One significant problem is that the meaning of return values is not always clear.  Usually some kind of expression is need to test the result but the intent of the calculation is usually something less than obvious.  The header for this library, and to a much lesser extent the actual code in the library, make it easier to understand your intent if it is used consistently.

A second phase of this project, which is not even in the planning stages at this time, will make translating the program's or project's messages, particularly status messages, into other languages easier.

Quick Reference

Status encoding

A common 'C' convention is to return a pointer to a resource or resource control structure.  Another common convention is to return a negative value when an error occurs and the normal range of results is positive.  The pointer convention and to lesser extent the negative value convention fail to provide details about the source or cause of the error.  The 'C' standard calls for a global variable errno to convey this kind of information.

There are two major problems with errno.  The more important is that errno takes special handling to work properly in a multi-threaded environment.  The second is that a program modification added between the generation of the error and the point where the errno value is checked may produce another error that overwrites the original errno value.

An alternative design is to pass the address of a pointer or other object to receive the result and return an encoded status value indicating the validity of the operation.  This approach is used in VMS and less consistently in Microsoft Windows.  It was one of the unifying themes of VMS.  (Comments on its use by Microsoft are inappropriate in this context.)

Such a design requires the following characteristics:

• A construct that can be easily returned by a function.  In this design, that is an unsigned integer type broken up into a number of fields.
• At least one bit is required to encode a simple valid/invalid indicator.
• A second bit is often useful as a modifier or qualifier to the valid/invalid indicator.
• An identification of the source of the information is needed to establish its context.
• Where possible it should produce conventions consistent with standards and common practice.  In particular:
  • EXIT_SUCCESS should indicate a usable result.
  • EXIT_FAILURE should indicate an unusable result.
  • EOF should indicate an unusable result with a side condition that some intervention is required before the resource can be used again.
• It should work with different integer architectures if possible.

The type used to contain this information is designated status_t.

Types and data structures.

Note: The number of integer architectures supported is limited by the ability to test the implementations.  Help with this for less common architectures would be very helpful.

The status_t type

For 32 bit 2's compliment integers, status_t is defined as uint_least32_t and has the following structure:

The purpose of each field is as follows:

C*

1 bit.  The continuation or result modifier indicator.  The values of this field have the following meanings:

0. continue or normal severity.
1. stop or high severity.

Context ID*

10† bits.  This field may expand in architectures where integers have more than 32 bits.  Identifies the detailed context of the status value.  Note that the boundary between this field and the Facility Id field is preliminary; it may be moved if surveys find the number of messages per facility is too wasteful.

Count

The nominal size of a signed short int in bits (16).  The count value extracted by statusCount.

Facility ID

5† bits.  This field may expand in architectures where integers have more than 32 bits.  This field may be smaller in architectures where integers have only 16 bits.  Identifies the program or library that generated this status value so that the meaning of the Context ID can be interpreted properly. 
It is desirable that this field, the Context ID field and the result validity indicator all fit in an architectures small integer form.  Note that the boundary between this field and the Context Id field is preliminary; it may be moved if surveys find the number of messages per facility is too wasteful.

Maintainer ID

15† bits.  This field may expand in architectures where integers have more than 32 bits.  This field will not exist in architectures where integers have only 16 bits.  Identifies the the group for maintaining the Facility ID and acts as an extension of the Facility ID.

R*

1 bit.  The result validity indicator.  The values of this field have the following meanings:

0. usable.
1. unusable.

*

These fields combine to produce the Message Id.

†

The size of these fields may change if the size of status_t changes.

Internal constants.

Note that there should not be any need to use the following _RSE_ constants in normal code.  The main reason for documenting them is so that you can avoid using conflicting names.

The status_t fields are described by a set of enumerated or macro defined constants.  In the following description x is one of the words continue, context, facility, maintainer, or result.

• _RSE_Wx defines the width of the field.  If the field is missing for a particular architecture, its value is zero.
• _RSE_Vx indicates the least significant bit of the field in the status_t value.  If the field is missing for a particular architecture, this value should not be used. 
• _RSE_Lx is a value equivalent to
  
  (1 << _RSE_Vx).
  This value can be multiplied by the desired field value to position the value for insertion into a status_t value or it can divide a masked status_t value to get the field value.  If the field is missing for a particular architecture, this value should not be used. 
• _RSE_Mx is a value as a mask to isolate a particular field in a status_t value.  The expression
  
  (((status) & _RSE_Mx) / _RSE_Lx)
  
  will return the value of field x.  Note that there are functions and function like macros defined for many of fields.  If the field is missing for a particular architecture, this value should not be used. 

There are also a number of constants of the form _RSE_Cy, _RSE_Ry and _RSE_Sy used, among other things, to convert macro keyword like parameters to field values.  They are described in more detail in the section on initialization macros (below).

Normal functions and function like macros.

The canContinue function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool canContinue(status_t);

Description

The canContinue function test the continuation indicator of the status_t value for a not done status.

Returns

The canContinue function returns true if the continuation indicator of the status_t value has a not done status and false otherwise.

See also:

isError, isSuccess, and
status_t, statusDef5, myStatusDef3, sysStatusDef3, statusMessageId, and
mustStop, isDone, isFatal, isOverrun, isWarning

The isBad function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isBad(status_t);

Description

The isBad function test the result indicator of the status_t value for an invalid result status.

Returns

The isBad function returns true if the result indicator of the status_t value has an invalid result status and false otherwise.

See also:

isError, isFatal, isOverrun, and
status_t, statusDef5, myStatusDef3, sysStatusDef3, statusMessageId, and
isGood, isDone, isSuccess, isWarning, and

The isCError function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isCError(int);

Description

The isCError function test the int argument for a negative value which indicates an error.

Returns

The isCError function returns true if the int value indicates an error and false otherwise.

See also:

notCError

The isCount function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isCount(status_t);

Description

The isCount function test the status_t value to see if it is a valid argument for the statusCount function.  status_t values constructed with either the statusCountDef2 or statusCountDef3 macros will have this property.

Returns

The isCount function returns true if the the status_t value is a valid argument for the statusCount function.

See also:

statusCount, statusCountDef2, statusCountDef3, status_t

The isDone function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isDone(status_t);

Description

The isDone function test the status_t value for the done condition.  It is equivalent to the expression

(isGood(status_t) && mustStop(status_t))

except that it evaluates the status_t argument only once.

Returns

The isDone function returns true if the the status_t condition indicates done and false otherwise.

See also:

isWarning, isGood, mustStop, and
status_t, statusDef4, myStatusDef2, sysStatusDef2, and
isError, isFatal, isOverrun, isSuccess

The isError function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isError(status_t);

Description

The isError function test the status_t value for the error condition.  It is equivalent to the expression

(isBad(status_t) && canContinue(status_t))

except that it evaluates the status_t argument only once.

Returns

The isError function returns true if the status_t condition indicates an error and false otherwise.

See also:

canContinue, isBad, and
status_t, statusDef4, myStatusDef2, sysStatusDef2, and
isDone, isFatal, isOverrun, isSuccess, isWarning

The isFatal function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
boot isFatal(status_t);

Description

The isFatal function test the status_t value for the sever or fatal error condition.  It should be used in situations where a continuation indication does not make sense.  It is equivalent to the expression

(isBad(status_t) && mustStop(status_t))

except that it evaluates the status_t argument only once.

Returns

The isFatal function returns true if the status_t condition indicates a sever or fatal error and false otherwise.

See also:

isOverrun, isBad, mustStop, and
status_t, statusDef4, myStatusDef2, sysStatusDef2, and
isDone, isError, isSuccess, isWarning

The isGood function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isGood(status_t);

Description

The isGood function test the result indicator of the status_t for a valid result status.

Returns

The isGood function returns true if the result indicator of the status_t value indicates a valid result status and false otherwise.

See also:

isDone, isSuccess, isWarning, and
status_t, statusDef5, myStatusDef5, sysStatusDef5, statusMessageId, and
isBad, isError, isFatal, isOverrun

The isNULL function

Synopsis

#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isNULL(void *);

Description

The isNULL function tests its argument's value for equivalence to the NULL pointer.

Returns

The isNULL function returns true if its argument's value is equivalent to the NULL pointer and false otherwise.

See also:

notNULL

The isOverrun function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isOverrun(status_t);

Description

The isOverrun function test the status_t value for an overrun error condition.  It is equivalent to the expression

(isBad(status_t) && mustStop(status_t))

except that it evaluates the status_t argument only once.

Returns

The isOverrun function returns true if the status_t condition indicates an overrun error and false otherwise.

See also:

isFatal, isBad, mustStop, and
status_t, statusDef4, myStatusDef2, sysStatusDef2, and
isDone, isError, isWarning

The isSuccess function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isSuccess(status_t);

Description

The isSuccess function test the status_t value for the success condition.  It is equivalent to the expression

(isGood(status_t) && canContinue(status_t))

except that it evaluates the status_t argument only once.

Returns

The isSuccess function returns true if the status_t condition indicates success and false otherwise.

See also:

isGood, canContinue, and
status_t, statusDef4, myStatusDef2, sysStatusDef2, and
isDone, isError, isFatal, isOverrun, isWarning

The isWarning function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool isWarning(status_t);

Description

The isWarning function test the status_t value for the warning condition.  It should be used in situations where a continuation indication does not make sense.  It is equivalent to the expression

(isGood(status_t) && mustStop(status_t))

except that it evaluates the status_t argument only once.

Returns

The isWarning function returns true if the status_t condition indicates warning and false otherwise.

See also:

isDone, isGood, mustStop, and
status_t, statusDef4, myStatusDef2, sysStatusDef2, and
isError, isFatal, isOverrun, isSuccess

The mustStop function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool mustStop(status_t);

Description

The mustStop function test the continuation indicator of the status_t value for a done status.

Returns

The mustStop function returns true if the continuation indicator of the status_t value indicates a done status and false otherwise.

See also:

isDone, isFatal, isOverrun, isWarning, and
status_t, statusDef5, myStatusDef3, sysStatusDef3, statusMessageId, and
canContinue, isError, isSuccess

The notCError function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool notCError(int);

Description

The notCError function test the int value for a positive value which indicates that the value has its nominal meaning.

Returns

The notCError function returns true if the int value does not indicates an error and false otherwise.

See also:

isCError

The notNULL function

Synopsis

#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>
#include <status.h>
bool notNULL(void *);

Description

The notNULL function tests its argument's value for equivalence to the NULL pointer.

Returns

The notNULL function returns true if its argument's value is not equivalent to the NULL pointer and false otherwise.

See also:

isNULL

The statusContextId function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
unsigned int statusContextID(status_t);

Description

The statusContextID function extracts the value of the status_t Context ID field.

Returns

The statusContextID function returns the value of the status_t Context ID field.

See also:

statusMessageId, and
status_t, myStatusDef2, myStatusDef3, statusDef4, statusDef5, sysStatusDef2, sysStatusDef3

The statusCount function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
short int statusCount(status_t);

Description

The statusCount function extracts the count value from a status_t value constructed using the statusCountDef2 or statusCountDef3 macros.  If the function is applied to a status_t value for which isCount returns false, the result is undefined.

Returns

The statusCount function returns the value of the last argument passed to the statusCountDef2 or statusCountDef3 macro used to construct the status_t value.

See also:

isCount, and
status_t, statusCountDef2, statusCountDef3

The statusFacilityId function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
unsigned int statusFacilityId(status_t);

Description

The statusFacilityId function extracts the value of the Facility Id field of the status_t value.

Returns

The statusFacilityId function returns the value of the Facility Id field of the status_t value.

See also:

status_t, statusDef2, statusDef3, sysStatusDef2, sysStatusDef3, and
RSE_facility, myStatusDef2, myStatusDef3

The statusMaintainerId function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
unsigned int statusMaintainerId(status_t);

Description

The statusMaintainerId function extracts the value of the Maintainer Id field from the status_t value.  This function is not implemented on architectures with small ints.

Returns

The statusMaintainerId function returns the value of the Maintainer Id field from the status_t value.

See also:

status_t, statusDef2, statusDef3, sysStatusDef2, sysStatusDef3, and
RSE_maintainer, myStatusDef2, myStatusDef3

The statusMessageId function

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
unsigned int statusMessageId(status_t);

Description

The statusMessageId constructs a message identifier from several fields in the status_t value.  If this function is implemented as a macro, it may evaluate its argument more than once.

Returns

The statusMessageId returns the Message Id constructed from several fields in the status_t value.

See also:

statusContextId, canContinue, isBad, isGood, mustStop, and
status_t, statusDef4, statusDef5, myStatusDef2, myStatusDef3, sysStatusDef2, sysStatusDef3

Macros.

User defined:

The following user defined macros set the values for use by the myStatusDef3 and myStatusDef3 macros.

The RSE_facility macro

Description

Sets the facility identifier for the myStatusDef3 and myStatusDef2 macros.  If not defined, a default value will be set by including the <status.h> header.

See also:

status_t, myStatusDef2, myStatusDef3, statusFacilityId

The RSE_maintainer macro

Description

Sets the maintainer identifier for the myStatusDef3 and myStatusDef2 macros.  If not defined, a default value will be set by including the <status.h> header.

See also:

status_t, myStatusDef2, myStatusDef3, statusMaintainerId

Initialization macros:

Initial values for status_t static constants and variables must be compile-time constant expressions; they can not be function return values.  The expressions needed are fairly complex and implementation dependent.  To avoid these problems a number of macros are defined in this section.

The return, continuation and combined status indicator coding may change with the platform.  Simply passing zero and non-zero values to the macros would not be portable and the meaning of each argument would not be clear.  The solution to both these problems is to give these values meaningful names.

Warning

The keyword like arguments used in the following eight (8) macros can not be expressions.  Using anything other than the keywords defined below will result in compile or link time errors of some form.  The exact form of the error messages may be obscure; they are not under the control of this project.

The statusDef4 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
status_t statusDef4({success | warning | error | fatal | done | overrun}, contextId, facilityId, maintainerId);

Description

The statusDef4 macro constructs a status_t value from all its components.  {success | warning | error | fatal | done | overrun} is a keyword like argument specifying the values of the combined indicators.

Returns

The statusDef4 macro returns the constructed status_t value.

See also:

Keyword like arguments, status_t, myStatusDef2, sysStatusDef2, and
isDone, isError, isFatal, isOverrun, isSuccess, isWarning, and
statusDef5, myStatusDef3, sysStatusDef3

The statusDef5 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
status_t statusDef5({good | bad}, {continue | stop}, contextId, facilityId, maintainerId);

Description

The statusDef5 macro constructs a status_t value from all its components.  {good | bad} is a keyword like argument specifying the value of the result indicator.  {continue | stop} is a keyword like argument specifying the value of the continuation indicator.

Returns

The statusDef5 macro returns the constructed status_t value.

See also:

Keyword like arguments, status_t, myStatusDef3, sysStatusDef3, and
canContinue, isBad, isGood, mustStop, and
statusDef4, myStatusDef2, sysStatusDef2

The statusCountDef2 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
status_t statusCountDef2({success | warning | error | fatal | done | overrun}, signed short int);

Description

The statusCountDef2 macro constructs a status_t value that can be used with the statusCount function from all its components.  {success | warning | error | fatal | done | overrun} is a keyword like argument specifying the values of the combined indicators.  The value of signed short int is the value that will be extracted by the statusCount function.

Returns

The statusCountDef2 macro returns the constructed status_t value.

See also:

Keyword like arguments, isCount, statusCount, status_t, statusCountDef3 and
isDone, isError, isFatal, isOverrun, isSuccess, isWarning

The statusCountDef3 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
status_t statusCountDef3({good | bad}, {continue | stop}, signed short int);

Description

The statusCountDef3 macro constructs a status_t value that can be used with the statusCount function from all its components.  {good | bad} is a keyword like argument specifying the value of the result indicator.  {continue | stop} is a keyword like argument specifying the value of the continuation indicator.  The value of signed short int is the value that will be extracted by the statusCount function.

Returns

The statusCountDef3 macro returns the constructed status_t value.

See also:

Keyword like arguments, isCount, statusCount, status_t, statusCountDef2, and
canContinue, isBad, isGood, mustStop

The myStatusDef2 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
status_t myStatusDef2({success | warning | error | fatal | done | overrun}, contextId);

Description

The myStatusDef2 macro is equivalent to

statusDef4({success | warning | error | fatal | overrun}, contextId, RSE_facility, RSE_maintainer).

Returns

The myStatusDef2 macro returns the constructed status_t value.

See also:

status_t, statusDef4, sysStatusDef2, and
isDone, isError, isFatal, isOverrun, isSuccess, isWarning, and
statusDef5, myStatusDef3, sysStatusDef3

The myStatusDef3 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>

myStatusDef3({good | bad}, {continue | stop}, contextId);

Description

The myStatusDef3 macro is equivalent to

statusDef5({good | bad}, {continue | stop}, contextId, RSE_facility, RSE_maintainer).

Returns

The myStatusDef3 macro returns the constructed status_t value.

See also:

status_t, statusDef5, sysStatusDef3, and
canContinue, isBad, isGood, mustStop, and
statusDef5, myStatusDef3, sysStatusDef3

The sysStatusDef2 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>
status_t sysStatusDef2({success | warning | error | fatal | done | overrun}, contextId);

Description

The sysStatusDef2 macro is equivalent to

statusDef4({success | warning | error | fatal | overrun}, contextId, 0, 0).


The contextId value should be one of the E... values defined in the <errno.h> system header.

Returns

The sysStatusDef2 macro returns the constructed status_t value.

See also:

status_t, statusDef4, myStatusDef2, and
isDone, isError, isFatal, isOverrun, isSuccess, isWarning, and
statusDef5, myStatusDef3, sysStatusDef3

The sysStatusDef3 function like macro

Synopsis

#include <stdbool.h>
#include <stdint.h>
#include <status.h>

sysStatusDef3({good | bad}, {continue | stop}, contextId);

Description

The sysStatusDef3 macro is equivalent to

statusDef5({good | bad}, {continue | stop}, contextId, 0, 0).

The contextId value should be one of the E... values defined in the <errno.h> system header.

Returns

The sysStatusDef3 macro returns the constructed status_t value.

See also:

status_t, statusDef5, myStatusDef3, and
canContinue, isBad, isGood, mustStop, and
statusDef5, myStatusDef3, sysStatusDef3

Keyword like arguments.

All the 'Def' macros that are used to construct status_t values take one or two 'keyword like arguments' to specify the state of indicators.  These arguments can not be expressions.  A preprocessor trick is used to associate the words with the values the indicators are to be set to.  (See the Implementation guide for details.)  If you must use an expression to select different status_t values, select between complete status_t, not keyword like arguments.

In addition to the complete keywords, a number of abbreviations have also been defined:

These words are the 'y's used to construct the _RSE_Cy, _RSE_Sy and _RSE_Ry internal constants mentioned in the section on the fields of status_t values. 

Note that these keywords are not reserved; they can be used for other purposes in your code if you want to do so.

Defining ContextIds and MessageIds.

The ContextIds and MessageIds used in status_t values are a global resource that will be needed in several places in a project.  As with any such global set of definitions it will be difficult to keep track of all the places the definitions have to be changed unless their values are defined in only one place, like in a project level header file similar to the system header <errno.h>.

The facility and maintainer identifier management problem.

The total number of different messages or contexts that a status_t value can designate is quite large (>10⁹) but any one project will need only a modest number.  This preliminary implementation allocates a few thousand messages or contexts to each project.  Simple division shows that about a million projects could be handled by this implementation. 

The facility and maintainer Id fields should combine to uniquely designate the project.  However the mapping of this number to the actual project is not a simple problem.

For active groups with multiple projects it makes sense to have the group designate at least part of the mapping.  That is why there are separate facility and maintainer fields; the facility Id is nominally designated by the maintainer.  Not all groups will have multiple projects and it would be wasteful to give a small group a large, multi-facility, message space if they are only going to use a tiny fraction of it.  For these reasons the split between maintainer and facility fields should be considered experimental.

Also note that a large project may need more than the few thousand messages or contexts allocated by this scheme.  This should be rare (>85% of all projects should need less than the preallocated number) that a project will overflow one allocation but there will be some that need more.  This needs to be taken into account as well when allocating project identifiers.

All the above, while important considerations, do not actually specify how project numbers are to be assigned.  Some assignments are required:

• The project identifiers corresponding to EXIT_SUCCESS, EXIT_FAILURE and EOF must be reserved to the 'C' run time and kernel.
• A sequence of project identifiers are needed to designate the 'Count' type of status values.
• At least one and probably a fair size series of project Ids should be reserved for developmental and experimental use.

The rest of the assignments will be arbitrary with some authority (or possibly a small set of coordinated authorities) specifying the mapping.  There are a number of authorities already in existence that perform similar services in different contexts.  They are commercial enterprises and charge fees for each assignment and, as a result, are less than ideal for implementing this function.  Further, a project is probably not a good candidate for such an authority since failing to maintain the project would make the assignments unusable.  That suggests that the Open Source hosting facilities as a group may be the appropriate authorities to perform this task.

Phase II preliminary requirements:

• Translation of messages to different language and culture requirements.
• Message generators – functional components.
• Flexable data structures.
• Communicating with the user.

Work List:

• Do other environments use encoded status values?
• Consider merging Maintainer Id and Facility Id into a single Project Id.