This command is part of the [TclX] package.
    :   '''cmdtrace''' [[''level'' | '''on''']] ''options...''
    :   '''cmdtrace off'''
    :   '''cmdtrace depth'''

See also the [trace] command's execution traces.
----
    :   '''cmdtrace''' [[''level'' | '''on''']] ?'''noeval'''? ?'''notruncate'''? ?'''procs'''? ?''fileid''? ?'''command''' ''cmd''?

Print a trace statement for all commands executed at depth of ''level'' or below (1 is the top level). If '''on''' is specified, all commands at any level are traced. The following options are available:

   '''noeval''':   Causes arguments to be printed unevaluated. If '''noeval''' is specified, the arguments are printed before evaluation. Otherwise, they are printed afterwards. <<br>><<br>> If the command line is longer than 60 characters, it is truncated to 60 and a "..." is postpended to indicate that there was more output than was displayed. If an evaluated argument contains a space, the entire argument will be enclosed inside of braces (‘{}’) to allow the reader to visually separate the arguments from each other.

   '''notruncate''':   Disables the truncation of commands and evaluated arguments.

   '''procs''':   Enables the tracing of procedure calls only. Commands that aren't procedure calls (i.e., calls to commands that are written in C, C++ or some object-compatible language) are not traced if the procs option is specified. This option is particularly useful for greatly reducing the output of '''cmdtrace''' while debugging.

   ''fileid'':   This is a file id as returned by the [open] command. If specified, then the trace output will be written to the file rather than [stdout]. A [flush] is done after every line is written so that the trace may be monitored externally or provide useful information for debugging problems that cause core dumps.

   '''command''' ''cmd'':   Call the specified command ''cmd'' on when each command is executed instead of tracing to a file. See the description of the functionally below. This option may not be specified with a ''fileid''.

The most common use of this command is to enable tracing to a file during the development. If a failure occurs, a trace is then available when needed. Command tracing will slow down the execution of code, so it should be removed when code is debugged. The following command will enable tracing to a file for the remainder of the program:
======
cmdtrace on [open cmd.log w]
======
The '''command''' option causes a user specified trace command to be called for each command executed. The command will have the following arguments appended to it before evaluation:

   ''command'':   A string containing the text of the command, before any argument substitution.

   ''argv'':   A list of the final argument information that will be passed to the command after command, variable, and backslash substitution.

   ''evalLevel'':   The [Tcl_Eval] call level.

   ''procLevel'':   The procedure call level.

The command should be constructed in such a manner that it will work if additional arguments are added in the future. It is suggested that the command be a proc with the final argument being [args].

Tracing will be turned off while the command is being executed. The values of the [errorInfo] and [errorCode] variables will be saved and restored on return from the command. It is the command's responsibility to preserve all other state.

If an error occurs during the execution of command, an error message is dumped to [stderr] and the tracing is disabled. The underlying mechanism that this functionality is built on does not support returning an error to the interpreter.
----
    :   '''cmdtrace off'''
Turn off all tracing.
----
    :   '''cmdtrace depth'''
Returns the current maximum trace level, or zero if trace is disabled.


<<categories>> Command | Debugging | TclX