1mNAME0m
       catch - Evaluate script and trap exceptional returns

1mSYNOPSIS0m
       1mcatch 4m22mscript24m ?4mvarName24m?


1mDESCRIPTION0m
       The  1mcatch  22mcommand may be used to prevent errors from aborting command
       interpretation.  The 1mcatch 22mcommand calls  the  Tcl  interpreter  recur-
       sively  to execute 4mscript24m, and always returns without raising an error,
       regardless of any errors that might occur while executing 4mscript24m.

       If 4mscript24m raises an error, 1mcatch 22mwill return a non-zero  integer  value
       corresponding  to the exceptional return code returned by evaluation of
       4mscript24m.  Tcl defines the normal return code from script  evaluation  to
       be  zero  (0),  or  1mTCL_OK22m.   Tcl  also defines four exceptional return
       codes: 1 (1mTCL_ERROR22m), 2 (1mTCL_RETURN22m), 3 (1mTCL_BREAK22m),  and  4  (1mTCL_CON-0m
       1mTINUE22m).  Errors during evaluation of a script are indicated by a return
       code of 1mTCL_ERROR22m.  The other exceptional return codes are returned  by
       the  1mreturn22m,  1mbreak22m,  and 1mcontinue 22mcommands and in other special situa-
       tions as documented.  Tcl packages can define new commands that  return
       other integer values as return codes as well, and scripts that make use
       of the 1mreturn -code 22mcommand can also have return codes other  than  the
       five defined by Tcl.

       If  the 4mvarName24m argument is given, then the variable it names is set to
       the result of the script evaluation.  When the  return  code  from  the
       script  is  1 (1mTCL_ERROR22m), the value stored in 4mvarName24m is an error mes-
       sage.  When the return code from the script is 0  (1mTCL_OK22m),  the  value
       stored in 4mresultVarName24m is the value returned from 4mscript24m.

       If 4mscript24m does not raise an error, 1mcatch 22mwill return 0 (1mTCL_OK22m) and set
       the variable to the value returned from 4mscript24m.

       Note that 1mcatch 22mcatches all exceptions, including  those  generated  by
       1mbreak  22mand  1mcontinue  22mas  well as errors.  The only errors that are not
       caught are syntax errors found when the script is  compiled.   This  is
       because the catch command only catches errors during runtime.  When the
       catch statement is compiled, the script is compiled  as  well  and  any
       syntax errors will generate a Tcl error.


1mEXAMPLES0m
       The  1mcatch  22mcommand may be used in an 1mif 22mto branch based on the success
       of a script.
              if { [1mcatch 22m{open $someFile w} fid] } {
                  puts stderr "Could not open $someFile for writing\n$fid"
                  exit 1
              }

       The 1mcatch 22mcommand will not catch compiled  syntax  errors.   The  first
       time proc 1mfoo 22mis called, the body will be compiled and a Tcl error will
       be generated.
              proc foo {} {
                  1mcatch 22m{expr {1 +- }}
              }


1mSEE ALSO0m
       break(n), continue(n), error(n), return(n), tclvars(n)


1mKEYWORDS0m
