1<HTML><HEAD><TITLE>Tcl Built-In Commands - bgerror manual page</TITLE></HEAD><BODY> 2<H3><A NAME="M2">NAME</A></H3> 3bgerror - Command invoked to process background errors 4<H3><A NAME="M3">SYNOPSIS</A></H3> 5<B>bgerror </B><I>message</I><BR> 6<H3><A NAME="M4">DESCRIPTION</A></H3> 7The <B>bgerror</B> command doesn't exist as built-in part of Tcl. Instead, 8individual applications or users can define a <B>bgerror</B> 9command (e.g. as a Tcl procedure) if they wish to handle background 10errors. 11<P> 12A background error is one that occurs in an event handler or some 13other command that didn't originate with the application. 14For example, if an error occurs while executing a command specified 15with the <B><A HREF="../TclCmd/after.htm">after</A></B> command, then it is a background error. 16For a non-background error, the error can simply be returned up 17through nested Tcl command evaluations until it reaches the top-level 18code in the application; then the application can report the error 19in whatever way it wishes. When a background error occurs, the 20unwinding ends in the Tcl library and there is no obvious way for Tcl 21to report the error. 22<P> 23When Tcl detects a background error, it saves information about the 24error and invokes the <B>bgerror</B> command later as an idle event 25handler. Before invoking <B>bgerror</B>, Tcl restores the 26<B>errorInfo</B> and <B>errorCode</B> variables to their values at the 27time the error occurred, then it invokes <B>bgerror</B> with the error 28message as its only argument. Tcl assumes that the application has 29implemented the <B>bgerror</B> command, and that the command will 30report the error in a way that makes sense for the application. Tcl 31will ignore any result returned by the <B>bgerror</B> command as long 32as no error is generated. 33<P> 34If another Tcl error occurs within the <B>bgerror</B> command (for 35example, because no <B>bgerror</B> command has been defined) then Tcl 36reports the error itself by writing a message to stderr. 37<P> 38If several background errors accumulate before <B>bgerror</B> is 39invoked to process them, <B>bgerror</B> will be invoked once for each 40error, in the order they occurred. However, if <B>bgerror</B> returns 41with a break exception, then any remaining errors are skipped without 42calling <B>bgerror</B>. 43<P> 44Tcl has no default implementation for <B>bgerror</B>. However, in 45applications using Tk there is a default <B>bgerror</B> procedure which 46posts a dialog box containing the error message and offers the user a 47chance to see a stack trace showing where the error occurred. In 48addition to allowing the user to view the stack trace, the dialog 49provides an additional application configurable button which may be 50used, for example, to save the stack trace to a file. By default, 51this is the behavior associated with that button. This behavior can 52be redefined by setting the option database values 53<B>*ErrorDialog.function.text</B>, to specify the caption for the 54function button, and <B>*ErrorDialog.function.command</B>, to specify 55the command to be run. The text of the stack trace is appended to the 56command when it is evaluated. If either of these options is set to 57the empty string, then the additional button will not be displayed in 58the dialog. 59<P> 60If you are writing code that will be used by others as part of a 61package or other kind of library, consider avoiding <B>bgerror</B>. 62The reason for this is that the application programmer may also want 63to define a <B>bgerror</B>, or use other code that does and thus will 64have trouble integrating your code. 65<H3><A NAME="M5">EXAMPLE</A></H3> 66This <B>bgerror</B> procedure appends errors to a file, with a timestamp. 67<PRE>proc bgerror {message} { 68 set timestamp [clock format [clock seconds]] 69 set fl [open mylog.txt {WRONLY CREAT APPEND}] 70 puts $fl "$timestamp: bgerror in $::argv '$message'" 71 close $fl 72}</PRE> 73<H3><A NAME="M6">SEE ALSO</A></H3> 74<B><A HREF="../TclCmd/after.htm">after</A></B>, <B><A HREF="../TclCmd/tclvars.htm">tclvars</A></B> 75<H3><A NAME="M7">KEYWORDS</A></H3> 76<A href="../Keywords/B.htm#background error">background error</A>, <A href="../Keywords/R.htm#reporting">reporting</A> 77<HR><PRE> 78<A HREF="../copyright.htm">Copyright</A> © 1990-1994 The Regents of the University of California. 79<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. 80<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> 81</BODY></HTML> 82