Catch Until now we have ignored the possibility of errors. In practice, however, a command will raise an error if it is called with the wrong number of arguments, or if it detects some error condition particular to its implementation. An uncaught error aborts execution of a script.[*] The catch command is used to trap such errors. It takes two arguments: [*] More precisely, the Tcl script unwinds and the current Tcl_Eval procedure in the C runtime library returns TCL_ERROR. There are three cases. In interactive use, the Tcl shell prints the error message. In Tk, errors that arise during event handling trigger a call to bgerror, a Tcl procedure you can implement in your application. In your own C code, you should check the result of Tcl_Eval and take appropriate action in the case of an error.
catch command ?resultVar? The first argument to catch is a command body. The second argument is the name of a variable that will contain the result of the command, or an error message if the command raises an error. catch returns zero if there was no error caught, or a nonzero error code if it did catch an error. You should use curly braces to group the command instead of double quotes because catch invokes the full Tcl interpreter on the command. If double quotes are used, an extra round of substitutions occurs before catch is even called. The simplest use of catch looks like the following: catch {command } A more careful catch phrase saves the result and prints an error message: Example 6-14 A standard catch phrase. if {[catch { command arg1 arg2 ... }result]} { puts stderr $result } else { # command was ok, result contains the return value } A more general catch phrase is shown in the next example. Multiple commands are grouped into a command body. The errorInfo variable is set by the Tcl interpreter after an error to reflect the stack trace from the point of the error: Example 6-15 A longer catch phrase. if {[catch { command1 command2 command3 } result]} { global errorInfo puts stderr $result puts stderr "*** Tcl TRACE ***" puts stderr $errorInfo } else { # command body ok, result of last command is in result } These examples have not grouped the call to catch with curly braces. This is acceptable because catch always returns an integer, so the if command will parse correctly. However, if we had used while instead of if, then curly braces would be necessary to ensure that the catch phrase was evaluated repeatedly. Catching More Than Errors The catch command catches more than just errors. If the command body contains return, break, or continue commands, these terminate the command body and are reflected by catch as nonzero return codes. You need to be aware of this if you try to isolate troublesome code with a catch phrase. An innocent looking return command will cause the catch to signal an apparent error. The next example uses switch to find out exactly what catch returns. Nonerror cases are passed up to the surrounding code by invoking return, break, or continue: Example 6-16 There are several possible return values from catch. switch [catch { command1 command2 ... } result] { 0 { # Normal completion } 1 { # Error case } 2 { return $result ;# return from procedure} 3 { break ;# break out of the loop} 4 { continue ;# continue loop} default { # User-defined error codes } } | 
