printlevel
display of information; debugging procedures
Calling Sequence
Parameters
Description
Compatibility
printlevel := n
n
-
integer
The printlevel environment variable is a debugging tool that controls tracing of statements and procedures to a specified execution level (depth).
For more comprehensive interactive debugging facilities, see debugger.
The execution of a Maple statement, whether at the top level, or within a procedure or module, is associated with a level.
The top (interactive, or a script of Maple commands) level is numbered 0. Each level of conditional (if) or repetition (for, while) statement represents one additional level. Each level of procedure call represents 5 additional levels.
The value of the printlevel environment variable causes tracing of all statements executed up to the level indicated by printlevel. Initially, printlevel is set to 1, so only top level statements, and those within a single level of conditional or repetition are traced.
Higher values of printlevel will cause more information to be displayed; negative values will cause no information to be displayed.
For debugging purposes, printlevel := 1000 is not uncommon.
When execution errors are encountered when printlevel > 2, a summary of calling routines, like that produced by tracelast, is also shown.
Because printlevel is an environment variable, it can be set by a procedure that is being debugged without affecting the procedures that called it.
Attempting to assign a non-integer value to printlevel raises an error and leaves printlevel unchanged.
Instead of tracing all statements up to a specified execution level, it is also possible to trace only the execution of specified procedures by using the trace function.
Output Produced during Tracing
The amount of information displayed during tracing depends on whether the top-level expression being evaluated was terminated with a semicolon (";") or a colon (":"). If terminated with a semicolon, procedure entry, the result of each statement executed within the procedure, and procedure exit are shown. If terminated with a colon, only the entry and exit points of each traced procedure are shown (this can be achieved for specific procedures using the statements=false option to the trace command).
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|
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|
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.
Display of source file and line number information in tracing output is new in Maple 2020.
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 printlevel command was 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
debugger
environment variables
mint
trace
tracelast
Download Help Document
