Consider the following procedure, sieve, which is used as a case study. It implements the Sieve of Eratosthenes: given a parameter n, return a count of the prime numbers less than or equal to n. To debug the sieve procedure, breakpoints and watchpoints will be used to stop the the execution of the procedure at selected points or on selected events.

To use the Maple debugger, you can enter several debugger commands. Many of these debugger commands refer to statements in the procedures that you are debugging. Statement numbers allow such references. The showstat command displays a Maple procedure along with numbers preceding each line that begins a new statement.

Note: The numbers preceding each line differ from line numbers that may be displayed in a text editor. For example, keywords that end a statement (such as end do and end if) are not considered separate Maple commands and are therefore not numbered.

To invoke the Maple debugger, execute a procedure and then stop the execution process within the procedure. To execute a Maple procedure, call it by using a Maple command at the top level or call it from another procedure. The simplest way to stop the execution process is to set a breakpoint in the procedure.

Use the stopat command to set a breakpoint in the sieve procedure.

This command sets a breakpoint before the first statement in the procedure sieve. When you subsequently execute the sieve procedure, Maple stops before executing the first statement and waits for you to provide instructions on what to do next. When the execution process stops, the debugger prompt is displayed (DBG>).

Note: If a procedure has a remember table or a cache table, you may have to run the restart command before running a second or subsequent stopat command. For more information about remember tables and cache tables, see The remember, cache, and system Options or refer to the remember or CacheCommand help pages.

In the following example, the sieve procedure is called.

Several pieces of information are displayed after the debugger prompt.

At the debugger prompt, you can evaluate Maple expressions and call debugger commands. Maple evaluates expressions in the context of the stopped procedure. You have access to the same procedure parameters, and local, global, and environment variables as the stopped procedure. For example, since the sieve procedure was called with parameter value 10, the formal parameter n has the value 10.

For each expression that Maple evaluates,

Note: To remove a breakpoint from a procedure, use the unstopat command.

Debugger commands control how the procedure is executed once the debugger is started. Some commonly used debugger commands are next, step, into, list, outfrom, and cont.

The next command runs the next statement at the current nesting level. After the statement is run, control is returned to the debugger. If the statement is a control structure (for example, an if statement or a loop), the debugger runs any statements within the control structure that it would normally run. It stops the execution process before the next statement after the control structure. Similarly, if the statement contains calls to procedures, the debugger executes these procedure calls in their entirety before the execution process stops.

The 0 in the first line of the output represents the result of the statement that was run--that is, the result of count := 0. A "*" does not appear next to the statement number because there is no breakpoint set immediately before statement 2. The debugger does not show the body of the for loop, which itself consists of statements with their own statement numbers, unless the execution process actually stops within its body. Maple represents the body of compound statements by ellipses (...).

Running the next command again results in the following output.

The execution process now stops before statement 4. Statement 3 (the body of the previous for loop) is at a deeper nesting level. The loop is executed n-1 times. The debugger displays the last result computed in the loop (the assignment of the value true to flags[10]).

Tip: If you want to repeat the previous debugger command, as shown in the second next command above, you can press Enter at the DBG> prompt. You can also view your recent command history using the up and down arrow keys on your keyboard.

To step into a nested control structure (such as an if statement or for loop) or a procedure call, use the step debugger command.

If you use the step debugger command when the next statement to run is not a deeper structured statement or procedure call, it has the same effect as the next debugger command.

At any time during the debugging process, you can use the showstat debugger command to display the current status of the debugging process.

Maple displays a debugger prompt to indicate that you are still working within the Maple debugger. The asterisk (*) indicates the unconditional breakpoint. An exclamation point (!) that follows a statement number (see line 7) indicates the statement at which the procedure is stopped.

To continue the debugging process, run another debugger command. For example, you can use into or step to enter the innermost loop.

The behavior of the into debugger command is between that of the next and step commands. The execution process stops at the next statement in the current procedure independent of whether it is at the current nesting level or in the body of a control structure (an if statement or a loop). That is, the into command steps into nested statements, but not procedure calls. It executes called procedures completely and then stops.

A debugger command that is related to showstat is the list command. It displays the previous five statements, the current statement, and the next statement to indicate where the procedure has stopped.

You can use the outfrom debugger command to finish the execution process at the current nesting level or at a deeper level. Execution of the procedure is stopped once a statement at a shallower nesting level is reached, that is, after a loop terminates, a branch of an if statement executes, or the current procedure call returns.

The cont debugger command continues the execution process until either the procedure stops normally or encounters another breakpoint.

The procedure does not give the expected output. Although you may find the reason obvious from the previous debugger command examples, in other cases, it may not be easy to find procedure errors. Therefore, continue to use the debugger. First, use the unstopat command to remove the breakpoint from the sieve procedure.

The procedure sieve maintains the changing result in the variable count. Therefore, a logical place to look during debugging is wherever Maple modifies count. The easiest way to do this is by using a watchpoint, which starts the debugger whenever Maple modifies a variable that you identify.

Use the stopwhen command to set watchpoints. In this case, the execution process will stop whenever Maple modifies the variable count in the procedure sieve.

The stopwhen command returns a list of all the currently watched variables (that is, the variables that you provided to the stopwhen command).

Execute the  sieve procedure again.

The execution process stops because Maple modified count and the debugger displays the assignment statement count := 0. Similar to breakpoints, the debugger then displays the name of the procedure and the next statement to be run in the procedure. Note that the execution process stops after Maple assigns a value to count.

This first assignment to count is correct. Use the cont debugger command to continue the execution process.

At first glance, this may look correct. Assume that the output is correct and continue the execution process.

This output appears to be incorrect because Maple should have simplified 2*1. Note that it printed 2*l (two times the letter l) instead. By examining the source text for the procedure, you can see that the letter "l" was entered instead of the number "1". Since the source of the error has been discovered, you can stop the procedure. Use the quit debugger command to stop the debugger, and then use the unstopwhen command to remove the watchpoint from the procedure.

After correcting the source code for sieve, run the restart command, re-execute that source code (for example, read it into your command-line session or re-execute that code region in your worksheet), and execute the procedure again.

This result is still incorrect. There are four primes less than 10, namely 2, 3, 5, and 7. Therefore, start the debugger once more, stepping into the innermost parts of the procedure to investigate. Since you do not want to start executing the procedure from the start, set the breakpoint at statement 6.

The last step reveals the error. The previously computed result should have been false (from the assignment of flags[k] to the value false), but instead the value true = false was returned. An equation was used instead of an assignment. Therefore, Maple did not set flags[k] to false.

Once again, stop the debugger and correct the source text.

The following code represents the corrected procedure.

Execute the sieve procedure again to test the corrections.

The sieve procedure returns the correct result.

The showstat command has the following syntax. The procedureName parameter is optional.

If showstat is called with no arguments, all procedures that contain breakpoints are displayed.

You can also use the showstat command to display a single statement or a range of statements by using the following syntax.

In these cases, the statements that are not displayed are represented by ellipses (...). The procedure name, its parameters, and its local and global variables are always displayed.

This section provides additional information about breakpoints and watchpoints.

Setting Breakpoints

The stopat command has the following syntax, where procedureName is the name of the procedure in which to set the breakpoint, statementNumber is the line number of the statement in the procedure before which the breakpoint is set, and condition is a Boolean expression which must be true to stop the execution process. The statementNumber and condition arguments are optional.   stopat( procedureName, statementNumber, condition ); The condition argument can refer to any global variable, local variable, or parameter of the procedure. These conditional breakpoints are indicated by a question mark (?) if the showstat command is used to display the procedure. Since the stopat command sets the breakpoint before the specified statement, when Maple encounters a breakpoint, the execution process stops and Maple starts the debugger before the statement. Note: This means that you cannot set a breakpoint after the last statement in a statement sequence--that is, at the end of a loop body, an if statement body, or a procedure. If two identical procedures exist, depending on how you created them, they may share breakpoints. If you entered the procedures individually, with identical procedure bodies, they do not share breakpoints. If you created a procedure by assigning it to the body of another procedure, their breakpoints are shared. >  f := proc(x) x^2 end proc: g := proc(x) x^2 end proc: h := op(g): stopat(g); $\left[g\,h\right]$ (9) >  showstat(); g := proc(x)    1*  x^2 end proc h := proc(x)    1*  x^2 end proc

Removing Breakpoints

The unstopat command has the following syntax, where procedureName is the name of the procedure that contains the breakpoint, and statementNumber is the line number of the statement where the breakpoint is set. The statementNumber parameter is optional.   unstopat( procedureName, statementNumber ); If statementNumber is omitted in the call to unstopat, all breakpoints in the procedure procedureName are cleared.

Setting Explicit Breakpoints

You can set an explicit breakpoint by inserting a call to the DEBUG command in the source text of a procedure. The DEBUG command has the following syntax. The argument parameter is optional.   DEBUG( argument ); If no argument is included in the DEBUG command, execution in the procedure stops at the statement following the location of the DEBUG command, and then the debugger is started. Note: The showstat command does not mark explicit breakpoints with an "*" or a "?". >  f := proc(x,y) local a;         a:=x^2;         DEBUG();         a:=y^2; end proc: >  showstat(f); f := proc(x, y) local a;    1   a := x^2;    2   DEBUG();    3   a := y^2 end proc >  f(2,3); 4 f:    3   a := y^2 DBG> quit Interrupted If the argument of the DEBUG command is a Boolean expression, the execution process stops only if the Boolean expression evaluates to true. If the Boolean expression evaluates to false or FAIL, the DEBUG command is ignored. >  f := proc(x,y) local a;         a:=x^2;         DEBUG(a<1);         a:=y^2;         DEBUG(a>1);         print(a); end proc: >  f(2,3); 9 f:    5   print(a) DBG> quit Interrupted If the argument of the DEBUG command is a value other than a Boolean expression, the debugger prints the value of the argument (instead of the last result) when the execution process stops at the following statement. >  f := proc(x)         x^2;         DEBUG("This is my breakpoint. The current value of x is:", x);         x^3; end proc: >  f(2); "This is my breakpoint. The current value of x is:", 2 f:    3   x^3 DBG>

Removing Explicit Breakpoints

The unstopat command cannot remove explicit breakpoints. You must remove breakpoints that were set by using DEBUG by editing the source text for the procedure. DBG> unstopat [f] f:    3   x^3 DBG> showstat f := proc(x)    1   x^2;    2   DEBUG("This is my breakpoint. The current value of x is:", x);    3 ! x^3 end proc DBG> quit Interrupted Note: If you display the contents of a procedure by using the print command (or lprint) and the procedure contains a breakpoint that was set by using stopat, the breakpoint appears as a call to DEBUG. >  f := proc(x) x^2 end proc: >  stopat(f); $\left[f\,g\,h\right]$ (10) >  print(f); $\mathbf{proc}\left(x\right)\mathrm{DEBUG}\left(\right)\;x\^2\mathbf{end\; proc}$ (11)

Setting Watchpoints

The stopwhen command can take the following forms.   stopwhen( globalVariableName );   stopwhen( [procedureName, variableName] ); The first form specifies that the debugger should be started when the global variable globalVariableName is changed. Maple environment variables, such as Digits, can also be monitored by using this method. >  stopwhen(Digits); $\left[\mathrm{Digits}\right]$ (12) The second form starts the debugger when the (local or global) variable variableName is changed in the procedure procedureName. When any form of stopwhen is called, Maple returns a list of the current watchpoints. The execution process stops after Maple assigns a value to the watched variable. The debugger displays an assignment statement instead of the last computed result (which would otherwise be the right-hand side of the assignment statement).

	Clearing Watchpoints
	The syntax to call unstopwhen is the same as that for stopwhen. Similar to the stopwhen command, the unstopwhen command returns a list of all (remaining) watchpoints. If no arguments are included in the call to unstopwhen, then all watchpoints are cleared.

Setting Watchpoints on Specified Errors

You can use an error watchpoint to start the debugger when Maple returns a specified error message. When a watched error occurs, the procedure stops executing and the debugger displays the statement in which the error occurred. Error watchpoints are set by using the stoperror command. The stoperror command has the following syntax   stoperror( "errorMessage" ); where errorMessage is a string or a symbol that represents the error message returned from the evaluation of a Maple expression. If the argument is a string, the debugger will be started when an error for which the given string is a prefix is encountered. A list of the current error watchpoints is returned. If no argument is entered in the call to stoperror, the list of current (error) watchpoints is returned. >  stoperror(); $\left[\right]$ (13) >  stoperror( "numeric exception: division by zero" ); $\left[''numeric\; exception:\; division\; by\; zero''\right]$ (14) >  stoperror(); $\left[''numeric\; exception:\; division\; by\; zero''\right]$ (15) If the special name `all` is used instead of a specific error message as the parameter to the stoperror command, a procedure stops executing when any error that would not be trapped occurs. Errors trapped by an error trapping construct (try...catch statement) do not generate an error message. Therefore, the stoperror command cannot be used to catch them. For more information about the try...catch structure, see Trapping Errors. If the special name `traperror` is used instead of a specific error message as the parameter to the stoperror command, a procedure stops executing when any error that is trapped occurs. If the errorMessage parameter is entered in the form traperror["message"] to stoperror, the debugger starts only if the error specified by "message" is trapped. When a procedure stops executing because of an error which causes an exception, continued execution is not possible. Any of the execution control commands, such as next or step (see Controlling the Execution of a Procedure during Debugging I and Controlling the Execution of a Procedure during Debugging II), process the error as if the debugger had not intervened. For example, consider the following two procedures. The first procedure, f, calculates 1/x. The other procedure, g, calls f but traps the "division by zero" error that occurs  when x = 0. >  f := proc(x) 1/x end proc: g := proc(x) local r;         try           f(x);         catch:           infinity;         end try; end proc: If procedure g is executed at x=9, the reciprocal is returned. >  g(9); $\frac{1}{9}$ (16) At x=0, as expected, a value of infinity is returned. >  g(0); $\mathrm{\infty }$ (17) The stoperror command stops the execution process when you call f directly. >  stoperror("numeric exception: division by zero"); $\left[''numeric\; exception:\; division\; by\; zero''\right]$ (18) >  f(0); Error, numeric exception: division by zero f:    1   1/x DBG> cont Error, (in f) numeric exception: division by zero The call to f from g is within a try...catch statement, so the "division by zero" error does not start the debugger. >  g(0); $\mathrm{\infty }$ (19) Instead, try using the stoperror(traperror) command. >  unstoperror( "numeric exception: division by zero" ); $\left[\right]$ (20) >  stoperror( `traperror` ); $\left[\mathrm{traperror}\right]$ (21) This time, Maple does not stop at the error in f. >  f(0); Error, (in f) numeric exception: division by zero However, Maple starts the debugger when the trapped error occurs. >  g(0); Error, numeric exception: division by zero f:    1   1/x DBG> step Error, numeric exception: division by zero g:    3     infinity DBG> step $\mathrm{\infty }$ (22) In the case that a particular error message is specified in the form traperror["message"], the debugger is started only if the error specified by "message" is trapped.

	Clearing Watchpoints on Specified Errors
	Error watchpoints are cleared by using the top-level unstoperror command. The syntax to call the unstoperror command is the same as for the stoperror command. Like the stoperror command, the unstoperror command returns a list of all (remaining) error watchpoints. If no argument is included in the call to unstoperror, all error watchpoints are cleared. >  unstoperror(); $\left[\right]$ (23)

After stopping the execution of a procedure and starting the debugger, you can examine the values of variables or perform other experiments (see the following section, Changing the State of a Procedure during Debugging). After you have examined the state of the procedure, you can continue the execution process by using several different debugger commands.

The most commonly used debugger commands are into, next, step, cont, outfrom, return, and quit.

The return debugger command causes execution of the currently active procedure call to complete. The execution process stops at the first statement after the current procedure.

The other commands are described in the tutorial in The Maple Debugger: A Tutorial Example. For more information on these and other debugger commands, refer to the debugger help page.

When a breakpoint or watchpoint stops the execution of a procedure, the Maple debugger is started. In the debugger mode, you can examine the state of the global variables, local variables, and parameters of the stopped procedure. You can also determine where the execution process stopped, evaluate expressions, and examine procedures.

While in the debugger mode, you can evaluate any Maple expression and perform assignments to local and global variables. To evaluate an expression, enter the expression at the debugger prompt. To perform assignments to variables, use the standard Maple assignment statement.

The debugger evaluates any variable names that you use in the expression in the context of the stopped procedure. Names of parameters or local variables evaluate to their current values in the procedure. Names of global variables evaluate to their current values. Environment variables, such as Digits, evaluate to their values in the stopped procedure's environment.

If an expression corresponds to a debugger command (for example, your procedure has a local variable named step), you can still evaluate it by enclosing it in parentheses.

When the execution process is stopped, you can modify local and global variables by using the assignment statement (:=). The following example sets a breakpoint in the loop only when the index variable is equal to 5.

Reset the index to 3 so that the breakpoint is encountered again.

Maple has added the numbers 1, 2, 3, 4, 3, and 4 and returned 17 as the result. By continuing the execution of the procedure, the numbers 5, 6, 7, 8, 9, and 10 are added and 62 is returned as the result.

You can use two debugger commands to return information about the state of the procedure execution. The list debugger command shows you the location where the execution process stopped within the procedure and the where debugger command shows you the stack of procedure activations.

The list debugger command has the following syntax.

The list debugger command is similar to the showstat command, except that you do not need to specify arguments. If no arguments are included in the call to list, only the five previous statements, the current statement, and the next statement to be executed are displayed. This provides some context in the stopped procedure. In other words, it indicates the static position where the execution process stopped.

The where debugger command shows you the stack of procedure activations. Starting from the top level, it shows you the statement that is executing and the parameters it passed to the called procedure. The where debugger command repeats this for each level of procedure call until it reaches the current statement in the current procedure. In other words, it indicates the dynamic position where execution stopped. The where command has the following syntax.

To illustrate these commands, consider the following example. The procedure check calls the sumn procedure from the previous example.

There is a (conditional) breakpoint in sumn.

When check calls sumn, the breakpoint starts the debugger.

The where debugger command shows that

The next example illustrates the use of where in a recursive function.

If you do not want to view the entire history of the nested procedure calls, use the numLevels parameter in the call to the where debugger command to print a specified number of levels.

The showstop command (and the showstop debugger command) displays a report of all the currently set breakpoints, watchpoints, and error watchpoints. Outside the debugger at the top level, the showstop command has the following syntax.

The next example illustrates the use of the showstop command.

In the following example, breakpoints are set.

In the following example, watchpoints are set.

In the following example, an error watchpoint is set.

The showstop command reports all the breakpoints and watchpoints.

The  showstat, stopat, unstopat, stopwhen, unstopwhen, stoperror, and showstop commands can be used at the debugger prompt. The following list describes the syntax rules for top-level commands used at the debugger prompt.

Except for these rules, the debugger prompt call for each command is of the same form and takes the same arguments as the corresponding top-level command call.

At the debugger prompt, the only permissible Maple statements are debugger commands, expressions, and assignments. The debugger does not permit statements such as if, while, for, read, and save. However, you can use `if` to simulate an if statement and seq to simulate a loop.

The debugger cannot set breakpoints in, or step into, built-in commands, such as diff and has. These commands are implemented in C and compiled into the Maple kernel. Debugging information about these commands is not accessible to Maple. However, if a built-in command calls a library command, for example, the diff command calling `diff/sin`, you can use a breakpoint to stop in the latter.

If a procedure contains two identical statements that are expressions, the debugger cannot always determine the statement at which the execution process stopped. If this situation occurs, you can still use the debugger and the execution process can continue. The debugger issues a warning that the displayed statement number may be incorrect.

Note: This issue occurs because Maple stores all identical expressions as a single occurrence of the expression. The debugger cannot determine at which invocation the execution process stopped.

The simplest tools available for error detection in Maple are the printlevel environment variable, and the trace and tracelast commands. You can use these facilities to trace the execution of both user-defined and Maple library procedures. However, they differ in the type of information that is returned about a procedure.

The printlevel variable is used to control how much information is displayed when a program is executed. By assigning a large integer value to printlevel, you can monitor the execution of statements to selected levels of nesting within procedures. The default value of printlevel is 1. Larger, positive integer values cause the display of more intermediate steps in a computation. Negative integer values suppress the display of information.

The printlevel environment variable is set by using the following syntax, where n is the level to which Maple commands are evaluated.

To determine what value of n to use, note that statements within a particular procedure are recognized in levels that are determined by the nesting of conditional or repetition statements, and by the nesting of procedures. Each loop or if condition increases the evaluation level by 1, and each procedure call increases the evaluation level by 5. Alternatively, you can use a sufficiently large value of n to ensure that all levels are traced. For example, printlevel := 1000 displays information in procedures up to 200 levels deep.

The amount of information that is displayed depends on whether the call to the procedure was terminated with a colon or a semicolon. If a colon is used, only the entry and exit points of the procedure are printed. If a semicolon is used, the results of the statements are also printed.

To reset the value of the printlevel variable, reassign its value to 1.

By assigning a large value to printlevel, the trace of all subsequent Maple procedure calls is displayed. To display the trace of specific procedures, you can use the trace command. The trace command has the following syntax, where arguments is one or more procedure names.

The trace command returns an expression sequence containing the names of the traced procedures. To begin tracing, call the procedure.

Similar to printlevel, the amount of information that is displayed during tracing when trace is used depends on whether the call to the procedure was terminated with a colon or a semicolon.  If a colon is used, only entry and exit points of the procedure are printed. If a semicolon is used, the results of the statements are also printed.

To turn off the tracing of specific procedures, use the untrace command.

Note: You can use debug and undebug as alternate names for trace and untrace.

If running a procedure results in the display of an error message, you can use the tracelast command to determine the last statement executed and the values of variables at the time of the error.  The tracelast command has the following syntax.

After an error message is displayed, the following information is returned from a call to tracelast.

You can find the error in this procedure by studying the results of the tracelast command--the assignment to the local variable j incorrectly uses an equal sign (=) instead of an assignment symbol ( := ).

The information provided by tracelast can become unavailable whenever Maple does a garbage collection. Therefore, it is advisable to use tracelast immediately after an error occurs. For more information about garbage collection in Maple, see Garbage Collection.

An assertion is a verification of the state of Maple at the time the assertion is made. You can include assertions in your procedure to guarantee pre- and post-conditions, and loop invariants during execution by using the ASSERT command. You can also use assertions to guarantee the value returned by a procedure or the value of local variables inside a procedure. The ASSERT command has the following syntax.

If condition evaluates to false, an error is generated and message is printed.  If the first argument evaluates to true, ASSERT returns NULL.

To check assertions, turn on assertion checking before executing a procedure that contains an ASSERT command. To query the current state of assertion checking, or turn assertion checking on or off, use the kernelopts command.

The default state for assertion checking is no assertion checking (assertlevel=0).

Programming note: You should use assertions to verify that your program is working as intended.  You should not use assertions to validate computations or values which are not completely in the control of your program, such as user input.

Turn assertion checking on:

Note that when you set a kernelopts variable, such as when you turn assertion checking on or off, kernelopts returns its previous value.

At any time during the Maple session, you can check the setting for assertion checking by entering the following command.

If assertion checking is on and a procedure that contains an ASSERT statement is executed, the condition represented by the ASSERT statement is checked.

Use the kernelopts command again to turn assertion checking off. (Again, kernelopts returns its previous value.) When assertion checking is off, the overhead of processing an ASSERT statement in a procedure is minimal.

For information on assertion checking and procedures, see Return Type) and Variables in Procedures.

Related to assertions are Maple warning messages. The WARNING command causes a specified warning message to display. The warning is preceded by the string '"Warning, "'.  The WARNING command has the following syntax.

The msgString parameter is the text of the warning message and msgParami are optional parameters to substitute into msgString, if any. For more information on message parameters, see Handling Exceptions.

By default, warning messages are displayed. You can hide warning messages by using the interface(warnlevel=0) command. In this case, the warning is not displayed and the call to WARNING has no effect.

An exception is an event that occurs during the execution of a procedure that disrupts the normal flow of instructions. Many kinds of actions can cause exceptions, for example, attempting to read from a file that does not exist. Maple has two mechanisms available when such situations occur:

Raising Exceptions

The error statement raises an exception. Execution of the current statement sequence is interrupted, and the block and procedure call stack is popped until either an exception handler is encountered, or execution returns to the top level (in which case the exception becomes an error). The error statement has the following syntax.   error msgString, msgParam1, msgParam2, ... The msgString parameter is a string that gives the text of the error message. It can contain numbered parameters of the form %n or %-n, where n is an integer. These numbered parameters are used as placeholders for actual values. In the event that the exception is printed as an error message, the actual values are specified by the msgParam values. For example, >  error "%1 has a %-2 argument, %3, which is missing", f, 4, x; Error, f has a 4th argument, x, which is missing A numbered parameter of the form %n displays the nth msgParam in line-printed notation (that is, as lprint would display it). A numbered parameter of the form %-n displays the nth msgParam, assumed to be an integer, in ordinal form. For example, the %-2 in the previous error statement is displayed as "4th". The special parameter %0 displays all the msgParams, separated by a comma and a space. The error statement evaluates its arguments and then creates an exception object which is an expression sequence with the following elements. •  The name of the procedure in which the exception was raised. If the exception occurred in a procedure local to a module, then the name of the innermost visible (non-local) calling procedure is used. If the exception occurred at the top level (not within a procedure), then the first element of the exception object will be the constant 0. •  The msgString. •  The msgParams, if any. The created exception object is assigned to the global variable lastexception as an expression sequence. For more information on lastexception, refer to the error help page. Note: The actual arguments to the error statement are also assigned to lasterror for compatibility with older versions of Maple. Note: To view the value of the lastexception variable within the debugger, use the showexception debugger command. The error statement normally causes an immediate exit from the current procedure to the Maple session. Maple prints an error message of the following form.   Error, (in procName) msgText In this case, msgText is the text of the error message (which is constructed from the msgString and optional msgParams of the error statement), and procName is the name of the procedure in which the error occurred, or the name of the innermost non-local procedure in the current call stack if the procedure is a module local. If the procedure does not have a name, procName is displayed as unknown. If the error occurs at the top level, outside any procedure, the (in procName) part of the message is omitted. The error statement is commonly used when parameter declarations are not sufficient to check that the actual parameters to a procedure are of the correct type. The following pairup procedure takes a list L of the form [x_1, y_1, x_2, y_2, ..., x_n, y_n] as input, and creates from it a list of the form [[x_1, y_1], [x_2, y_2], ..., [x_n, y_n]]. A simple type check cannot determine if list L has an even number of elements, so you must check this explicitly by using an error statement. >  pairup := proc(L::list)            local i, n;            n := nops(L);            if irem(n, 2) = 1 then               error "list must have an even number of "                     "entries, but had %1", n;            end if;            [seq( [L[2*i-1], L[2*i]], i=1..n/2 )]; end proc: >  pairup([1, 2, 3, 4, 5]); Error, (in pairup) list must have an even number of entries, but had 5 >  pairup([1, 2, 3, 4, 5, 6]); $\left[\left[1\,2\right]\,\left[3\,4\right]\,\left[5\,6\right]\right]$ (46) For information on trapping errors using a try...catch statement, see Trapping Errors.

The Maple maplemint command generates a list of semantic errors for a specified procedure, if any. The semantic errors for which maplemint checks include parameter name conflicts, local and global variable name conflicts, unused variable declarations, and unreachable code. The maplemint command has the following syntax.

In the case where the specified procedure is free of semantic errors, maplemint returns NULL.

Similar to maplemint, Maple also has an external program utility called mint. The mint program is called from outside Maple; it is used to check both semantic and syntax errors in an external Maple source file.

A simple way to measure the time requirements of an executed command at the interactive level is to use the time command. The time command has the following syntax.

The following statements all return the sum of the same sequence of numbers. However, by using the time command, it is clear that the second expression, which uses the add command, is the most efficient method with respect to time consumption.

Two options are available to compare these expression with the equivalent for...do statement. The first is to wrap the statement in an anonymous function call:

Another solution is to use the other form of the time command with no arguments, which returns the total CPU time used since the start of the Maple session. The time is reported in seconds and the value returned is a floating-point number.

To find the time used to execute a particular statement or group of statements, use the following statements.

Therefore, you could use the following set of statements to calculate the amount of time (in seconds) required to add the first 10,000 powers of 2 by using the add command.

CPU time is not the only important measure of efficiency. For most code, the amount of memory used is equally important. This can be measured with the command

For parallel code, the real or wall clock time is also important. The time command with the index real measures real time used:

A uniform interface to all of these metrics is available in the CodeTools package.

By default, CodeTools:-Usage prints the time and memory usage in evaluating the expression. If you want to save the results, you can specify an output option, which ensures that values that can be saved are returned.

For most computers, the third expression above will have the lowest cputime and bytesused values. Depending on the parallelism available, the fourth expression, which uses Threads:-Add, may have the lowest realtime value. The first two expressions will have the highest bytesused values since they both create large sequences of 2*10^4 numbers before adding them to 1.

The Profiling subpackage of CodeTools can be used to display run-time information about a procedure (or procedures). The run-time information is displayed in tabular form and it contains the number of calls to the procedures, the CPU time used, and the number of bytes used by each call. To turn on profiling, use the Profile command.

Then, to display the run-time information collected for the profiled procedures use the SortBy command.

To display the line-by-line profiling information for the specified procedure, use the PrintProfiles command. If no argument is given to PrintProfiles, the run-time information for all profiled procedures is displayed.

To illustrate the use of profiling in Maple, consider the following procedures that compute the nth Fibonacci number. Both procedures contain the same code except that Fibonacci1 uses option remember.

For more information about option remember, see The remember, cache, and system Options.

Turn on profiling for both procedures.

Execute the procedures.

Use the SortBy command to display the run-time information about Fibonacci1 and Fibonacci2.

Use PrintProfiles to display the line-by-line run-time information.

By studying the run-time information, particularly the number of calls to each procedure, you can see that it is more efficient to use option remember in a recursive procedure.

To turn off profiling, use the UnProfile command.  If no argument is given to UnProfile, all procedures currently profiled are returned to their original state.

When a procedure is unprofiled, all run-time information for that procedure is lost.

The CodeTools:-Profiling package has several other useful commands, including LoadProfiles and SaveProfiles, which can be used to save and load profile information to and from a file. By using these commands, you can collect profiling information from commands run with restart commands in between. In the following code, both calls to myproc will be profiled and the data collected as if they had been executed right after each other.

The older profile facility is also still available but it is slower and does not provide line-by-line profiling information. It is still useful for profiling the use of built-in procedures, which are not supported by CodeTools:-Profiling. For more information, refer to the profile help page.

In some cases, it is useful to collect profiling information on every procedure which is invoked during the evaluation of a Maple expression. In this situation, use the exprofile command with the profile kernel option. The output of exprofile can be verbose for moderately complicated code.

The timelimit command is used to limit the amount of CPU time for a computation. The timelimit command has the following syntax, where time is the time limit (in seconds) to evaluate expression.

If the expression is successfully evaluated within the specified time, timelimit returns the value of the expression. If the time limit is reached before the expression is evaluated, timelimit raises an exception.

The exception raised by timelimit can be caught with a try...catch construct.

Multiple calls to timelimit can be nested, causing both limits to be active at once.

Note that in the second of these examples, the inner call, g(10) would normally have finished without triggering the time limit exception.  The outer time limit of 0.25 cpu seconds prevented the inner call from completing.  Thus, the time-out event did not occur inside g and so is not trapped by the catch clause in g.  This illustrates that a try-catch construct cannot capture a time limit exception event generated by a timelimit call in a surrounding scope.

For more information on catching time expired exceptions and nested time limits, refer to the timelimit help page.

Garbage collection deletes all objects that are no longer in use by the program and are occupying space in memory. In Maple, garbage collection will also recover storage from the remember tables of procedures that use an option system or option builtin by removing entries that have no other references to them.

For more information about procedure options, see Options.

Garbage collection is also used to clear cache tables that have temporary entries when a memory usage threshold is reached.

The Maple garbage collection command is gc. It has the following syntax.

Garbage collection occurs automatically when the memory management system determines that memory resources are low.  Alternatively, the gc command explicitly schedules a garbage collection cycle and returns a value of NULL. However, the use of gc is discourage since the underlying memory management system attempts to balance memory usage and performance by tracking the memory behavior of the program.  The decision of when to initiate a garbage collection can be skewed by directly calling gc.