/usr/share/doc/blt-dev/html/watch.html

                    <!-- manual page source format generated by PolyglotMan v3.0.8+XFree86, -->
<!-- available via anonymous ftp from ftp.cs.berkeley.edu:/ucb/people/phelps/tcltk/rman.tar.Z -->

<HTML>
<HEAD>
<TITLE>watch(n) manual page</TITLE>
</HEAD>
<BODY BGCOLOR="#efefef" TEXT="black" LINK="blue" VLINK="#551A8B" ALINK="red">
<A HREF="#toc">Table of Contents</A><P>

<H2><A NAME="sect0" HREF="#toc0">Name</A></H2>
watch - call Tcl procedures before and after each
command 
<H2><A NAME="sect1" HREF="#toc1">Synopsis</A></H2>
<B>watch create</B> <I>watchName</I> ?<I>options</I>? <P>
<B>watch activate</B> <I>watchName</I>
<P>
<B>watch deactivate</B> <I>watchName</I> <P>
<B>watch delete</B> <I>watchName</I> <P>
<B>watch configure</B> <I>watchName</I>
?<I>options</I> <P>
<B>watch info</B> <I>watchName</I> <P>
<B>watch names</B>  
<H2><A NAME="sect2" HREF="#toc2">Description</A></H2>
The <B>watch</B> command
arranges for Tcl procedures to be invoked before and after the execution
of each Tcl command. 
<H2><A NAME="sect3" HREF="#toc3">Introduction</A></H2>
When an error occurs in Tcl, the global
variable <I>errorInfo</I> 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.
<P>
The <B>watch</B> 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
<B>if</B> and <B>set</B>), not just Tcl procedures. 
<H2><A NAME="sect4" HREF="#toc4">Example</A></H2>
The following example use <B>watch</B>
to trace Tcl commands  (printing to standard error) both before and after
they are executed.  <BR>
<CODE>proc preCmd { level command argv } {<BR>
    set name [lindex $argv 0]<BR>
    puts stderr "$level $name =&gt; $command"<BR>
}<BR>
<P>
proc postCmd { level command argv retcode results } {<BR>
    set name [lindex $argv 0]<BR>
    puts stderr "$level $name =&gt; $argv0= ($retcode) $results"<BR>
}<BR>
watch create trace \<BR>
<tt>&#32;</tt>&nbsp;<tt>&#32;</tt>&nbsp;-postcmd postCmd -precmd preCmd<BR>

<H2><A NAME="sect5" HREF="#toc5"></CODE><P>Operations</A></H2>
The following operations are available for the <B>watch</B> command:

<DL>

<DT><B>watch activate <I>watchName</I></B>  </DT>
<DD>Activates the watch, causing Tcl commands the
be traced to the maximum depth selected. </DD>

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

<DT><B>watch configure <I>watchName</I></B> ?<I>options...</I>? </DT>
<DD>Queries or modifies
the configuration options of the watch <I>watchName</I>. <I>WatchName</I> is the name
of a watch. <I>Options</I> may have any of the following values: <blockquote></DD>

<DT><B>-active <I>boolean</I></B>
</DT>
<DD>Specifies if the watch is active. By default, watches are active when created.
</DD>

<DT><B>-postcmd <I>string</I></B> </DT>
<DD>Specifies a Tcl procedure to be called immediately after
each Tcl command.  <I>String</I> is name of a Tcl procedure and any extra arguments
to be passed to it.  Before <I>string</I> 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. </DD>

<DT><B>-precmd <I>string</I></B>  </DT>
<DD>Specifies a Tcl procedure
to be called immediately before each Tcl command.  <I>String</I> is name of a Tcl
procedure and any extra arguments to be passed to it.  Before <I>string</I> 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 <B>-precmd</B> procedure is always
ignored. </DD>

<DT><B>-maxlevel <I>number</I></B> </DT>
<DD>Specifies the maximum evaluation depth to watch
Tcl commands. The default maximum level is 10000. </DD>
</DL>
</blockquote>

<DL>

<DT><B>watch deactivate <I>watchName</I></B>
 </DT>
<DD>Deactivates the watch.  The <B>-precmd</B> and <B>-postcmd</B> procedures will no longer
be invoked. </DD>

<DT><B>watch info <I>watchName</I></B>  </DT>
<DD>Returns the configuration information
associated with the  watch <I>watchName</I>.  <I>WatchName</I> is the name of a watch.
</DD>

<DT><B>watch names</B> ?<I>state</I>? </DT>
<DD>Lists the names of the watches for a given state.  <I>State</I>
may be one of the following: <I>active</I>, <I>idle</I>, or <I>ignore</I>.  If a <I>state</I> argument
isn't specified,  all watches are<BR>
 listed. </DD>
</DL>
</blockquote>

<H2><A NAME="sect6" HREF="#toc6">Keywords</A></H2>
debug, profile <P>

<HR><P>
<A NAME="toc"><B>Table of Contents</B></A><P>
<UL>
<LI><A NAME="toc0" HREF="#sect0">Name</A></LI>
<LI><A NAME="toc1" HREF="#sect1">Synopsis</A></LI>
<LI><A NAME="toc2" HREF="#sect2">Description</A></LI>
<LI><A NAME="toc3" HREF="#sect3">Introduction</A></LI>
<LI><A NAME="toc4" HREF="#sect4">Example</A></LI>
<LI><A NAME="toc5" HREF="#sect5">Operations</A></LI>
<LI><A NAME="toc6" HREF="#sect6">Keywords</A></LI>
</UL>
</BODY></HTML>
blt-dev 2.5.3+dfsg-1 / usr / share / doc / blt-dev / html / watch.html
