trace - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Programming : Debugging : trace

trace

trace procedures in order to debug them

untrace

turn off tracing

 

Calling Sequence

Parameters

Description

Examples

Compatibility

Calling Sequence

trace(f, options)

trace(f, g, h, ..., options)

untrace(f)

untrace(f, g, h, ...)

debug(f, options)

debug(f, g, h, ..., options)

undebug(f)

undebug(f, g, h, ...)

Parameters

f, g, h, ...

-

name(s) of procedure(s) to be traced

Description

• 

The trace function is a debugging tool for tracing the execution of specified procedures. One or more procedure or module names can be passed to trace.

• 

For more comprehensive interactive debugging facilities, see debugger.

• 

If a module name is given and the module has a ModuleApply procedure, this procedure will be traced. If the module does not have a ModuleApply procedure, all the exports of the module are traced. This process is recursive, so all exported procedures in all submodules are also traced.

• 

A special syntax, similar to that used for stopat and unstopat, may be used for tracing local procedures in modules. If a module m has a local variable g that is a procedure, then you can trace g by issuing the command trace( m::g ). Similarly, tracing of g can be turned off with the call untrace( m::g ). Note that, in this call, the expression g must be of type symbol and must be global in scope. (This special way of referring to locals of a module is recognized only when used with debugging-related utilities. It is not a general syntax for referring to module locals.)

• 

When tracing recursive procedures, it is sometimes useful to only trace the top few calls to the procedure. The depth=integer option limits tracing to the specified number of nested calls of the function(s) being traced, where a depth of 1 signifies just the top-level call.

• 

Note that it is not possible to trace most built-in functions that have special evaluation rules, such as: assigned, eval, evalhf, evalf, evaln, or seq. However, when tracing a procedure that calls evalf, any traceable code that is executed by evalf is traced.

• 

The trace function will silently ignore any argument which is not the name of a traceable procedure. In particular, it is possible to invoke trace(anames()) to cause tracing of all procedures which correspond to currently assigned names even though many of the names in anames() may not be assigned procedures.

• 

The untrace function turns off the tracing of the specified procedures.

• 

The trace (untrace) function returns an expression sequence of the names of the procedures for which tracing was turned on (off).

• 

The names debug and undebug are alternate names for trace and untrace.

• 

Instead of tracing specified procedures, it is also possible to trace all statements up to a specified depth of procedure calls and statement nesting using the printlevel environment variables.

Output Produced during Tracing

• 

The amount of information displayed during tracing depends on whether the top-level expression being evaluated was terminated with a colon (":") or a semicolon (";"). If terminated with a colon, only entry and exit points of traced procedures are printed. If terminated with a semicolon, the result of each statement executed is also printed.

• 

When execution enters a procedure for which tracing is active (either due to a call to trace, or a sufficiently high value of printlevel), a line similar to the following is displayed,

 {--> enter F, args = x, y, z, ...

  

where F is the procedure that has just been entered, and x, y, z, ... are the arguments that were passed to F.

• 

When execution exits a traced procedure, a line similar to the following is displayed,

 <-- exit F (now in G) = result }

  

where F is the procedure that has just finished, G is the procedure that execution has returned to (the caller of F), and result is the result returned by F.

• 

If an execution of a procedure terminates due to an error, a pair of lines such as the following is displayed,

 <-- ERROR in F (now in G) =

 error message, x, y, z, ... }

  

where error message refers to the message string, and x, y, z, ... are any arguments to be substituted into the message.

• 

Each entry point is printed with a left brace ("{") at the beginning of the line, and each exit point is printed with a right brace ("}") at the end of the line. If you are viewing trace output with a text editor that has a delimiter-matching function, you can use this to jump back and forth between corresponding entry and exit points.

Display of Assignments

• 

The display of assignments during tracing can be controlled by three kernelopts options, traceincidentalassign, tracesplitmulassign, and traceshowspecassign.

  

By default, assignments that occur as side-effects of calls to Maple built-in functions, such as assign or the three-argument form of member, are shown during tracing. Setting kernelopts(traceincidentalassign=false) will suppress the display of such incidental assignments.

  

Setting kernelopts(tracesplitmulassign=true) will cause multiple assignments (for example, a,b := c,d;) to be displayed individually. For multiple assignments of many variables, or with complicated right-hand sides, this is often easier to read.

  

Setting kernelopts(traceshowspecassign=true) causes some assignments to display in a distinctive way:

• 

Operator assignments that don't actually take place (for example, the second assignment in a := false; a and= b;) will be displayed using the symbol &:= instead of :=.

• 

Some assignments do not actually assign to the variable on the left-hand side of the assignment statement, but instead assign into the value that the variable currently has. For example, if the value of A is an Array, then the assignment A[2] := x; or the operator assignment A ,= y assign into the Array, but A itself is not changed (that is, A continues to refer to the same, now modified, Array or table). Such assignments are then displayed using the symbol &[]= instead of :=.

• 

Except as described otherwise above, operator assignments such as x += y; are displayed as x := finalValue, where finalValue refers to the value that was assigned to x (the result of computing x + y in this case).

Display of File and Line Number Information

• 

If source code for a traced procedure is available and kernelopts(keepdebuginfo) is true, traced output will include source file name and line number information based on the setting of kernelopts(tracelineinfo):

• 

With kernelopts(tracelineinfo=0), source file and line number information is not displayed.

• 

With kernelopts(tracelineinfo=1), which is the default, source file and line number information is displayed for procedure entry and exit only.

• 

With kernelopts(tracelineinfo=2), source file and line number information is displayed for procedure entry and exit, as well as all other statements for which tracing output would be produced.

• 

The following is an excerpt of typical output when kernelopts(tracelineinfo=2) is in effect:

 {--> enter G |TraceExample.mpl:7|, args = 3*a^2

 |TraceExample.mpl:8|

                                          2

                                  y := 3 a  + 4

 

 {--> enter H |TraceExample.mpl:12|, args = (3*a^2+4)^5

 |TraceExample.mpl:13|

                                          2     5

                               y := 6 (3 a  + 4)

 

 |TraceExample.mpl:14|

                                        2     5

                             r := 6 (3 a  + 4)  + 7

 

 <-- exit H |TraceExample.mpl:15| (now in G |TraceExample.mpl:9|)

 = 6*(3*a^2+4)^5+7}

 |TraceExample.mpl:9|

                                        2     5

                             r := 6 (3 a  + 4)  + 7

• 

The setting of kernelopts(shortlineinfo) controls whether the full recorded path of a source file is shown (shortlineinfo=false, the default), or whether just the file's name is shown (shortlineinfo=true).

Tracing Anonymous Procedures

• 

When tracing an anonymous procedure, the name unknown is displayed as the procedure name on entry and exit.

• 

On exiting a procedure, if execution returns to an anonymous procedure, the displayed exit line will be of the form,

 <-- exit F (now in unknown < G) = result }

  

where G is the procedure that called the anonymous procedure. If that procedure is also anonymous, the line will be of the form,

 <-- exit F (now in N * unknown < H) = result }

  

where N is the number of levels of anonymous procedures active between F and H.

Examples

f := proc(x) local y; y := x * 2; g(x) / 4; end proc;

f:=procxlocaly&semi;y:=2&ast;x&semi;1&sol;4&ast;gxend proc

(1)

g := proc(x) local z; z := x^2; z * 2; end proc;

g:=procxlocalz&semi;z:=x&Hat;2&semi;2&ast;zend proc

(2)

tracef&comma;g

f,g

(3)

f3

{--> enter f, args = 3
                                    y := 6

{--> enter g, args = 3
                                    z := 9

                                      18

<-- exit g (now in f) = 18}
                                      9/2

<-- exit f (now in `mpldoc/process_example`) = 9/2}

92

(4)

f3&colon;

{--> enter f, args = 3
                                    y := 6

{--> enter g, args = 3
                                    z := 9

                                      18

<-- exit g (now in f) = 18}
                                      9/2

<-- exit f (now in `mpldoc/process_example`) = 9/2}

m := module()
  export f;
  local g;
  g := proc( x )
    local y;
    y := 2 * x;
    y
  end proc;
  f := x -> g( x / 3 );
end module:

tracem::g

g

(5)

m:-f2

{--> enter g, args = 2/3
                                   y := 4/3

                                      4/3

<-- exit g (now in f) = 4/3}

43

(6)

untracem::g

g

(7)

m:-fs

2s3

(8)

Compatibility

• 

Display of source file and line number information in tracing output is new in Maple 2020.

• 

The depth option was introduced in Maple 2017.

• 

For more information on Maple 2017 changes, see Updates in Maple 2017.

• 

The kernelopts(traceincidentalassign), kernelopts(tracesplitmulassign) and kernelopts(traceshowspecassign) options were introduced in Maple 2019.1.

• 

For more information on Maple 2019 changes, see Updates in Maple 2019.

• 

The trace and untrace commands were updated in Maple 2020.

• 

The kernelopts(tracelineinfo) and kernelopts(shortlineinfo) options were introduced in Maple 2020.

• 

For more information on Maple 2020 changes, see Updates in Maple 2020.

See Also

assigned

debugger

eval

evalf

evalhf

evaln

LinearAlgebra[Trace]

module

module[export]

module[local]

printlevel

seq

Trace

tracelast

Tracing a Procedure

userinfo