Status and Text Reference Coding

This project is currently in the design and documentation stage.  This web page is also less than beautiful.  Suggestions on how to improve either the project itself, these web pages or both are welcome here.

Purpose and Origins

While 'C' and Unix use the errno global variable to communicate the cause of errors, there are some very serious problems associated with that scheme.  (See the background page for more information.)

This project discusses and implements an alternative method for encoding status information, and associating descriptive text with that information, in an easy to understand way.

This facility was inspired by a facility in Digital Equipment Corporation's VMS operating system.  A similar facility exits on Microsoft's Windows platform.  This facility is broadly similar to its predicessors but is an independent and original development.  In particular an attempt has been made to bring this facility into alignment with the POSIX standards.

Outlook

If the facility implemented by this project is used in other projects, the following benefits are likely to result:

• A cleaner interaction between project components.  It will be possible to pass more information on both successful results and less than successful results back to the caller without having to resort to global variables that are not usable in or severely complicate a multi-threaded environment.  This means you will not be trapping yourself in an environment where your performance is unintentionally limited.  Further, this will often mean fewer changes will be needed in your application and the needed changes will be easier to identify when components you depend upon change.
• Better communication with users and better error report information.  It will be possible to describe what isn't working more precisely, giving users and support staff a better understanding of what is going wrong and what needs to be done get the results the user wants.  This may reduce the resources you need to devote to customer support.
• With the implementation of Phase II, it will be easier to add support for multiple languages and, with appropriate locale support, multiple cultures.  By removing the need for embedding text in your applications, it will be easier to translate messages to other cultural contexts and languages.  This can reduce the load on your technical and support staff because expert, but less technical, personnel will be able to perform much of the translation.

Design Phases

The primary implementation will be for the 'C' language.  An implementation for 'C' can be translated to other languages with a preprocessor or that can use the 'C' preprocessor as a front end.  Special implementations for 'C++' and other languages may or may not be produced as user demand dictates.

This project has been split into two phases.  This first phase must be implemented before the design of the second phase begins.

The first phase provides the encoded status data type and related components.

The second phase provides services for managing internationalization and message customization.

Links to usage information

Programmer's Guide – descriptive information intended for the people using the results from this project.

Links to developers' information

Implementation Notes – descriptions of the project components, their inter-relation and theory of operation.  This information is a primary resource for people maintaining or modifying the source material for this project.

Maintenance Notes – warnings about things that didn't work and things to watch out for when working on project elements.  It should summarize the reasons for major changes and significant bug fixes.  It should be maintained by the quality assurance team and is required reading for maintainers and project developers.

Links to other project pages

Background – what is available on other platforms.

Requirements – elements, features, interfaces and procedures that must be present in the result.  This is a design phase document and may or may not be kept up to date after the design phase is complete.

Analysis – an analysis and extension of the requirements with the intent of specifying a usable result.  This is a design phase document and may or may not be kept up to date after the design phase is complete.

Specifications – a high level description of what the project will do.  This is a design phase document and may or may not be kept up to date after the design phase is complete.

Design – an analysis of the specifications with the intent of implementing the project.  This is a design phase document and may or may not be kept up to date after the design phase is complete.

NOTE

The formal documentation technique used for this project is mostly for demonstration purposes.  It can be made to work for a small project like this one.  For large projects this outline may be useful, but strict adherence to this documentation methodology can seriously hamper the progress of a project.  What must be done in large projects is to recognize that all the useful information from the early documents will be copied into later documents and that maintaining the early documents is almost always a waste of resources.

Major project work items:

• Posted the design and documentation for review.  Make revisions as needed.
• Implement regression tests for Phase I.
• Design and Implement the maintainers' registry.  (This is a major stumbling block.)
• Research requirements and existing implementations for Phase II.  (Frankly, I'm going to need some help with this one.)
• Design and implementation of Phase II.  (This item will be expanded when needed.)

Secondary and continuing project work items:

• Identify and document additional existing facilities similar to the facilities provided by Phase I.
• Implement a generic large binary 2s complement implementation.

Minor project work items:

• Revise each project document to reflect changes needed by subsequent documents.  (This is in support of the documentation technique demonstration and must not get in the way of over-all progress on the project.)