HP/util/HP/man/mann/watch.n

   1 '\"
   2 '\" Copyright 1991-1997 by Bell Labs Innovations for Lucent Technologies.
   3 '\"
   4 '\" Permission to use, copy, modify, and distribute this software and its
   5 '\" documentation for any purpose and without fee is hereby granted, provided
   6 '\" that the above copyright notice appear in all copies and that both that the
   7 '\" copyright notice and warranty disclaimer appear in supporting documentation,
   8 '\" and that the names of Lucent Technologies any of their entities not be used
   9 '\" in advertising or publicity pertaining to distribution of the software
  10 '\" without specific, written prior permission.
  11 '\"
  12 '\" Lucent Technologies disclaims all warranties with regard to this software,
  13 '\" including all implied warranties of merchantability and fitness.  In no event
  14 '\" shall Lucent Technologies be liable for any special, indirect or
  15 '\" consequential damages or any damages whatsoever resulting from loss of use,
  16 '\" data or profits, whether in an action of contract, negligence or other
  17 '\" tortuous action, arising out of or in connection with the use or performance
  18 '\" of this software.
  19 '\"
  20 '\"
  21 .HS watch BLT
  22 .BS
  23 .SH NAME
  24 watch \- call Tcl procedures before and after each command
  25 .SH SYNOPSIS
  26 \fBwatch create\fR \fIwatchName\fR ?\fIoptions\fR?
  27 .sp
  28 \fBwatch activate\fR \fIwatchName\fR
  29 .sp
  30 \fBwatch deactivate\fR \fIwatchName\fR
  31 .sp
  32 \fBwatch delete\fR \fIwatchName\fR
  33 .sp
  34 \fBwatch configure\fR \fIwatchName\fR ?\fIoptions\fR
  35 .sp
  36 \fBwatch info\fR \fIwatchName\fR
  37 .sp
  38 \fBwatch names\fR
  39 .BE
  40 .SH DESCRIPTION
  41 The \fBwatch\fR command arranges for Tcl procedures to be invoked
  42 before and after the execution of each Tcl command.
  43 .SH INTRODUCTION
  44 When an error occurs in Tcl, the global variable \fIerrorInfo\fR will
  45 contain a stack-trace of the active procedures when the error occured.
  46 Sometimes, however, the stack trace is insufficient.  You may need to
  47 know exactly where in the program's execution the error occured.  In
  48 cases like this, a more general tracing facility would be useful.
  49 .PP
  50 The \fBwatch\fR command lets you designate Tcl procedures to be
  51 invoked before and after the execution of each Tcl command.  This
  52 means you can display the command line and its results for each
  53 command as it executes.  Another use is to profile your Tcl commands.
  54 You can profile any Tcl command (like \fBif\fR and \fBset\fR), not just
  55 Tcl procedures.
  56 .SH EXAMPLE
  57 The following example use \fBwatch\fR to trace Tcl commands
  58 (printing to standard error) both before and after they are executed.
  59 .DS
  60 proc preCmd { level command argv } {
  61     set name [lindex $argv 0]
  62     puts stderr "$level $name => $command"
  63 }
  64
  65 proc postCmd { level command argv retcode results } {
  66     set name [lindex $argv 0]
  67     puts stderr "$level $name => $argv\n<= ($retcode) $results"
  68 }
  69 watch create trace \\
  70         -postcmd postCmd -precmd preCmd
  71 .DE
  72 .SH "OPERATIONS"
  73 The following operations are available for the \fBwatch\fR command:
  74 .TP
  75 \fBwatch activate \fIwatchName\fR
  76 Activates the watch, causing Tcl commands the be traced to the
  77 maximum depth selected.
  78 .TP
  79 \fBwatch create \fIwatchName\fR ?\fIoptions\fR?...
  80 Creates a new watch \fIwatchName\fR. It's an error if another watch
  81 \fIwatchName\fR already exists and an error message will be returned.
  82 \fIOptions\fR may have any of the values accepted by the
  83 \fBwatch configure\fR command.
  84 This command returns the empty string.
  85 .TP
  86 \fBwatch configure \fIwatchName\fR ?\fIoptions...\fR?
  87 Queries or modifies the configuration options of the watch \fIwatchName\fR.
  88 \fIWatchName\fR is the name of a watch.
  89 \fIOptions\fR may have any of the following values:
  90 .RS
  91 .TP
  92 \fB\-active \fIboolean\fR
  93 Specifies if the watch is active.
  94 By default, watches are active when created.
  95 .TP
  96 \fB\-postcmd \fIstring\fR
  97 Specifies a Tcl procedure to be called immediately after each Tcl
  98 command.  \fIString\fR is name of a Tcl procedure and any extra
  99 arguments to be passed to it.  Before \fIstring\fR is invoked, five
 100 more arguments are appended: 1) the current level 2) the current
 101 command line 3) a list containing the command after substitutions and
 102 split into words 4) the return code of the command, and 5) the results
 103 of the command.  The return status of the postcmd procedure is always
 104 ignored.
 105 .TP
 106 \fB\-precmd \fIstring\fR
 107 Specifies a Tcl procedure to be called immediately before each Tcl
 108 command.  \fIString\fR is name of a Tcl procedure and any extra
 109 arguments to be passed to it.  Before \fIstring\fR is invoked, three
 110 arguments are appended: 1) the current level 2) the current command
 111 line, and 3) a list containing the command after substitutions and
 112 split into words.  The return status of the \fB\-precmd\fR procedure
 113 is always ignored.
 114 .TP
 115 \fB\-maxlevel \fInumber\fR
 116 Specifies the maximum evaluation depth to watch Tcl commands.
 117 The default maximum level is 10000.
 118 .RE
 119 .TP
 120 \fBwatch deactivate \fIwatchName\fR
 121 Deactivates the watch.  The \fB\-precmd\fR and \fB\-postcmd\fR procedures
 122 will no longer be invoked.
 123 .TP
 124 \fBwatch info \fIwatchName\fR
 125 Returns the configuration information associated with the
 126 watch \fIwatchName\fR.  \fIWatchName\fR is the name of a watch.
 127 .TP
 128 \fBwatch names\fR ?\fIstate\fR?
 129 Lists the names of the watches for a given state.  \fIState\fR may be
 130 one of the following: \f(CWactive\fR, \f(CWidle\fR, or \f(CWignore\fR.  If a
 131 \fIstate\fR argument isn't specified,
 132  all watches are
 133 listed.
 134 .RE
 135 .SH KEYWORDS
 136 debug, profile