watch(n)						       BLT Built-In Commands							  watch(n)

__________________________________________________________________________________________________________________________________________________

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  cur-
		     rent  command  line  3) a list containing the command after substitutions and split into words 4) the return code of the com-
		     mand, 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

BLT
									2.4								  watch(n)