Error generation and handling
TWAPI error generation and handling
TWAPI generates Tcl exceptions when errors are
encountered. Information pertaining to the error is stored in Tcl
global variables as with any standard Tcl errors. The global variable
errorInfo contains a traceback of the Tcl stack when the error
occured. The global errorCode contains a list with additional
information about the error. The first element is the error class
and determines the format of the rest of the list. This may take
one of the following values:
This error class corresponds to Windows error codes. The second element of
the list is the integer Windows error code. The third element is the
corresponding localized text string describing the error. The fourth element
is optional and its format is dependent on the specific error code.
The command win32_error can be used to generate
an error in this format.
This error class is used for non-Windows related errors, for example invalid
options to commands. The format is similar to that of TWAPI_WIN32
except that the error code is an internal TWAPI error code and the text
is not localized.
Several TWAPI commands pertain to error handling.
returns the text description
of an operating system error code.
try provides exception handling with finalization features.
- map_windows_error ERRORCODE
Returns the text string corresponding to a Windows error code.
- try SCRIPT ?onerror ERRORPATTERN ERRORSCRIPT?... ?finally FINALSCRIPT?
The command executes SCRIPT in the caller's context. If the script
completes without generating any Tcl exceptions, the command executes
the script FINALSCRIPT if specified. The result of the command is
the result of SCRIPT.
If SCRIPT generates any errors, the command matches the
Tcl global ::errorCode variable against each specified
ERRORPATTERN in turn. When the first match is found, the corresponding
ERRORSCRIPT is executed. Then FINALSCRIPT is executed if specified.
The return value from the command
is the result of the executed ERRORSCRIPT script.
If the none of the ERRORPATTERN arguments match when an error
occurs in SCRIPT, the command executes FINALSCRIPT if specified,
and then regenerates the original error.
Each ERRORPATTERN should be a list and is matched against the first
(facility) and second (code) elements of ::errorCode. If
ERRORPATTERN is empty, it matches any value of ::errorCode.
If ERRORPATTERN contains only one element, it is matched against
the first element of ::errorCode with the second field of
::errorCode not used for matching. When matching against the second
element of ::errorCode, first a exact string match is tried and
if that fails, an integer match is tried if both operands being compared
are valid integers.
When a ERRORSCRIPT script is run, the global Tcl variables
::errorCode, ::errorInfo are automatically brought into scope
without needing a global statement in the script and contain
the values set when SCRIPT generated the error. In addition,
the variable ::errorResult is set to the error message set by
the original error. This behavior is
similar to the try_eval command from TclX.
- win32_error WINERROR ?MESSAGE?
Generates a Tcl exception corresponding to the Windows error code WINERROR.
MESSAGE may be specified as the error message in which case the
system error message for WINERROR is appended to it.
Copyright © 2003-2006 Ashok P. Nadkarni