CLASS
tcl.lang.Interp -- This manual entry contains Interp methods that monitor accesses of Tcl variables.
METHODS
void traceVar(String name, VarTrace trace, int flags) throws TclException
void traceVar(String part1, String part2, VarTrace trace, int flags) throws TclException
void untraceVar(String name, VarTrace trace, int flags) throws TclException
void untraceVar(String part1, String part2, VarTrace trace, int flags) throws TclException
OTHER METHODS
ARGUMENTS
DESCRIPTION
traceVar
untraceVar
OVERLOADING
FLAGS
TCL.TRACE_READS
TCL.TRACE_WRITES
TCL.TRACE_UNSETS
TCL.GLOBAL_ONLY
TCL.NAMESPACE_ONLY
CALLBACK TIMING
WHOLE-ARRAY TRACES
MULTIPLE TRACES
RESTRICTIONS
UNDEFINED VARIABLES
EQUIVALENT C FUNCTIONS
SEE ALSO
KEYWORDS

CLASS

tcl.lang.Interp -- This manual entry contains Interp methods that monitor accesses of Tcl variables.

METHODS

void traceVar(String name, VarTrace trace, int flags) throws TclException

void traceVar(String part1, String part2, VarTrace trace, int flags) throws TclException

void untraceVar(String name, VarTrace trace, int flags) throws TclException

void untraceVar(String part1, String part2, VarTrace trace, int flags) throws TclException

OTHER METHODS

setVar, createCommand, eval, setResult, backgroundError,
getNotifier, setAssocData, dispose, pkgRequire

ARGUMENTS

String name ()
Name of variable. May refer to a scalar variable, an array variable with no index, or an array variable with a parenthesized index.

String part1 ()
Name of scalar or array variable. If part2 is null, part1 is treated like name. Otherwise, part1 cannot be array variable with a parenthesized index.

String part2 ()
If not null, gives name of element within array; in this case part1 must refer to an array variable with no index.

int flags ()
OR-ed combination of bits providing additional information. See below for valid values.

VarTrace trace ()
The trace to add to or remove from a variable.

DESCRIPTION

A trace is used to monitor and control access )reads, writes, and/or unsets) to a specified Tcl variable. Traces are instances of the VarTrace class, whose traceProc method is called whenever the specified Tcl Variable is accessed. The traceVar methods create traces, and the untraceVar methods delete them.

traceVar
The traceVar methods create an instance of the VarTrace class to monitor and control access to Tcl variable whose name is name or the combination of part1 and part2. See the OVERLOADING section below to learn how arguments part1 and part2 are combined to form a valid variable name. The result of creating a variable trace VarTrace's traceProc is invoked whenever the variable is read, written or unset, dpending on the value of the flags argument. The flags argument indicates when the trace procedure is to be invoked and provides information for setting up the trace. See the FLAGS section below for details.

untraceVar
The untraceVar methods allow a java method to remove a trace previously placed on the variable whose name is name or the combination of part1 and part2 (as described for the traceVar method above). If an error occurs while removing the trace (e.g. the variable doesn't have a trace on it), then a TclException is generated and an error message is left in interp's result unless the TCL.DONT_THROW_EXCEPTION flag bit is set.

OVERLOADING

These methods are overloaded to allow three different ways to specify variable names.

[1]
If traceVar or untraceVar is invoked with the name argument, the variable name is given as a single string, name. If name contains an open parenthesis and ends with a close parenthesis, then the value between the parentheses is treated as an index (which can have any string value) and the characters before the first open parenthesis are treated as the name of an array variable. If name doesn't have parentheses as described above, then the entire string is treated as the name of a scalar variable or array name with no index.

[2]
If the part1 and part2 arguments are provided and part2 is not null, then the variable part1(part2) is specified. The part1 argument contains the array name, and the part2 argument contains the index.

[3]
If the part1 and part2 arguments are provided and part2 is null, then part1 is treated the same as the name argument in step [1].

FLAGS

The flags argument may be used to specify any of several options to the methods. It consists of an OR-ed combination of the following bits.

TCL.TRACE_READS
Invoke proc whenever an attempt is made to read the variable. This flag is only active for the traceVar methods.

TCL.TRACE_WRITES
Invoke proc whenever an attempt is made to modify the variable. This flag is only active for the traceVar methods.

TCL.TRACE_UNSETS
Invoke proc whenever the variable is unset. A variable may be unset either explicitly by an unset command, or implicitly when a procedure returns (its local variables are automatically unset) or when the interpreter is deleted (all variables are automatically unset). This flag is only active for the traceVar methods.

TCL.GLOBAL_ONLY
Under normal circumstances, the procedures look up variables as follows. If a procedure call is active in Interp, the variable is looked up at the current level of procedure call. Otherwise, the variable is looked up first in the current namespace, then in the global namespace. However, if this bit is set in flags then the variable is looked up only in the global namespace, even if there is an active procedure call. If both TCL.GLOBAL_ONLY and TCL.NAMESPACE_ONLY are given, TCL.GLOBAL_ONLY is ignored.

TCL.NAMESPACE_ONLY
If this bit is set in flags then the variable is looked up only in the current namespace; if a procedure is active, its variables are ignored, and the global namespace is also ignored unless it is the current namespace.

CALLBACK TIMING

When read tracing has been specified for a variable, traceProc will be invoked whenever the variable's value is read. This includes set Tcl commands, $-notation in Tcl commands, and invocations of Interp.getVar. traceProc is invoked just before the variable's value is returned. It may modify the value of the variable to affect what is returned by the traced access. If it unsets the variable then the access will return an error just as if the variable never existed.

When write tracing has been specified for a variable, traceProc will be invoked whenever the variable's value is modified. This includes set commands, commands that modify variables as side effects (such as catch and scan), and calls toInterp.setVar). tracProc will be invoked after the variable's value has been modified, but before the new value of the variable has been returned. It may modify the value of the variable to override the change and to determine the value actually returned by the traced access. If it deletes the variable then the traced access will return an empty string.

When unset tracing has been specified,traceProc will be invoked whenever the variable is destroyed. The traces will be called after the variable has been completely unset.

WHOLE-ARRAY TRACES

If a call to traceVar specifies the name of an array variable without an index into the array, then the trace will be set on the array as a whole. This means that trceProc will be invoked whenever any element of the array is accessed in the ways specified by flags. When an array is unset, a whole-array trace will be invoked just once, with part1 equal to the name of the array and part2 NULL; it will not be invoked once for each element.

MULTIPLE TRACES

It is possible for multiple traces to exist on the same variable. When this happens, all of the trace procedures will be invoked on each access, in order from most-recently-created to least-recently-created. When there exist whole-array traces for an array as well as traces on individual elements, the whole-array traces are invoked before the individual-element traces. If a read or write trace unsets the variable then all of the unset traces will be invoked but the remainder of the read and write traces will be skipped.

RESTRICTIONS

A trace procedure can be called at any time, even when there is a partially-formed result in the interpreter's result area. If the trace procedure does anything that could damage this result (such as calling Interp.eval) then it must save the original values of the interpreter's result and restore it before it returns.

UNDEFINED VARIABLES

It is legal to set a trace on an undefined variable. The variable will still appear to be undefined until the first time its value is set. If an undefined variable is traced and then unset, the unset will fail with an error (``no such variable''), but the trace procedure will still be invoked.

EQUIVALENT C FUNCTIONS

Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2

SEE ALSO

Interp, VarTrace, setVar, setResult, Eval

KEYWORDS

array, get, interpreter, scalar, set, trace, unset, variable 
Copyright © 1998 by Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.