| 1 |
578 |
markom |
'\"
|
| 2 |
|
|
'\" Copyright (c) 1990-1994 The Regents of the University of California.
|
| 3 |
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
| 4 |
|
|
'\"
|
| 5 |
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
| 6 |
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
| 7 |
|
|
'\"
|
| 8 |
|
|
'\" RCS: @(#) $Id: bgerror.n,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $
|
| 9 |
|
|
'\"
|
| 10 |
|
|
.so man.macros
|
| 11 |
|
|
.TH bgerror n 7.5 Tcl "Tcl Built-In Commands"
|
| 12 |
|
|
.BS
|
| 13 |
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
| 14 |
|
|
.SH NAME
|
| 15 |
|
|
bgerror \- Command invoked to process background errors
|
| 16 |
|
|
.SH SYNOPSIS
|
| 17 |
|
|
\fBbgerror \fImessage\fR
|
| 18 |
|
|
.BE
|
| 19 |
|
|
|
| 20 |
|
|
.SH DESCRIPTION
|
| 21 |
|
|
.PP
|
| 22 |
|
|
The \fBbgerror\fR command doesn't exist as built-in part of Tcl. Instead,
|
| 23 |
|
|
individual applications or users can define a \fBbgerror\fR
|
| 24 |
|
|
command (e.g. as a Tcl procedure) if they wish to handle background
|
| 25 |
|
|
errors.
|
| 26 |
|
|
.PP
|
| 27 |
|
|
A background error is one that occurs in an event handler or some
|
| 28 |
|
|
other command that didn't originate with the application.
|
| 29 |
|
|
For example, if an error occurs while executing a command specified
|
| 30 |
|
|
with the \fBafter\fR command, then it is a background error.
|
| 31 |
|
|
For a non-background error, the error can simply be returned up
|
| 32 |
|
|
through nested Tcl command evaluations until it reaches the top-level
|
| 33 |
|
|
code in the application; then the application can report the error
|
| 34 |
|
|
in whatever way it wishes.
|
| 35 |
|
|
When a background error occurs, the unwinding ends in
|
| 36 |
|
|
the Tcl library and there is no obvious way for Tcl to report
|
| 37 |
|
|
the error.
|
| 38 |
|
|
.PP
|
| 39 |
|
|
When Tcl detects a background error, it saves information about the
|
| 40 |
|
|
error and invokes the \fBbgerror\fR command later as an idle event handler.
|
| 41 |
|
|
Before invoking \fBbgerror\fR, Tcl restores the \fBerrorInfo\fR
|
| 42 |
|
|
and \fBerrorCode\fR variables to their values at the time the
|
| 43 |
|
|
error occurred, then it invokes \fBbgerror\fR with
|
| 44 |
|
|
the error message as its only argument.
|
| 45 |
|
|
Tcl assumes that the application has implemented the \fBbgerror\fR
|
| 46 |
|
|
command, and that the command will report the error in a way that
|
| 47 |
|
|
makes sense for the application. Tcl will ignore any result returned
|
| 48 |
|
|
by the \fBbgerror\fR command as long as no error is generated.
|
| 49 |
|
|
.PP
|
| 50 |
|
|
If another Tcl error occurs within the \fBbgerror\fR command
|
| 51 |
|
|
(for example, because no \fBbgerror\fR command has been defined)
|
| 52 |
|
|
then Tcl reports the error itself by writing a message to stderr.
|
| 53 |
|
|
.PP
|
| 54 |
|
|
If several background errors accumulate before \fBbgerror\fR
|
| 55 |
|
|
is invoked to process them, \fBbgerror\fR will be invoked once
|
| 56 |
|
|
for each error, in the order they occurred.
|
| 57 |
|
|
However, if \fBbgerror\fR returns with a break exception, then
|
| 58 |
|
|
any remaining errors are skipped without calling \fBbgerror\fR.
|
| 59 |
|
|
.PP
|
| 60 |
|
|
Tcl has no default implementation for \fBbgerror\fR.
|
| 61 |
|
|
However, in applications using Tk there is a default
|
| 62 |
|
|
\fBbgerror\fR procedure
|
| 63 |
|
|
which posts a dialog box containing
|
| 64 |
|
|
the error message and offers the user a chance to see a stack
|
| 65 |
|
|
trace showing where the error occurred.
|
| 66 |
|
|
|
| 67 |
|
|
.SH KEYWORDS
|
| 68 |
|
|
background error, reporting
|
