MATLAB®

Warning Control

Overview

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

• Display selected warnings.

• Ignore selected warnings.

• Stop in the debugger when a warning is invoked.

• Display an M-stack trace after a warning is invoked.

Depending on how you set 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 need for the warnings generated by your code. Do you want the 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 each of those warnings. If, on the other hand, you do not require that fine a granularity of control, the warning statements in your code need no message identifiers.

3. When you are ready to run 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.

Back to Top

Warning Statements

The warning statements you put into your M-file code must contain the string 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 do not need to single out certain warnings for control, you need to specify only the message string. Use the syntax shown in Warnings. Valid formats are

warning('warnmsg')
warning('formatted_warnmsg', arg1, arg2, ...)

Attaching an Identifier to the Warning Statement

If you want to be able to apply control statements to specific warnings, you need to include a message identifier in the warning statements you wish to control. The message identifier must be the first argument in the statement. Valid formats are

warning('msg_id', 'warnmsg')
warning('msg_id', 'formatted_warnmsg', arg1, arg2, ...)

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

Note   When you specify more than one input argument with warning, MATLAB treats the warnmsg string as if it were a formatted_warnmsg. This is explained in Formatted Message Strings.

Back to Top

Warning Control Statements

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

warning state msg_id

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

s = warning('state', 'msg_id');

Warning States

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

Message Identifiers

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

Note   MATLAB starts up with all warnings enabled, except for those displayed in response to the command, warning('query', 'all').

Example 1 — Enabling a Selected Warning

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

warning off all
warning on Simulink:actionNotTaken

Next, 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.

warning query all
The default warning state is 'off'. Warnings not set to the 
default are

  State  Warning Identifier

     on  Simulink:actionNotTaken

Example 2 — Disabling the Most Recent Warning

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

inv(0)
Warning: Matrix is singular to working precision.
ans =
   Inf

warning off last

inv(0)              % No warning is displayed this time
ans =
   Inf

Back to Top

Output from Control Statements

The warning function, when used in a control statement, returns a MATLAB structure array containing the previous state of the selected warning(s). Use the following syntax to return this information in structure array s:

s = warning('state', 'msg_id');

You must type the command using the MATLAB function format; parentheses and quotation marks are required.

Note   MATLAB does not display warning output if you do not assign the output to a variable.

The next example turns off divideByZero warnings for the MATLAB component, and returns the identifier and previous state in a 1-by-1 structure array.

s = warning('off','MATLAB:divideByZero')
s = 
    identifier: 'MATLAB:divideByZero'
         state: 'on'

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

s = warning('query', 'msg_id');

If you want to change state, but save the former state so 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.

s = warning('on', 'all');

See 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.

If you query for the state of just one warning, using a message identifier or 'last' in the command, 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:

s = warning('query','last')
s = 
   identifier: 'MATLAB:divideByZero'
        state: 'on'

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

• The first element of the array always represents the default state. (This is the state set by the last warning on|off all command.)

• Each other element of the array represents a warning that is in a state different from the default.

  warning off all
  warning on MATLAB:divideByZero
  warning on MATLAB:fileNotFound
  
  s = warning('query', 'all')
  s = 
     3x1 struct array with fields:
         identifier
         state
  
  s(1)
  ans = 
     identifier: 'all'
          state: 'off'
  
  s(2)
  ans = 
     identifier: 'MATLAB:divideByZero'
          state: 'on'
  
  s(3)
  ans = 
     identifier: 'MATLAB:fileNotFound'
          state: 'on'

Back to Top

Saving and Restoring State

To temporarily change the state of some warnings and then later return to your original settings, 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 Output from Control Statements. The following statement saves the current state of all warnings in structure array s:

s = warning('query', 'all');

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

warning(s)

Example 1 — Performing an Explicit Query

Perform a query of all warnings to save the current state in structure array s:

s = warning('query', 'all');

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

warning(s)

Example 2 — Performing an Implicit Query

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:

s = warning('on', 'Control:parameterNotSymmetric');

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

warning(s)

Back to Top

Backtrace and Verbose Modes

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

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

warning state mode

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.

Note   You cannot save and restore the current state of the backtrace or verbose modes as you can with other states.

Example 1 — Displaying a Stack Trace on a Specific Warning

It can be difficult to locate the source of a warning when it is generated from code buried in several levels of function calls. This example generates a warning within a function that is nested several levels deep within the primary function in file f1.m:

function f1(a, b)
   for k = a:-1:b
       f2(k)
   end
   function f2(x)
       f3(x-1)
       function f3(y)
           x = log(y);
       end
   end
end

After enabling all warnings, run the M-file. The code generates a Log of zero warning. In an M-file of this size, it is not difficult to find the cause of the warning, but in an M-file of several hundred lines, this could take some time:

warning on all

f1(50,1)
Warning: Log of zero.

To simplify the debug process, enable backtrace mode. In this mode, MATLAB reports which function generated the warning (f3), the line number of the attempted operation (line 8), the sequence of function calls that led up to the execution of the function (f1>f2/f3), and the line at which each of these function call was made (3 and 6):

warning on backtrace
f1(50,1)
Warning: Log of zero.
> In f1>f2/f3 at 8
  In f1>f2 at 6
  In f1 at 3

Example 2 — Enabling Verbose Warnings

When you enable verbose warnings, MATLAB displays an extra line of information with each warning that tells you how to suppress it:

Turn on all warnings, disable backtrace (if you have just run the previous example), and enable verbose warnings:

warning on all
warning off backtrace
warning on verbose

Call the function described in Example 1 to find out how to suppress any warnings generated by that function:

f1(50,1)
Warning: Log of zero.
(Type "warning off MATLAB:log:logOfZero" to suppress this warning.)

Use the message identifier MATLAB:log:logOfZero to disable only this warning, and run the function again. This time the warning message is not displayed:

warning off MATLAB:log:logOfZero

f1(50,1)

Back to Top

Warnings

Debugging Errors and Warnings