NAME

       bgerror - Command invoked to process background errors

SYNOPSIS

       bgerror message
_________________________________________________________________

DESCRIPTION

       The  bgerror  command  doesn't  exist  as  built-in  part  of  Tcl.   Instead,  individual
       applications or users can define a bgerror command (e.g. as a Tcl procedure) if they  wish
       to handle background errors.

       A  background  error  is  one  that  occurs in an event handler or some other command that
       didn't originate with the application.  For example, if an error occurs while executing  a
       command  specified  with  the  after  command,  then it is a background error.  For a non-
       background error, the  error  can  simply  be  returned  up  through  nested  Tcl  command
       evaluations  until  it reaches the top-level code in the application; then the application
       can report the error in whatever way it wishes.   When  a  background  error  occurs,  the
       unwinding ends in the Tcl library and there is no obvious way for Tcl to report the error.

       When  Tcl detects a background error, it saves information about the error and invokes the
       bgerror command later as an idle event handler. Before invoking bgerror, Tcl restores  the
       errorInfo  and errorCode variables to their values at the time the error occurred, then it
       invokes bgerror with the error message  as  its  only  argument.   Tcl  assumes  that  the
       application  has  implemented  the  bgerror  command, and that the command will report the
       error in a way that makes sense for the application.  Tcl will ignore any result  returned
       by the bgerror command as long as no error is generated.

       If  another  Tcl  error occurs within the bgerror command (for example, because no bgerror
       command has been defined) then Tcl reports the  error  itself  by  writing  a  message  to
       stderr.

       If several background errors accumulate before bgerror is invoked to process them, bgerror
       will be invoked once for each error, in the order  they  occurred.   However,  if  bgerror
       returns  with  a  break  exception,  then any remaining errors are skipped without calling
       bgerror.

       Tcl has no default implementation for bgerror. However, in applications using Tk there  is
       a  default  bgerror  procedure  which  posts a dialog box containing the error message and
       offers the user a chance to see a stack  trace  showing  where  the  error  occurred.   In
       addition  to  allowing the user to view the stack trace, the dialog provides an additional
       application configurable button which may be used, for example, to save the stack trace to
       a  file.  By default, this is the behavior associated with that button.  This behavior can
       be redefined by setting the option database values *ErrorDialog.function.text, to  specify
       the  caption  for  the  function button, and *ErrorDialog.function.command, to specify the
       command to be run.  The text of the stack trace is appended to  the  command  when  it  is
       evaluated.   If  either  of  these options is set to the empty string, then the additional
       button will not be displayed in the dialog.

       If you are writing code that will be used by others as part of a package or other kind  of
       library,  consider  avoiding  bgerror.   The  reason  for  this  is  that  the application
       programmer may also want to define a bgerror, or use other code that does  and  thus  will
       have trouble integrating your code.

EXAMPLE

       This bgerror procedure appends errors to a file, with a timestamp.
              proc bgerror {message} {
                  set timestamp [clock format [clock seconds]]
                  set fl [open mylog.txt {WRONLY CREAT APPEND}]
                  puts $fl "$timestamp: bgerror in $::argv '$message'"
                  close $fl
              }

SEE ALSO

       after(3tcl), tclvars(3tcl)

KEYWORDS

       background error, reporting