Error(3tlib)

Synopsis

Description

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

errorStackVarName

the name of a Tcl variable that contains the error stack.

throwflag

boolean. If 1, the function will perform an ErrorThrow.

level

indicates which stack frame to access. Defaults to the top (0).

messageId

error message token as used with IntlLocalizeMsg(3tlib).

argList

optional list of positional arguments for the internationalized message.

dataList

arbitrary user-defined data that may be optionally included in the stack frame

FileId

Tcl file identifier as returned from open(1tcl).

References