Programming and Data Types    

Warning Control

MATLAB gives you the ability to control what happens when a warning is encountered during M-file program execution. Options that are available include

Depending on how you set up your warning controls, you can have these actions affect all warnings in your code, specific warnings that you select, or just the most recently invoked warning.

Setting up this system of warning control involves several steps.

  1. Start by determining the scope of the control you will need for the warnings generated by your code. Do you want the above control operations to affect all the warnings in your code at once, or do you want to be able to control certain warnings separately?
  2. If the latter is true, you will need to identify those warnings you want to selectively control. This requires going through your code and attaching unique message identifiers to those warnings. If, on the other hand, you don't require that fine a granularity of control, then the warning statements in your code need no message identifiers.
  3. When you are ready to execute your programs, use the MATLAB warning control statements to exercise the desired controls on all or selected warnings. Include message identifiers in these control statements when selecting specific warnings to act upon.

Warning Statements

The warning statements that you put into your M-file code must contain the string that is to be displayed when the warning is incurred, and may also contain a message identifier. If you are not planning to use warning control or if you have no need to single out certain warnings for control, then you only need to specify the message string. Use the syntax shown in the section on Warnings. Valid formats are

Attaching an Identifier to the Warning Statement.   If there are specific warnings that you want MATLAB to be able to apply control statements to, then you need to include a message identifier in the warning statement. The message identifier must be the first argument in the statement. Valid formats are

See Message Identifiers for information on how to specify the msg_id argument.

Warning Control Statements

Once you have the warning statements in your M-file code and are ready to execute the code, you can indicate how you want MATLAB to act on these warnings by issuing control statements. These statements place the specified warning(s) into a desired state and have the format

Control statements can also return information on the state of selected warnings. This only happens if you assign the output to a variable, as shown below. See Output from Control Statements.

Warning States.   There are three possible values for the state argument of a warning control statement.

Enable the display of selected warning message.
Disable the display of selected warning message.
Display the current state of selected warning.

Message Identifiers.   In addition to the message identifiers already discussed, there are two other identifiers that you can use in control statements only.

msg_id string
Set selected warning to the specified state.
Set all warnings to the specified state.
Set only the last displayed warning to the specified state.

Example 1.   Enable just the actionNotTaken warning from Simulink by first turning off all warnings and then setting just that warning to on.

Use query to determine the current state of all warnings. It reports that you have set all warnings to off with the exception of Simulink:actionNotTaken.

Example 2.   Evaluating inv on zero displays a warning message. Turn off the most recently invoked warning with warning off last.

Debug, Backtrace, and Verbose Modes

In addition to warning messages, there are three modes that can be enabled or disabled with a warning control statement. These modes are shown here.

Stop in the debugger when a warning is invoked.
Display an M-stack trace after a warning is invoked.
Display a message on how to suppress the warning.

The syntax for using this type of control statement is as follows, where state, in this case, can be only on, off, or query.

Note that there is no need to include a message identifier with this type of control statement. All enabled warnings are affected by the this type of control statement.

Example 1.   To enter debug mode whenever a Simulink actionNotTaken warning is invoked, first turn off all warnings and enable only this one type of warning using its message identifier. Then turn on debug mode for all enabled warnings. When you run your program, MATLAB will stop in debug mode just before this warning is executed. You will see the debug prompt (K>>) displayed.

Example 2.   By default, there is an extra line of information shown with each warning telling you how to suppress it.

Disable this extra line by turning off verbose mode.

Output from Control Statements

When you include an output variable in a control statement, warning returns a MATLAB structure array containing the state of the selected warning and assigns it to this variable. You must type the command using the MATLAB function format, that is, parentheses and quotation marks are required.

You can use output variables with any type of control statement. If you just want to collect the information but don't want to change state, then simply perform a query on the warning(s). MATLAB returns the current state of those warnings selected by the message identifier.

If you want to change state, but also save the former state so that you can restore it later, use the return structure array to save that state. The following example does an implicit query, returning state information in s, and then turns on all warnings.

See the section, Saving and Restoring State, for more information on restoring the former state of warnings.

Output Structure Array.   Each element of the structure array returned by warning contains two fields.

Message identifier string, 'all', or 'last'
State of warning(s) prior to invoking this control statement

If you query for the state of just one warning, using a message identifier or 'last' in the command, then MATLAB returns a one-element structure array. The identifier field contains the selected message identifier and the state field holds the current state of that warning.

If you query for the state of all warnings, using 'all' in the command, MATLAB returns a structure array having one or more elements.

Saving and Restoring State

If you want to temporarily change the state of some warnings and then later return to your original settings, you can save the original state in a structure array and then restore it from that array. You can save and restore the state of all of your warnings or just one that you select with a message identifier.

To save the current warning state, assign the output of a warning control statement, as discussed in the last section, Output from Control Statements. The following statement saves the current state of all warnings in structure array s.

To restore state from s, use the syntax shown below. Note that the MATLAB function format (enclosing arguments in parentheses) is required.

Example 1.   Perform a query of all warnings to save the current state in structure array s.

Then, after doing some work that includes making changes to the state of some warnings, restore the original state of all warnings.

Example 2.   Turn on one particular warning, saving the previous state of this warning in s. Remember that this nonquery syntax (where state equals on or off) performs an implicit query prior to setting the new state.

Restore the state of that one warning when you are ready, with

  Using Message Identifiers with lasterr Debugging Errors and Warnings