NAME

       Tcl_BackgroundError  -  report  Tcl error that occurred in
       background processing


SYNOPSIS

       #include <tcl.h>

       Tcl_BackgroundError(interp)


ARGUMENTS

       Tcl_Interp   *interp   (in)      Interpreter in which  the
                                        error occurred.
_________________________________________________________________



DESCRIPTION

       This  procedure  is  typically  invoked  when  a Tcl error
       occurs during ``background processing'' such as  executing
       an  event  handler.   When such an error occurs, the error
       condition is reported to Tcl or to a widget or some  other
       C  code, and there is not usually any obvious way for that
       code to report the error to the user.  In these cases  the
       code  calls  Tcl_BackgroundError  with  an interp argument
       identifying the interpreter in which the  error  occurred.
       At  the  time  Tcl_BackgroundError  is invoked, the inter­
       preter's result is expected to contain an  error  message.
       Tcl_BackgroundError will invoke the bgerror Tcl command to
       report the error in an application-specific  fashion.   If
       no  bgerror command exists, or if it returns with an error
       condition,  then  Tcl_BackgroundError  reports  the  error
       itself by printing a message on the standard error file.

       Tcl_BackgroundError  does  not  invoke bgerror immediately
       because this could potentially interfere with scripts that
       are  in  process at the time the error occurred.  Instead,
       it invokes bgerror later as an idle  callback.   Tcl_Back­
       groundError  saves  the values of the errorInfo and error­
       Code variables  and  restores  these  values  just  before
       invoking bgerror.

       It  is  possible  for many background errors to accumulate
       before bgerror is invoked.  When this happens, each of the
       errors is processed in order.  However, if bgerror returns
       a break exception, then all remaining  error  reports  for
       the interpreter are skipped.



KEYWORDS

       background, bgerror, error