MATLAB®

Debugging Process and Features

Ways to Debug M-Files

You can debug the M-files using the Editor, which is a graphical user interface, as well as by using debugging functions from the Command Window. You can use both methods interchangeably. These topics and the example describe both methods.

Back to Top

Preparing for Debugging

Do the following to prepare for debugging:

• Open the file — To use the Editor for debugging, open it with the file to run.

• Save changes — If you are editing the file, save the changes before you begin debugging. If you try to run a file with unsaved changes from within the Editor, the file is automatically saved before it runs. If you run a file with unsaved changes from the Command Window, MATLAB^® software runs the saved version of the file, so you will not see the results of your changes.

• Add the files to a directory on the search path or put them in the current directory — Be sure the file you run and any files it calls are in directories that are on the search path. If all files to be used are in the same directory, you can instead make that directory be the current directory.

Debugging Example — The Collatz Problem

The debugging process and features are best described via an example. To prepare to use the example, create two M-files, collatz.m and collatzplot.m, that produce data for the Collatz problem.

For any given positive integer, n, the Collatz function produces a sequence of numbers that always resolves to 1. If n is even, divide it by 2 to get the next integer in the sequence. If n is odd, multiply it by 3 and add 1 to get the next integer in the sequence. Repeat the steps until the next integer is 1. The number of integers in the sequence varies, depending on the starting value, n.

The Collatz problem is to prove that the Collatz function will resolve to 1 for all positive integers. The M-files for this example are useful for studying the Collatz problem. The file collatz.m generates the sequence of integers for any given n. The file collatzplot.m calculates the number of integers in the sequence for all integers from 1 through m, and plots the results. The plot shows patterns that can be further studied.

Following are the results when n is 1, 2, or 3.

M-Files for the Collatz Problem.   Following are the two M-files you use for the debugging example. To create these files on your system, open two new M-files. Select and copy the following code from the Help browser and paste it into the M-files. Save and name the files collatz.m and collatzplot.m. Save them to your current directory or add the directory where you save them to the search path. One of the files has an embedded error to illustrate the debugging features.

Code for collatz.m.

function sequence=collatz(n)
% Collatz problem. Generate a sequence of integers resolving to 1
% For any positive integer, n:
% 	Divide n by 2 if n is even
% 	Multiply n by 3 and add 1 if n is odd
% 	Repeat for the result
% 	Continue until the result is 1%

sequence = n;
next_value = n;
while next_value > 1
	if rem(next_value,2)==0
		next_value = next_value/2;
	else
		next_value = 3*next_value+1;
	end
	sequence = [sequence, next_value];
end

Code for collatzplot.m.

function collatzplot(m)
% Plot length of sequence for Collatz problem
% Prepare figure
clf
set(gcf,'DoubleBuffer','on')
set(gca,'XScale','linear')
%
% Determine and plot sequence and sequence length
for N = 1:m
	plot_seq = collatz(N);
	seq_length(N) = length(plot_seq);
	line(N,plot_seq,'Marker','.','MarkerSize',9,'Color','blue')
	drawnow
end

Trial Run for Example.   Open the file collatzplot.m. Make sure the current directory is the directory in which you saved collatzplot.

Try out collatzplot to see if it works correctly. Use a simple input value, for example, 3, and compare the results to those shown in the preceding table. Typing

collatzplot(3)

produces the plot shown in the following figure.

The plot for n = 1 appears to be correct—for 1, the Collatz series is 1, and contains one integer. But for n = 2 and n = 3, it is wrong because there should be only one value plotted for each integer, the number of integers in the sequence, which the preceding table shows to be 2 (for n = 2) and 8 (for n = 3). Instead, multiple values are plotted. Use MATLAB debugging features to isolate the problem.

Back to Top

Setting Breakpoints

Set breakpoints to pause execution of the M-file so you can examine values where you think the problem might be. You can set breakpoints in the Editor, using functions in the Command Window, or both.

There are three basic types of breakpoints you can set in M-files:

• A standard breakpoint, which stops at a specified line in an M-file. For details, see Setting Standard Breakpoints.

• A conditional breakpoint, which stops at a specified line in an M-file only under specified conditions. For details, see Conditional Breakpoints.

• An error breakpoint that stops in any M-file when it produces the specified type of warning, error, or NaN or infinite value. For details, see Error Breakpoints.

You can disable standard and conditional breakpoints so that MATLAB temporarily ignores them, or you can remove them. For details, see Disabling and Clearing Breakpoints. Breakpoints are not maintained after you exit the MATLAB session.

You can only set valid standard and conditional breakpoints at executable lines in saved files that are in the current directory or in directories on the search path. When you add or remove a breakpoint in a file that is not in a directory on the search path or in the current directory, a dialog box appears, presenting you with options that allow you to add or remove the breakpoint. You can either change the current directory to the directory containing the file, or you can add the directory containing the file to the search path.

Do not set a breakpoint at a for statement if you want to examine values at increments in the loop. For example, in

for n = 1:10 
    m = n+1; 
end 

MATLAB executes the for statement only once, which is efficient. Therefore, when you set a breakpoint at the for statement and step through the file, you only stop at the for statement once. Instead place the breakpoint at the next line, m=n+1 to stop at each pass through the loop.

You cannot set breakpoints while MATLAB is busy, for example, running an M-file, unless that M-file is paused at a breakpoint.

Setting Standard Breakpoints

To set a standard breakpoint using the Editor, click in the breakpoint alley at the line where you want to set the breakpoint. The breakpoint alley is the narrow column on the left side of the Editor, just right of the line number. Set breakpoints at lines that are preceded by a - (dash). Lines not preceded by a dash, such as comments or blank lines, are not executable—if you try to set a breakpoint there, it is actually set at the next executable line. Other ways to set a breakpoint are to position the cursor in the line and then click the Set/Clear Breakpoint button on the toolbar, or select Set/Clear Breakpoint from the Debug menu or the context menu. A breakpoint icon appears.

Set Breakpoints for the Example.   It is unclear whether the problem in the example is in collatzplot or collatz. To start, set breakpoints in collatzplot.m at lines 10, 11, and 12. The breakpoint at line 10 allows you to step into collatz to see if the problem might be there. The breakpoints at lines 11 and 12 stop the program where you can examine the interim results.

Valid (Red) and Invalid (Gray) Breakpoints.   Red breakpoints are valid standard breakpoints. If breakpoints are instead gray, they are not valid.

Breakpoints are gray for either of these reasons:

• The file has not been saved since changes were made to it. Save the file to make breakpoints valid. The gray breakpoints become red, indicating they are now valid. Any gray breakpoints that were entered at invalid breakpoint lines automatically move to the next valid breakpoint line with the successful file save.

• There is a syntax error in the file. When you set a breakpoint, an error message appears indicating where the syntax error is. Fix the syntax error and save the file to make breakpoints valid.

Function Alternative for Setting Breakpoints

To set a breakpoint using the debugging functions, use dbstop. For the example, type

dbstop in collatzplot at 10
dbstop in collatzplot at 11
dbstop in collatzplot at 12

Some useful related functions are

• dbtype — Lists the M-file with line numbers in the Command Window.

• dbstatus — Lists breakpoints.

Back to Top

Running an M-File with Breakpoints

After setting breakpoints, run the M-file from the Command Window or the Editor.

Running the Example

For the example, run collatzplot for the simple input value, 3, by typing in the Command Window

collatzplot(3)

The example, collatzplot, requires an input argument and therefore runs only from the Command Window and not from the Editor.

Results of Running an M-File Containing Breakpoints

Running the M-file results in the following:

• The prompt in the Command Window changes to

  K>>

  indicating that MATLAB is in debug mode.

• The program pauses at the first breakpoint. This means that line will be executed when you continue. The pause is indicated in the Editor by the green arrow just to the right of the breakpoint, which in the example, is line 10 of collatzplot as shown here.

  

  If you use debugging functions from the Command Window, the line at which you are paused is displayed in the Command Window. For the example, it would show

  10  	plot_seq = collatz(N);
  

• The function displayed in the Stack field on the toolbar changes to reflect the current function (sometimes referred to as the caller or calling workspace). The call stack includes subfunctions as well as called functions. If you use debugging functions from the Command Window, use dbstack to view the current call stack.

• If the file you are running is not in the current directory or a directory on the search path, you are prompted to either add the directory to the path or change the current directory.

In debug mode, you can set breakpoints, step through programs, examine variables, and run other functions.

Note that MATLAB software could become nonresponsive if it stops at a breakpoint while displaying a modal dialog box or figure that your M-file creates. In that event, use Ctrl+C to go the MATLAB prompt.

Back to Top

Stepping Through an M-File

While debugging, you can step through an M-file, pausing at points where you want to examine values.

Use the step buttons or the step items in the Debug menu of the Editor or desktop, or use the equivalent functions.

Toolbar Button	Debug Menu Item	Description	Function Alternative
	Run m-file or Run Publish Configuration for m-file	Commence execution of M-file and run until completion or until a breakpoint is encountered. The Run Publish Configurations for M-file menu item provides a submenu that enables you to select a particular run configuration or to edit the run configurations for the M-file. If you choose Run M-file, the default run configuration is used.	None
None	Go Until Cursor	Continue execution of M-file until the line where the cursor is positioned. Also available on the context menu.	None
	Step	Execute the current line of the M-file.	dbstep
	Step In	Execute the current line of the M-file and, if the line is a call to another function, step into that function.	dbstep in
	Continue	Resume execution of M-file until completion or until another breakpoint is encountered.	dbcont
	Step Out	After stepping in, run the rest of the called function or subfunction, leave the called function, and pause.	dbstep out

Continue Running in the Example

In the example, collatzplot is paused at line 10. Because the problem results are correct for N/n = 1, continue running until N/n = 2. Press the Continue button three times to move through the breakpoints at lines 10, 11, and 12. Now the program is again paused at the breakpoint at line 10.

Stepping In to Called Function in the Example

Now that collatzplot is paused at line 10 during the second iteration, use the Step In button or type dbstep in in the Command Window to step into collatz and walk through that M-file. Stepping into line 10 of collatzplot goes to line 9 of collatz. If collatz is not open in the Editor, it automatically opens if you have selected Debug > Open M-Files When Debugging.

The pause indicator at line 10 of collatzplot changes to a hollow arrow , indicating that MATLAB control is now in a subfunction called from the main program. The call stack shows that the current function is now collatz.

In the called function, collatz in the example, you can do the same things you can do in the main (calling) function—set breakpoints, run, step through, and examine values.

Back to Top

Examining Values

While the program is paused, you can view the value of any variable currently in the workspace. Examine values when you want to see whether a line of code has produced the expected result or not. If the result is as expected, continue running or step to the next line. If the result is not as expected, then that line, or a previous line, contains an error. Use the following methods to examine values:

• Selecting the Workspace

• Viewing Values as Data tips in the Editor

• Viewing Values in the Command Window

• Viewing Values in the Workspace Browser and Variable Editor

• Evaluating a Selection

• Examining Values in the Example

Many of these methods are used in Examining Values in the Example.

Selecting the Workspace

Variables assigned through the Command Window and created using scripts are considered to be in the base workspace. Variables created in a function belong to their own function workspace. To examine a variable, you must first select its workspace. When you run a program, the current workspace is shown in the Stack field. To examine values that are part of another workspace for a currently running function or for the base workspace, first select that workspace from the list in the Stack field.

If you use debugging functions from the Command Window, use dbstack to display the call stack. Use dbup and dbdown to change to a different workspace. Use who or whos to list the variables in the current workspace.

Workspace in the Example.   At line 10 of collatzplot, you stepped in, so the current line is 9 in collatz. The Stack shows that collatz is the current workspace.

Viewing Values as Data tips in the Editor

In the Editor, position the pointer to the left of a variable. Its current value appears—this is called a data tip, which is like a ToolTip for data. The data tip stays in view until you move the pointer. If you have trouble getting the data tip to appear, click in the line containing the variable and then move the pointer next to the variable.

A related function is datatipinfo.

Data tips in the Example.   Position the pointer over n in line 9 of collatz. The data tip shows that n = 2, as expected.

Viewing Values in the Command Window

You can examine values while in debug mode at the K>> prompt. To see the variables currently in the workspace, use who. Type a variable name in the Command Window and it displays the variable's current value. For the example, to see the value of n, type

n

The Command Window displays the expected result

n =
	2

and displays the debug prompt, K>>.

Viewing Values in the Workspace Browser and Variable Editor

You can view the value of variables in the Value column of the Workspace browser. The Workspace browser displays all variables in the current workspace. Use the Stack in the Workspace browser to change to another workspace and view its variables.

The Value column does not show all details for all variables. To see details, double-click a variable in the Workspace browser. The Variable Editor opens, displaying the content for that variable. You can open the Variable Editor directly for a variable using openvar.

To see the value of n in the Variable Editor for the example, type

openvar n

and the Variable Editor opens, showing that n = 2 as expected.

Evaluating a Selection

Select a variable or equation in an M-file in the Editor. Right-click and select Evaluate Selection from the context menu (for a single-button mouse, use Ctrl+click). The Command Window displays the value of the variable or equation. You cannot evaluate a selection while MATLAB is busy, for example, running an M-file.

Examining Values in the Example

Step from line 9 through line 13 in collatz. Step again, and the pause indicator jumps to line 17, just after the if loop, as expected. Step again, to line 18, check the value of sequence in line 17 and see that the array is

2  1

as expected for n = 2. Step again, which moves the pause indicator from line 18 to line 11. At line 11, step again. Because next_value is now 1, the while loop ends. The pause indicator is at line 11 and appears as a green down arrow . This indicates that processing in the called function is complete and program control will return to the calling program. Step again from line 11 in collatz and execution is now paused at line 10 in collatzplot.

Note that instead of stepping through collatz, the called function, as was just done in this example, you can step out from a called function back to the calling function, which automatically runs the rest of the called function and returns to the next line in the calling function. To step out, use the Step Out button or type dbstep out in the Command Window.

In collatzplot, step again to advance to line 11, then line 12. The variable seq_length in line 11 is a vector with the elements

1  2

which is correct.

Finally, step again to advance to line 13. Examining the values in line 12, N  = 2 as expected, but the second variable, plot_seq, has two values, where only one value is expected. While the value for plot_seq is as expected

2  1

it is the incorrect variable for plotting. Instead, seq_length(N) should be plotted.

Back to Top

Correcting Problems and Ending Debugging

These are some of the ways to correct problems and end the debugging session:

• Changing Values and Checking Results

• Ending Debugging

• Disabling and Clearing Breakpoints

• Saving Breakpoints

• Correcting an M-File

• Completing the Example

• Running Sections in M-Files That Have Unsaved Changes

Many of these features are used in Completing the Example.

Changing Values and Checking Results

While debugging, you can change the value of a variable in the current workspace to see if the new value produces expected results. While the program is paused, assign a new value to the variable in the Command Window, Workspace browser, or Variable Editor. Then continue running or stepping through the program. If the new value does not produce the expected results, the program has a different problem.

Ending Debugging

After identifying a problem, end the debugging session. You must end a debugging session if you want to change and save an M-file to correct a problem, or if you want to run other functions in MATLAB.

Note   It is recommended that you quit debug mode before editing an M-file. If you edit an M-file while in debug mode, you can get unexpected results when you run the file. If you do edit an M-file while in debug mode, breakpoints turn gray, indicating that results might not be reliable. See Valid (Red) and Invalid (Gray) Breakpoints for details. If you attempt to save an edited M-file while in debug mode, a dialog box appears allowing you to exit debug mode and save the file.

To end debugging, click the Exit Debug Mode button , or select Exit Debug Mode from the Debug menu.

You can instead use the function dbquit or the Shift+F5 keyboard shortcut to end debugging.

After quitting debugging, pause indicators in the Editor display no longer appear, and the normal prompt >> appears in the Command Window instead of the debugging prompt, K>>. You can no longer access the call stack.

Disabling and Clearing Breakpoints

Disable a breakpoint to temporarily ignore it. Clear a breakpoint to remove it.

Disabling and Enabling Breakpoints.   You can disable selected breakpoints so the program temporarily ignores them and runs uninterrupted, for example, after you think you identified and corrected a problem. This is especially useful for conditional breakpoints—see Conditional Breakpoints.

To disable a breakpoint, right-click the breakpoint icon and select Disable Breakpoint from the context menu, or click anywhere in a line and select Enable/Disable Breakpoint from the Debug or context menu. You can also disable a conditional breakpoint by clicking the breakpoint icon. This puts an X through the breakpoint icon as shown here.

After disabling a breakpoint, you can enable it to make it active again, or clear it. To enable it, right-click the breakpoint icon and select Enable Breakpoint from the context menu, or click anywhere in a line and select Enable/Disable Breakpoint from the Breakpoints or context menu. The X no longer appears on the breakpoint icon and program execution will pause at that line.

When you run dbstatus, the resulting message for a disabled breakpoint is

Breakpoint on line 10 has conditional expression 'false'.

Clearing (Removing) Breakpoints.   All breakpoints remain in a file until you clear (remove) them or until they are automatically cleared. Clear a breakpoint after determining that a line of code is not causing a problem.

To clear a breakpoint in the Editor, click anywhere in a line and select Set/Clear Breakpoint from the Debug or context menu. The breakpoint for that line is cleared. Another way to clear a breakpoint is to click a standard breakpoint icon, or a disabled conditional breakpoint icon.

To clear all breakpoints in all files, select Debug > Clear Breakpoints in All Files, or click its equivalent button on the toolbar.

The function that clears breakpoints is dbclear. To clear all breakpoints, use dbclear all. For the example, clear all of the breakpoints in collatzplot by typing

dbclear all in collatzplot

Breakpoints are automatically cleared when you

• End the MATLAB session

• Clear the M-file using clear name or clear all

Note   When clear name or clear all is in a statement in an M-file that you are debugging, it clears the breakpoints.

Saving Breakpoints

You can use the s=dbstatus syntax and then save s to save the current breakpoints to a MAT-file. At a later time, you can load s and restore the breakpoints using dbstop(s). For more information, including an example, see the dbstatus reference page.

Correcting an M-File

To correct a problem in an M-file,

1. Quit debugging.

   Do not make changes to an M-file while MATLAB is in debug mode. If you do edit an M-file while in debug mode, breakpoints turn gray, indicating that results might not be reliable. SeeValid (Red) and Invalid (Gray) Breakpoints for details.

2. Make changes to the M-file.

3. Save the M-file.

4. Set, disable, or clear breakpoints, as appropriate.

5. Run the M-file again to be sure it produces the expected results.

Completing the Example

To correct the problem in the example, do the following:

1. End the debugging session. One way to do this is to select Exit Debug Mode from the Debug menu.

2. In collatzplot.m line 12, change the string plot_seq to seq_length(N) and save the file.

3. Clear the breakpoints in collatzplot.m. One way to do this is by typing

   dbclear all in collatzplot

   in the Command Window.

4. Run collatzplot for m = 3 by typing

   collatzplot(3)

   in the Command Window.

5. Verify the result. The figure shows that the length of the Collatz series is 1 when n = 1, 2 when n = 2, and 8 when n = 3, as expected.

   

6. Test the function for a slightly larger value of m, such as 6, to be sure the results are still accurate. To make it easier to verify collatzplot for m = 6 as well as the results for collatz, add this line at the end of collatz.m

   sequence
   

   which displays the series in the Command Window. The results for when n = 6 are

   sequence =
   
        6     3    10     5    16     8     4     2     1

   Then run collatzplot for m = 6 by typing

   collatzplot(6)
   

7. To make debugging easier, you ran collatzplot for a small value of m. Now that you know it works correctly, run collatzplot for a larger value to produce more interesting results. Before doing so, you might want to disable output for the line you just added in step 6, line 19 of collatz.m, by adding a semicolon to the end of the line so it appears as

   sequence;

   Then run

   collatzplot(500)

   The following figure shows the lengths of the Collatz series for n = 1 through n = 500.

   

Running Sections in M-Files That Have Unsaved Changes

It is a good practice to make changes to an M-file after you quit debugging, and to save the changes and then run the file. Otherwise, you might get unexpected results. But there are situations where you might want to experiment during debugging, to make a change to a part of the file that has not yet run, and then run the remainder of the file without saving the change.

To do this, while stopped at a breakpoint, make a change to a part of the file that has not yet run. Breakpoints will turn gray, indicating they are invalid. Then select all of the code after the breakpoint, right-click, and choose Evaluate Selection from the context menu. You can also use cell mode to do this.

Back to Top

Conditional Breakpoints

Set conditional breakpoints to cause MATLAB to stop at a specified line in a file only when the specified condition is met. One particularly good use for conditional breakpoints is when you want to examine results after a certain number of iterations in a loop. For example, set a breakpoint at line 10 in collatzplot, specifying that MATLAB should stop only if N is greater than or equal to 2. This section covers the following topics:

• Setting Conditional Breakpoints

• Copying, Modifying, Disabling, and Clearing Conditional Breakpoints

• Function Alternative for Conditional Breakpoints

Setting Conditional Breakpoints

To set a conditional breakpoint, follow these steps:

1. Click in the line where you want to set the conditional breakpoint. Then select Set/Modify Conditional Breakpoint from the Debug or context menu. If a standard breakpoint already exists at that line, use this same method to make it conditional.

   The MATLAB Editor conditional breakpoint dialog box opens as shown in this example.

   

2. Type a condition in the dialog box, where a condition is any legal MATLAB expression that returns a logical scalar value. Click OK. As noted in the dialog box, the condition is evaluated before running the line. For the example, at line 10 in collatzplot, enter

   N>=2

   as the condition. A yellow breakpoint icon (indicating the breakpoint is conditional) appears in the breakpoint alley at that line.

When you run the file, MATLAB software enters debug mode and pauses at the line only when the condition is met. In the collatzplot example, MATLAB runs through the for loop once and pauses on the second iteration at line 10 when N is 2. If you continue executing, MATLAB pauses again at line 10 on the third iteration when N is 3.

Copying, Modifying, Disabling, and Clearing Conditional Breakpoints

To copy a conditional breakpoint, right-click the icon in the breakpoint alley and select Copy from the context menu. Then right-click in the breakpoint alley at the line where you want to paste the conditional breakpoint and select Paste from the context menu.

Modify the condition for the breakpoint in the current line by selecting Set/Modify Conditional Breakpoint from the Debug or context menu.

Click a conditional breakpoint icon to disable it. Click a disabled conditional breakpoint to clear it.

Function Alternative for Conditional Breakpoints

Use the dbstop function with appropriate arguments to set conditional breakpoints from the Command Window, and use dbclear to clear them. Use dbstatus to view the breakpoints currently set, including any conditions, which are listed in the expression field. If no condition exists, the value in the expression field is [  ] (empty). For details, see the function reference pages: dbstop, dbclear, and dbstatus.

Back to Top

Breakpoints in Anonymous Functions

There can be multiple breakpoints in an M-file line that contains anonymous functions. There can be a breakpoint for the line itself (MATLAB software stops at the start of the line), as well as a breakpoint for each anonymous function in that line. When you add a breakpoint to a line containing an anonymous function, the Editor asks exactly where in the line you want to add the breakpoint. If there is more than one breakpoint in a line, the breakpoint icon is blue .

When there are multiple breakpoints set on a line, the icon is always blue, regardless of the status of any of the breakpoints on the line. Position the mouse on the icon and a ToolTip displays information about all breakpoints in that line.

To perform a breakpoint action for a line that can contain multiple breakpoints, such as Clear Breakpoint, right-click the breakpoint alley at that line and select the action. MATLAB prompts you to specify the exact breakpoint on which to act in that line.

When you set a breakpoint in an anonymous function, MATLAB stops when the anonymous function is called. The following illustration shows the Editor when you set a breakpoint in the anonymous function sqr in line 2, and then run the file. MATLAB stops when it runs sqr in line 4. After you continue execution, MATLAB stops again when it runs sqr the second time in line 4. Note that the Stack display shows the anonymous function.

Back to Top

Error Breakpoints

Set error breakpoints to stop program execution and enter debug mode when MATLAB encounters a problem. Unlike standard and conditional breakpoints, you do not set these breakpoints at a specific line in a specific file. Rather, once set, MATLAB stops at any line in any file when the error condition specified via the error breakpoint occurs. MATLAB then enters debug mode and opens the file containing the error, with the pause indicator at the line containing the error. Files open only when the you select Debug > Open M-Files . Error breakpoints remain in effect until you clear them or until you end the MATLAB session. You can set error breakpoints from the Debug menu in any desktop tool. This section covers the following topics:

• Setting Error Breakpoints

• Error Breakpoint Types and Options

• Function Alternative for Error Breakpoints

Setting Error Breakpoints

To set error breakpoints, select Debug > Stop if Errors/Warnings. In the resulting Stop if Errors/Warnings for All Files dialog box, specify error breakpoints on all appropriate tabs and click OK. To clear error breakpoints, select the Never stop if ... option for all appropriate tabs and click OK.

For example, to pause execution when a warning occurs, select the Warnings tab, and from it select Always stop if warning, then click OK. When you run an M-file and MATLAB produces a warning, execution pauses, MATLAB enters debug mode, and the file opens in the Editor at the line that produced the warning. To remove the warning breakpoint, select Never stop if warning in the Warnings tab and click OK.

Error Breakpoint Types and Options

The four basic types of error breakpoints you can set are Errors, Try/Catch Errors, Warnings, and NaN or Inf. Select the Always stop if ... option for each tab to set that type of breakpoint. Select the Use message identifiers ... option to limit each type of error breakpoint (except NaN or Inf) so that execution stops only for specific errors.

Errors.   When an error occurs, execution stops, unless the error is in a try...catch block. MATLAB enters debug mode and opens the M-file to the line in the try portion of the block that produced the error. You cannot resume execution.

Try/Catch Errors.   When an error occurs in a try...catch block, execution pauses. MATLAB enters debug mode and opens the M-file to the line that produced the error. You can resume execution or use debugging features.

Warnings.   When a warning is produced, MATLAB pauses, enters debug mode, and opens the M-file, paused at the line that produced the warning. You can resume execution or use debugging features.

NaN or Inf.   When an operator, function call, or scalar assignment produces a NaN (not-a-number) or Inf (infinite) value, MATLAB pauses, enters debug mode, and opens the M-file, paused immediately after the line that encountered the value. You can resume execution or use debugging features.

Use Message Identifiers.   Execution stops only when MATLAB encounters one of the specified errors. This option is not available for the NaN or Inf type of error breakpoint. To use this feature:

1. Select the Errors, Try/Catch Errors, or Warnings tab.

2. Select the Use Message Identifiers option.

3. Click Add.

4. In the resulting Add Message Identifier dialog box, supply the message identifier of the specific error you want to stop for, where the identifier is of the form component:message, and click OK.

5. The message identifier you added appears in the Stop If Errors/Warnings for All Files dialog box, where you click OK.

   You can add multiple message identifiers, and edit or remove them.

One way to obtain an error message identifier generated by a MATLAB function for example, is to produce the error, and then run the lasterror function. MATLAB returns the error message and identifier. Copy the identifier from the Command Window output and paste it into the Add Message Identifier dialog box. An example of an error message identifier is MATLAB:UndefinedFunction. Similarly, to obtain a warning message identifier, produce the warning and then run [m,id] = lastwarn; MATLAB returns the last warning identifier to id. An example of a warning message identifier is MATLAB:divideByZero.

Function Alternative for Error Breakpoints

The function equivalent for each option appears in the Stop if Errors/Warnings for All Files dialog box. For example, the function equivalent for Always stop if error is dbstop if error. Use the dbstop function with appropriate arguments to set error breakpoints from the Command Window, and use dbclear to clear them. Use dbstatus to view the error breakpoints currently set. Error breakpoints are listed in the cond field and message identifiers for breakpoints are listed in the identifier field of the dbstatus output.

Back to Top

M-Lint Code Analyzer

Using Cells for Rapid Code Iteration and Publishing Results