Error generation and handling

TWAPI error generation and handling

SYNOPSIS

DESCRIPTION

This module provides various facilities for generating and handing errors and Tcl exceptions.

Error generation

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:

Error handling

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.

Error Logging

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.

Commands

debuglog ?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 code.

trap 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.

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

Copyright © 2003-2009 Ashok P. Nadkarni