NAME

       watch - call Tcl procedures before and after each command

SYNOPSIS

       watch create watchName ?options?

       watch activate watchName

       watch deactivate watchName

       watch delete watchName

       watch configure watchName ?options

       watch info watchName

       watch names
_________________________________________________________________

DESCRIPTION

       The watch command arranges for Tcl procedures to be invoked before and after the execution
       of each Tcl command.

INTRODUCTION

       When an error occurs in Tcl, the global variable errorInfo will contain a  stack-trace  of
       the  active  procedures  when  the  error occured.  Sometimes, however, the stack trace is
       insufficient.  You may need to know exactly where in the  program's  execution  the  error
       occured.  In cases like this, a more general tracing facility would be useful.

       The  watch  command  lets  you designate Tcl procedures to be invoked before and after the
       execution of each Tcl command.  This means you  can  display  the  command  line  and  its
       results  for  each  command  as it executes.  Another use is to profile your Tcl commands.
       You can profile any Tcl command (like if and set), not just Tcl procedures.

EXAMPLE

       The following example use watch to trace Tcl commands (printing to  standard  error)  both
       before and after they are executed.

              proc preCmd { level command argv } {
                  set name [lindex $argv 0]
                  puts stderr "$level $name => $command"
              }

              proc postCmd { level command argv retcode results } {
                  set name [lindex $argv 0]
                  puts stderr "$level $name => $argv0= ($retcode) $results"
              }
              watch create trace \
                -postcmd postCmd -precmd preCmd

OPERATIONS

       The following operations are available for the watch command:

       watch activate watchName
              Activates  the  watch,  causing  Tcl  commands  the  be traced to the maximum depth
              selected.

       watch create watchName ?options?...
              Creates a new watch watchName. It's an error if  another  watch  watchName  already
              exists  and  an error message will be returned.  Options may have any of the values
              accepted by the watch configure command.  This command returns the empty string.

       watch configure watchName ?options...?
              Queries or modifies the configuration options of the watch watchName.  WatchName is
              the name of a watch.  Options may have any of the following values:

              -active boolean
                     Specifies  if  the  watch  is  active.   By default, watches are active when
                     created.

              -postcmd string
                     Specifies a Tcl procedure to be called immediately after each  Tcl  command.
                     String  is  name  of a Tcl procedure and any extra arguments to be passed to
                     it.  Before string is invoked, five more  arguments  are  appended:  1)  the
                     current  level  2) the current command line 3) a list containing the command
                     after substitutions and split into words 4) the return code of the  command,
                     and  5)  the  results  of  the  command.   The  return status of the postcmd
                     procedure is always ignored.

              -precmd string
                     Specifies a Tcl procedure to be called immediately before each Tcl  command.
                     String  is  name  of a Tcl procedure and any extra arguments to be passed to
                     it.  Before string is invoked, three arguments are appended: 1) the  current
                     level  2)  the  current  command  line, and 3) a list containing the command
                     after substitutions and split into words.  The return status of the  -precmd
                     procedure is always ignored.

              -maxlevel number
                     Specifies  the  maximum evaluation depth to watch Tcl commands.  The default
                     maximum level is 10000.

       watch deactivate watchName
              Deactivates the watch.  The -precmd and  -postcmd  procedures  will  no  longer  be
              invoked.

       watch info watchName
              Returns   the  configuration  information  associated  with  the  watch  watchName.
              WatchName is the name of a watch.

       watch names ?state?
              Lists the names of the watches for  a  given  state.   State  may  be  one  of  the
              following: active, idle, or ignore.  If a state argument isn't specified,
               all watches are listed.

KEYWORDS

       debug, profile