distrib/share/tcl/help/tcl/control/error

   1 NAME
   2        error - Generate an error
   3
   4 SYNOPSIS
   5        error message ?info? ?code?
   6
   7
   8 DESCRIPTION
   9        Returns  a  TCL_ERROR  code,  which causes command interpretation to be
  10        unwound.  Message is a string that is returned to  the  application  to
  11        indicate what went wrong.
  12
  13        If  the  info argument is provided and is non-empty, it is used to ini-
  14        tialize the global variable errorInfo.  errorInfo is used to accumulate
  15        a stack trace of what was in progress when an error occurred; as nested
  16        commands unwind, the Tcl interpreter adds information to errorInfo.  If
  17        the  info  argument  is present, it is used to initialize errorInfo and
  18        the first increment of unwind information will not be added by the  Tcl
  19        interpreter.   In other words, the command containing the error command
  20        will not appear in errorInfo; in its place will be info.  This  feature
  21        is most useful in conjunction with the catch command: if a caught error
  22        cannot be handled successfully, info can be  used  to  return  a  stack
  23        trace reflecting the original point of occurrence of the error:
  24               catch {...} errMsg
  25               set savedInfo $errorInfo
  26               ...
  27               error $errMsg $savedInfo
  28
  29        If the code argument is present, then its value is stored in the error-
  30        Code global variable.  This variable is intended  to  hold  a  machine-
  31        readable  description  of  the error in cases where such information is
  32        available; see the tclvars manual page for information  on  the  proper
  33        format  for  the  variable.   If the code argument is not present, then
  34        errorCode is automatically reset to ``NONE'' by the Tcl interpreter  as
  35        part of processing the error generated by the command.
  36
  37 EXAMPLE
  38        Generate an error if a basic mathematical operation fails:
  39               if {1+2 != 3} {
  40                   error "something is very wrong with addition"
  41               }
  42
  43
  44 SEE ALSO
  45        catch(n), return(n), tclvars(n)
  46
  47
  48 KEYWORDS