Status and Text Reference Coding

Analysis

The purpose of this document is to record ideas and conclusions after the requirements are set in order to convert those requirements into specifications.  As such it is a transition document.  If reviewed as part of a legal search for prior art and originality, please remember that a post hoc record can make a creative sequence seem mundane and unoriginal.

Why two status bits?

Current Microsoft Windows makes do with only a single severity bit and only distinguishes two conditions.  The older Microsoft NT has two severity bits and distinguished between four possible conditions including 'informational'.  VMS has three severity bits and distinguished between five possible conditions including 'informational'.  How many are actually needed?

The 'informational' codes in these schemes are not status conditions.  They are indicators that the value is a message to the user rather than an internal communication value.  (Final exit values serve both as a interprogram communication device and as a way to inform users of what has happened and will not be just 'informational'.)  While the requirements say that having an 'informational' function would be nice, that is really a separate function from status encoding.  That reduces the maximum number of distinct status codes in the reference schemes to four.  Four distinct codes can be encoded in two bits.

Thus the requirement section says two flags are needed: one to indicate the quality of the result and the other to indicate a Stop/Go condition.  Some situations may not need the Stop/Go condition but may be able to use an additional level of severity coding.  There is no particular reason why the Stop/Go indicator can not be serve as a severity modifier when a continuation indicator is not needed.  The two situations are distinguishable by context.

These combinations of states need descriptions.  The quality and Stop/Go combinations are as follows:

The following words suggest themselves as names for these combinations: Success, Done, Failure, and Overrun.  (That last one is a bit of a stretch.)

When interpreted as error severity codes these alternate descriptions apply:

The lack of distinction between severe and fatal errors a bit troublesome.  However, none of the reference schemes made such a distinction even when they could have done so.

Text mapping?

The reference schemes both use the same text for all severity values.  This has proved to be confusing on occasion; associating the phrase 'success' with a severe or fatal error conditions really isn't a great idea.  This strongly suggests that the condition or severity should be part of text selection process.

One of the less urgent requirements is for ways to store text for other than status reporting purposes.  (These are the 'informational' codes mentioned previously.)  For this kind of use, the condition bits, which help determine the text mapping, can be included in the calculation of the selection code.

Alterations from reference facilities

The message or code field in all the reference schemes is really too large.  A reasonable size for the context selectors is a power of 2 that will meet the needs of at least 85% of projects that could potentially use this facility.  (The 85% level is taken from the nominal criteria for setting traffic speed limits.)

An arbitrary specification of ten bits seem to be a good first approximation of the size of this field.  If more messages are really needed for a single project, adjacent facilities can be combined.  The order and encoding of the fields within the status type should be such that too large a code value will automatically increments the facility field value.  It would be a very good idea to survey the available open source projects and set the field size so that something like 85% (or more) of the projects can use a single facility code.

The originator field (1 bit) and facility field in the reference schemes are completely out of balance.  The name is also a little out of line with the meaning in this project; the term maintainer is a better match to its intended use.  A slightly more equal division would also be better (intentional understatement).  There is a natural boundary within a status value at the '16 bit word' boundary.  That suggests that the size of the facility field should be 5 bits for 32 bit architectures.  Again, the order and encoding of fields within the status type should be such that too large a facility identifier will automatically increments the maintainer field value.  Note that this division is completely arbitrary and may require a complete reanalysis when the maintainer registration problem is addressed.

One situation that is certain to arise is someone will want to return a count as part of a status value.  (Mapping the count to text should not be needed for this kind of situation.)  A 10 bit code field may not be large enough for this application, especially if the condition bits are needed for their nominal purpose.  The combination of the facility field with the code field will produce suggested field size of 15 bits which has a much more acceptable range of values.  The reservation of two adjacent maintainer values would bring the count up to 16 bits, the nominal size for short int.

Known problems

The facility and maintainer registries of the reference shemes are outside the control of this project.  The new facility registries should be under the control of the designated maintainer.  How maintainers are to be registered is an open question.

A small maintainer may not need more than one or two facility identifiers and, even at its smallest field size (5 bits), allocating all the facility identifiers to such a maintainer would be a waste of a valuable resource.  Therefore some maintainer codes will probably have to be sub-allocated to groups of maintainers.

The use of such a registry may very well extend past the other needs for active maintenance of this project.  Keeping such a registry up to date will almost certainly require participation of SourceForge.  If SourceForge is involved, they may need to charge a small fee for this service.

The implied scheme for facility and maintainer codes is very nebulous and is very likely to need a major redesign.

NOTE

The information on this document is preliminary and may not be maintained after initial development is complete.  However it does provide some information that is useful and does not really fit into the Programmer's Guide.  If any of the information here does end up in the Programmer's Guide, Design Notes, Implementation Notes or Maintenance Notes, it will not be updated here after implementation.  (If it doesn't fit anywhere else, stick it in the Implementation Notes.)