Tcl Built-In Commands                                 bgerror(1T)





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 bger-
     ror 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 applica-
     tion.  For example, if an error  occurs  while  executing  a
     command specified with the after command, then it is a back-
     ground 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



Tcl                     Last change: 7.5                        1






Tcl Built-In Commands                                 bgerror(1T)



     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 exam-
     ple, 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  addi-
     tional 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  pro-
     grammer 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 APEND}]
              puts $fl "$timestamp: bgerror in $::argv '$message'"
              close $fl
          }


SEE ALSO
     after(1T), tclvars(1T)


KEYWORDS
     background error, reporting

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:














Tcl                     Last change: 7.5                        2






Tcl Built-In Commands                                 bgerror(1T)



     
       ATRIBUTE TYPE     ATRIBUTE VALUE
    
     Availability         SUNWTcl        
    
     Interface Stability  Uncommitted    
    

NOTES
     Source for Tcl is available on http:/opensolaris.org.













































Tcl                     Last change: 7.5                        3