About SCOadmin error handling

An error is not a simple occurence that can be described by a simple message or error code, it is a state resulting from a series of steps that were taken when attempting to perform a task. The more information available about an error, the easier it is to correct its cause. Error information must be available in a form that is easy for either a program to interpret or a human to interpret (localized). A typical sequence of events leading to an error is caused by a higher level module making a request to a lower level module, which in turn may execute that request by making a request of even lower level modules. At some point along the way, an error is detected, either caused by bad data in the request or an external state. The error status is then returned up the stack of requesting modules. Each module at each of the layers has some knowledge about the the events leading up to the error. It is important to catch errors at each level and take corrective action or push the information (and its context) on the stack to be passed up the next level (and eventually to the user).

The basic Tcl error-handling facilities implemented in the error and catch functions allow procedures to pass error information - see error(TCL) and catch(TCL). SCOadmin builds on this functionality by adding the concept of an ``error stack'', a data structure that stores error information from all levels of the attempted operation. For example, if an application needs to open a log file as part of its initialization procedure and fails to open the file because it does not have permission, the stack of errors may include the following elements, from most general to most specific:

• application failed to initialize

• application failed to open logfile

• operation not permitted

Each element in a SCOadmin error stack is a Tcl list containing an error ID, the localized error message, and any optional error data. An error ID is simply a message ID used within the context of error management.

For debugging purposes, the ErrorOutput routine allows the text from an error stack to be displayed. ErrorId, ErrorText, and ErrorData allow the examination of specific parts of one element of the error stack. See Error(TCL_ADM) for more information.

When a procedure within SCOadmin attempts an operation that might cause an error, it can catch an error, throw an error (possibly after adding additional error information), do both, or neither.

To catch an error caused by an operation, a procedure must call the operation indirectly by using ErrorCatch(TCL_ADM). This is similar to using catch(TCL), but ErrorCatch allows you to store the error stack in a designated variable. If the error is serious enough to stop processing, you can add additional information to the error stack by calling ErrorPush with the error ID which describes the error.

With errors that are not the result of an operation called with ErrorCatch (in other words, if there is no error stack for the error yet), call ErrorPush and ErrorThrow. For errors resulting from a UNIX operation that leaves a standard UNIX error in the global ErrorCode variable, ErrorPushUnix can be called instead of ErrorPush to push the error ID that matches the UNIX error.

If a procedure attempts an operation directly (without using ErrorCatch) that results in an error, the procedure will return to its calling procedure. The result is similar to what would happen when calling a Tcl function that calls error(TCL).

ErrorTopLevelCatch provides the outermost trap for error messages and is described in ``Top level error trap''. However, when running the application errors should be displayed to the user if possible. The UiStart procedure includes the following code:

   VtSetAppValues $vtApp \
           -versionString "$appvals(title) $appvals(version)" \
           -errorCallback {SaUnexpectedErrorCB {}}