Error(TCL_ADM)

Error -- error handling interface for SCOadmin clients/OSAs

Syntax

ErrorThrow errorStackVarName
ErrorCatch errorStackVarName throwflag command resultVarName [messageId [argList]]
ErrorTopLevelCatch command description
ErrorStackSize errorStackVarName
ErrorId errorStackVarName [level]
ErrorData errorStackVarName [level]
ErrorText errorStackVarName [level]
ErrorPush errorStackVarName throwflag messageId [argList [dataList]]
ErrorPushUnix errorStackVarName throwflag [messageId [argList]]
ErrorAddData errorStackVarName dataList
ErrorOutput errorStackVarName [fileId [options [prefix]]]

Description

These functions provide a full-featured error handling interface for managing control flow and the error stack data structure including error identifiers and internationalized text.

The error stack is stack of 0 or more error frames. Each frame contains the following components:

Error Identifier Token
Error Text (internationalized)
Error Data

New error frames can be pushed on the stack and each component Each of stack frame components can be accessed from any stack frame.

Error Control

ErrorCatch: provides an interface to the Tcl catch command that performs special processing for SCOadmin standard errors. The command is executed. If it does not return TCL_ERROR, then the integer result is returned as the result of the ErrorCatch command and the string result of command is returned in the variable resultVarName. If an error occurs and errorCode contains an error stack (class ERRORSTACK), then the ErrorCatch returns ``1'' and result_variable will contain the error stack. If an error of class UNIX is returned, then a standard error stack is returned in resultVarName containing a UNIX error, as if ErrorPushUnix had been called. If any other class of error occurred, then ErrorCatch will not return, but will continue procedure call stack unwinding. A throw option may be specified (throwflag), in which case any error that occurs will be caught, the optional error added to the stack and then the unwinding will continue. This is particularly useful when calling a Tcl function that can return a UNIX class error, such as open, or when all that needs to be done is add an error to the stack and continue unwinding. The global variables errorInfo and errorCode are also available.
ErrorTopLevelCatch: provides a catch to wrap around the entire execution of a Tcl program. If an error occurs and it falls all the way back to this catch, the error will be logged and a message sent to standard error. It is assumed that any error that makes it here is a bug in the program. This is the equivalent of a core dump for Tcl programs. This routine should be placed around the top level code in a program, excluding procedure definitions.
ErrorThrow: throw an existing error stack. The procedure call stack will be unwound until an ErrorCatch is encountered. This functionality is normally obtained by calling the ErrorPush routines with throwflag set to true, but occasionally it is necessary to manage the error return more closely.

Error Stack Handling

ErrorStackSize: get the current size of the error stack (the number of frames).
ErrorId: get the message identifier for an error out of a stack frame.
ErrorData: get error data out of the stack frame.
ErrorText: get localized error text out of a stack frame.
ErrorPush: push an error frame onto an error stack. Optionally throw an error if throwflag is set to 1.
ErrorPushUnix: push a UNIX error onto an error stack. It is assumed that a Tcl command that got a UNIX system or library call error has just occurred and the variable errorCode still contains the error.
ErrorAddData: add error data to the entry on the top of the error stack. Since it is not possible to retrieve arguments formatted into a localized message, this function allows inclusion of data that can then be accessed by code examining the error. The actual contents are defined on by the client on an error ID basis. This will append to existing extra information that is already associated with the top of stack entry. There must be an entry on the top of the stack.
ErrorOutput: output an error stack to file in a human-readable format.

Arguments