Tcl Built-In Commands                                   catch(1T)





NAME
     catch - Evaluate script and trap exceptional returns

SYNOPSIS
     catch script ?varName?



DESCRIPTION
     The catch command may be used to prevent errors from  abort-
     ing command interpretation.  The catch command calls the Tcl
     interpreter  recursively  to  execute  script,  and   always
     returns  without  raising an error, regardless of any errors
     that might occur while executing script.

     If script raises an error,  catch  will  return  a  non-zero
     integer  value  corresponding to the exceptional return code
     returned by evaluation of script.  Tcl  defines  the  normal
     return  code  from  script  evaluation  to  be  zero (0), or
     TCLOK.  Tcl also defines four exceptional return  codes:  1
     (TCLEROR),   2   (TCLRETURN),   3   (TCLBREAK),   and  4
     (TCLCONTINUE).  Errors during evaluation of  a  script  are
     indicated  by  a return code of TCLEROR.  The other excep-
     tional return codes are returned by the return,  break,  and
     continue  commands  and in other special situations as docu-
     mented.  Tcl packages can define new  commands  that  return
     other  integer  values  as return codes as well, and scripts
     that make use of the return  -code  command  can  also  have
     return codes other than the five defined by Tcl.

     If the varName 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  (TCLEROR),  the  value
     stored in varName is an error message.  When the return code
     from  the  script  is  0  (TCLOK),  the  value  stored   in
     resultVarName is the value returned from script.

     If script does not raise  an  error,  catch  will  return  0
     (TCLOK)  and  set  the  variable to the value returned from
     script.

     Note that catch catches all exceptions, including those gen-
     erated  by  break  and continue as 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.





Tcl                     Last change: 8.0                        1






Tcl Built-In Commands                                   catch(1T)



EXAMPLES
     The catch command may be used in an if to  branch  based  on
     the success of a script.
          if { [catch {open $someFile w} fid] } {
              puts stderr "Could not open $someFile for writing\n$fid"
              exit 1
          }

     The catch command will not  catch  compiled  syntax  errors.
     The first time proc foo is called, the body will be compiled
     and a Tcl error will be generated.
          proc foo {} {
              catch {expr {1 ]- }}
          }


SEE ALSO
     break(1T), continue(1T), error(1T), return(1T), tclvars(1T)


KEYWORDS
     catch, error

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWTcl        
    
     Interface Stability  Uncommitted    
    

NOTES
     Source for Tcl is available on http:/opensolaris.org.


















Tcl                     Last change: 8.0                        2