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

• 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 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

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

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

• 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 String Conversion.

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

• warning state msg_id
  

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.

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

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

State	Description
on	Enable the display of selected warning message.
off	Disable the display of selected warning message.
query	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.

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

Note    MATLAB starts up with all warnings enabled.

Example 1.   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
  

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

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.

Mode	Description	Default
debug	Stop in the debugger when a warning is invoked.	off
backtrace	Display an M-stack trace after a warning is invoked.	off
verbose	Display a message on how to suppress the warning.	on

The syntax for using 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.

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.

• warning off all
  warning on Simulink:actionNotTaken
  warning on debug
  

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

• (Type "warning off MATLAB:divideByZero" to suppress this 
  warning.)
  

Disable this extra line by turning off verbose mode.

• warning off verbose
  

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.

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

Note    MATLAB does not display warning output when the terminating semicolon is left off of a control statement. You must assign the output to a variable to have output returned from warning.

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.

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

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.

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

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.

Fieldname	Description
identifier	Message identifier string, 'all', or 'last'
state	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.

• 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 that is 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'
  

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.

• 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.   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.   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)
  

Using Message Identifiers with lasterr

Debugging Errors and Warnings