| ActiveTcl User Guide |

# Debugging and Errors - errorInfo errorCode catch error return

In previous lessons we discussed how the `return` command could be used to return a value from a proc. In Tcl, a proc may return a value, but it always returns a status.

When a Tcl command or procedure encounters an error during its execution, the global variable `errorInfo` is set, and an error condition is generated. If you have proc `a` that called proc `b` that called `c` that called `d` , if `d` generates an error, the "call stack" will unwind. Since d generates an error, `c` will not complete execution cleanly, and will have to pass the error up to `b` , and in turn on to `a`. Each procedure adds some information about the problem to the report. For instance:

    proc a {} {
        b
    }
    proc b {} {
        c
    }
    proc c {} {
        d
    }
    proc d {} {
        some_command
    }

    a

Produces the following output:

    invalid command name "some_command"
        while executing
    "some_command"
        (procedure "d" line 2)
        invoked from within
    "d"
        (procedure "c" line 2)
        invoked from within
    "c"
        (procedure "b" line 2)
        invoked from within
    "b"
        (procedure "a" line 2)
        invoked from within
    "a"
        (file "errors.tcl" line 16)

This actually occurs when any exception condition occurs, including `break` and `continue`. The `break` and `continue` commands normally occur within a loop of some sort, and the loop command catches the exception and processes it properly, meaning that it either stops executing the loop, or continues on to the next instance of the loop without executing the rest of the loop body.

It is possible to "catch" errors and exceptions with the `catch` command, which runs some code, and catches any errors that code happens to generate. The programmer can then decide what to do about those errors and act accordingly, instead of having the whole application come to a halt.

For example, if an `open` call returns an error, the user could be prompted to provide another file name.

A Tcl proc can also generate an error status condition. This can be done by specifying an error return with an option to the `return` command, or by using the `error` command. In either case, a message will be placed in `errorInfo`, and the proc will generate an error.

`error` `message` `?info?` `?code?`

  Generates an error condition and forces the Tcl call stack to unwind, with error information being added at each step.

  If `info` or `code` are provided, the errorInfo and errorCode variables are initialized with these values.

`catch` `script` `?varName?`

  Evaluates and executes `script`. The return value of catch is the status return of the Tcl interpreter after it executes `script` If there are no errors in `script`, this value is 0. Otherwise it is 1.

  If `varName` is supplied, the value returned by `script` is placed in `varName` if the script successfully executes. If not, the error is placed in `varName`.

`return` `?-code code?` `?-errorinfo info?` `?-errorcode errorcode?` `?value?`
  Generates a return exception condition. The possible arguments are:
  `-code` `code`
    The next value specifies the return status. `code` must be one of:
    - `ok` - Normal status return
    - `error` - Proc returns error status
    - `return` - Normal return
    - `break` - Proc returns break status
    - `continue` - Proc returns continue status
    These allow you to write procedures that behave like the built in commands `break`, `error`, and `continue`.
  `-errorinfo` `info`
    `info` will be the first string in the `errorInfo` variable.
  `-errorcode` `errorcode`
    The proc will set `errorCode` to `errorcode`.
  `value`
    The string `value` will be the value returned by this proc.
`errorInfo`
  `errorInfo` is a global variable that contains the error information from commands that have failed.
`errorCode`
  `errorCode` is a global variable that contains the error code from command that failed. This is meant to be in a format that is easy to parse with a script, so that Tcl scripts can examine the contents of this variable, and decide what to do accordingly.

## Example

    proc errorproc {x} {
        if {$x > 0} {
        error "Error generated by error" "Info String for error" $x
        }
    }

    catch errorproc
    puts "after bad proc call: ErrorCode: $errorCode"
    puts "ERRORINFO:\n$errorInfo\n"

    set errorInfo "";
    catch {errorproc 0}
    puts "after proc call with no error: ErrorCode: $errorCode"
    puts "ERRORINFO:\n$errorInfo\n"

    catch {errorproc 2}
    puts "after error generated in proc: ErrorCode: $errorCode"
    puts "ERRORINFO:\n$errorInfo\n"

    proc returnErr { x } {
        return -code error -errorinfo "Return Generates This" -errorcode "-999"
    }

    catch {returnErr 2}
    puts "after proc that uses return to generate an error: ErrorCode: $errorCode"
    puts "ERRORINFO:\n$errorInfo\n"

    proc withError {x} {
        set x $a
    }

    catch {withError 2}
    puts "after proc with an error: ErrorCode: $errorCode"
    puts "ERRORINFO:\n$errorInfo\n"

    catch {open [file join no_such_directory no_such_file] r}
    puts "after an error call to a nonexistent file:"
    puts "ErrorCode: $errorCode"
    puts "ERRORINFO:\n$errorInfo\n"