Status and Text Reference Coding

Specification

Headers

If at all possible, the header containing the definitions for this facility should be called <status.h>.

Types

A type, preferably called status_t, should be declared by the header.  It should be an integral type assignment compatible with the macros EXIT_SUCCESS, EXIT_FAILURE and EOF.  Access to the various fields in the status_t value must be made using masks.

The size of the fields is as follows:

_RSE_Wcontext >= 10

This field indicates the context of the status value.  The size of this field is approximate; an actual survey of open source projects is needed to determine the acceptable size of this field.

_RSE_Wcontinue == 1

This field's value indicates if normal operations can continue.

_RSE_Wfacility >= 5

This field identifies the facility issuing the status value.  If the size of status_t is 16 bits, this field will be only 4 bits wide.  If possible, the combination of the result (see below), the context (above) and this field should fit in a architecture defined directly accessable value.

_RSE_Wmaintainer >= 10

This field identifies the maintainer of the facility issuing the status value.  If the size of status_t is 16 bits, this field will be missing; that is its width will be 0.

_RSE_Wresult == 1

This field's value indicates if the result is usable.

In the following specification, the x must be replaced by one of the words following _RSE_W in the above list.

For each of the non-zero widths specified, there will also be a value defined whose name has the form _RSE_Vx that indicates the bit in the status value corresponding to the least significant bit of the field value.  This value for zero width fields may be defined but should not be used.

The order of the fields within the status type should be such that a too large context value automatically increments the facility field value.  Also, the order of fields within the status type should be such that a too large facility identifier automatically increments the maintainer field value if such a field exists.  The maintainer field, if it exists, or the facility field if the maintainer field does not exist should not overflow into any higher fields.

For each of the non-zero width fields specified, there will also be a value defined whose name has the form _RSE_Lx that has a value equivalent to (1 << RSE_Vx).  This value for zero width fields may be defined but should not be used.  That is multiplying a desired field value by this number will position that value correctly for insertion into a status_t value.

For each of the non-zero width fields specified, there will also be a value defined whose name has the form _RSE_Mx that defines a mask for isolating the field within the status_t value.  The expression (status & _RSE_Mx) / _RSE_Lx can be used to get the value of field x.  This value for zero width fields may be defined as zero, but should not be used.  If the value of a zero width field is used, the result may be 'undefined behavior'.

Note: the prefix _RSE_ may have to be changed if it conflicts with other common usage.

Macros

The following macros may be defined by the user if needed before the header is included:

RSE_facility

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

RSE_maintainer

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

Note: the prefix RSE_ may have to be changed if it conflicts with other common usage.

Functions and function like macros.

The following functions or function like macros must be defined -

Usable result test indicators:

isBad(status)

true if the status indicates an unusable result.

isGood(status)

is true if the status indicates a usable result.

Operation sequence test indicators:

canContinue(status)

is true if the status indicates the operation sequence can continue.

mustStop(status)

is true if the status indicates the operation sequence can not continue.

Combined indicator tests:

isDone(status)

is true if the result is the last value in a sequence of values. 
Equivalent to (isGood(status) && mustStop(status)) except that it evaluates status only once.

isError(status)

is true if the status indicates an error condition. 
Equivalent to (isBad(status) && canContinue(status)) except that it evaluates status only once.

isFatal(status)

is true if the status indicates a severe or fatal error condition. 
Equivalent to (isBad(status) && mustStop(status)) except that it evaluates status only once.

isOverrun(status)

is true if the status indicates that a sequence nominally terminated by a isDone status has been continued. 
Equivalent to (isBad(status) && mustStop(status)) except that it evaluates status only once.

isSuccess(status)

is true if the status indicates a normal completion condition. 
Equivalent to (isGood(status) && canContinue(status)) except that it evaluates status only once.

isWarning(status)

is true if the status indicates a warning or alternate completion condition.
Equivalent to (isGood(status) && mustStop(status)) except that it evaluates status only once.

Access to other status components:

statusContextId(status)

returns the context identifier component of the status value.

statusCount(status)

returns the count value used to construct the status value.  The count value returned is a 16 bit signed integer.  This function will not be available in environments where int's are less than 32 bits wide.

isCount(status)

is true if status contains a count value.

statusFacilityId(status)

returns the facility identifier component of the status value.

statusMaintainerId(status)

returns the software maintainer identifier component of the status value.  This function will not be available in environments where int's are less than 32 bits wide.

statusMessageId(status)

returns a message identifier that combines the ContextId and the combined indicator fields from the status value.

Status definitions:

statusDef5(good|bad, continue|stop, contextId, facilityId, maintId)

constructs a status code 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.

statusDef4(success|warning|done|error|fatal|overrun, contextId, facilityId, maintId)

constructs a status code from all its components.  success|warning|done|error|fatal|overrun is a keyword like argument specifying the values of the combined indicators.

statusCountDef3(good|bad, continue|stop, count)

constructs a status code that has a combined contextId and facilityIdthat, when extracted by the statusCount, returns the value of count.  The count value should be in the range of 16 bit signed integers.  This function will not be available in environments where int's are less than 32 bits wide.

statusCountDef2(success|warning|done|error|fatal|overrun, count)

constructs a status code that has a combined contextId and facilityIdthat, when extracted by the statusCount, returns the value of count..  The count value should be in the range of 16 bit signed integers.

myStatusDef3(good|bad, continue|stop, contextId)

constructs a status code with preset facility and maintainer identifier values.  The keyword arguments are the same as for statusDef5.

myStatusDef2(success|warning|done|error|fatal|overrun, contextId)

constructs a status code with preset facility and maintainer identifier values.  The keyword argument is the same as for statusDef4.

sysStatusDef3(good|bad, continue|stop, contextId)

constructs a status code with the system (undefined) facility and maintainer identifier values.  The keyword arguments are the same as for statusDef5.  The contextId value should be one of the E... values defined in the <errno.h> system header.

sysStatusDef2(success|warning|done|error|fatal|overrun, contextId)

constructs a status code with the system facility and maintainer identifier values.  The keyword argument is the same as for statusDef4.  The contextId value should be one of the E... values defined in the <errno.h> system header.

Note that specifying an incorrect keyword must produce an error during compilation, however the relevance of the error description produced by a compiler is beyond the control of this project and it may not be easy to comprehend that the message generated is due to a invalid keyword value.

Note: the use of capital letters in function names is somewhat controversial, but I am not aware of any rational for not using this device to make reading code easier.

NOTE

The information on this page is preliminary and will not be maintained after initial development is complete.  For current information see the Programmer's Guide.