Error generation and handling
TWAPI error generation and handling
This module provides various facilities for generating and
handing errors and Tcl exceptions.
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
||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
Several TWAPI commands pertain to error handling. map_windows_error
returns the text description of an operating system error code.
trap provides exception
handling with finalization features.
For troubleshooting and debug purposes, TWAPI provides the
debuglog command which
writes to an internal log. Applications can use this command for
their purposes. TWAPI uses it internally to log unexpected state
and error conditions.
?MESSAGE? ?MESSAGE? ...
- Writes each specified argument as a message to an internal log.
If no arguments are specified, returns the current contents of the
log. There is an internal limit on the number of messages stored.
Older messages are discarded once the log reaches this limit.
- map_windows_error ERRORCODE
- Returns the text string corresponding to a Windows error
- trap SCRIPT ?onerror ERRORPATTERN ERRORSCRIPT?...
- 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
- try ...
- This is an alias for the trap command. This command is deprecated as it
conflicts with the try command in Tcl 8.6 when
imported into the global namespace.
- 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-2009 Ashok P. Nadkarni