       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.

                     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  argu-
                     ments.

              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 stdio buffer  flush  is  done
                     after every line is written so that the trace may be mon-
                     itored  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  descrip-
                     tion  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 back-
                     slash 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 com-
              mand'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.
