UEH

Applications which consist of several separate components and/or which use components or packages of other software tend to lack cohesive error handling due to the separate "error domains" owned by each component. The Unified Error Handler (UEH) alleviates this problem by fitting all component error domains into one overall error domain and prevents collisions between the same error "codes" from different components. This allows easier error handling in the calling code and provides a mechanism for error "passthrough" from situations such as: component A calls component B calls component C, which generates and error condition. B's operation fails as a result and passes C's error code back to A so that the ultimate cause of the problem can be discerned, even if A doesn't know about C. B also can return its own error condition code on an error stack so that A can attempt alternate processing depending upon the type of failure in B, regardless of the ultimate failure in C.

Despite its name, UEH can be used to do any kind of status notifications - not only errors. For instance, warnings, hints, and informational status can be passed.

Note that UEH could also mean "Unified Exception Handler" since UEH is independant of the method for passing errors back to calling code. In the case of C++, an exception handler which knows about UEH can be written and can be thrown, thus passing UEH-compliant error codes to the caller.

The way UEH works is that every component you write is assigned a unique 4-byte integer value, called a facility code. Errors are passed using a Unified Error Code (UEC), which consists of the facility code and a 4-byte integer condition code. Facility codes are absolutely unique: anyone wishing to produce software which is UEH-compliant must obtain a facility code for each component. The process is simple and free: send email with a body consisting of three lines:

REQUEST

count

entity

where "count" is the number of facility codes you want to allocate and "entity" is your name, or the name of your company. You can request as many facility codes as you wish, but no more than ten (10) at a time per individual, or 100 at a time for a company/organization. Your request will be processed and your unique facility codes will be assigned to you. You will receive an email informing you as to the codes that have been assigned to you. For a list of currently assigned facility codes, click here.

Why not assign facility code dynamically? Several reasons:

1. Logging error codes consumes more resources (logging two integers is faster, and requires less space, than logging the text of the message). While one would hope that the number of errors generated by an application would be small, it is possible that a great many notification messages could be generated, especially during debugging sessions.
2. If you want the calling code to be able to handle specific error codes from specific facilities, you have no easy way of identifying if a UEC is from the specific component you are checking for. If you didn't mind the overhead, you could request the name of the unknown facility and use that, but there is no guarantee that two different components will have unique names. It is guaranteed, however, that two different components will have two different unique static facility codes.
3. In a client/server application (especially when the client and server are on different machines) both the client and server may dynamically assign the same facility code to their components. When UECs are shared between the client and server, there would be a collision of error domains. You could get around this by having the server serve up dynamic facility codes, but that makes the coding more complicated (UEH is supposed to simplify your life), and you may not want the server to have the overhead of handling hundreds (or thousands!) of additional requests. Further, the problem grows exponentially if your server itself is a client to other servers. Besides, if your client has connections to several servers, which server serves up new dynamic facility codes?

Downloads (Last update: 29-March-2002)

A Windows 95/98/ME/XP/NT/2000 implementation of the UEH manager is available here for download: UEH32 V1.2. The file is a self-extracting archive containing the DLL and documentation. It also contains the UEHErr program which can be used to translate error codes. Sources are also available. This software is released to the public domain. UEH32 is compliant with version 1.2 of the UEH specification.

The UEH specification

UEH is a component of the Application Foundation, hosted on