rethrow (MException) - Reissue existing exception

Syntax

Description

rethrow(exception) forces an exception (i.e., error report) to be reissued by MATLAB after the error reporting process has been temporarily suspended to diagnose or remedy the problem. MATLAB typically responds to errors by terminating the currently running program. Errors occurring within a try block, however, bypass this mechanism and transfer control of the program to error handling code in the catch block instead. This enables you to write your own error handling procedures for parts of your program that require them.

The exception input is a scalar object of the MException class that contains information about the cause and location of the error.

The code segment below shows the format of a typical try-catch statement.

try                          try block
   program-code                  |
   program-code                  |
       :                         V
catch exception              catch block
   error-handling code           |
       :                         |
   rethrow(exception)            V
end

An error detected within the try block causes MATLAB to enter the corresponding catch block. The error record constructed by MATLAB in the process of reporting this error passes to the catch command in the statement

catch exception

Error handling code within the catch block uses the information in the error record to address the problem in some predefined manner. The catch block shown here ends with a rethrow statement which throws the exception returned in the catch statement, and then terminates the function:

rethrow(exception)

The most significant difference between rethrow and other MATLAB functions that throw exceptions is in how rethrow handles a piece of the exception record called the stack. The stack keeps a record of where the error occurred and what functions were called in the process. It is a struct array composed of the following fields, where each element of the array represents an exception:

Fields of the Exception Stack	Description
line	Line number from which the exception was thrown.
name	Name of the function being executed at the time.
file	Name of the file containing that function.

Functions such as error, assert, or throw, create the stack with the location from which they were executed. Calling rethrow, however, preserves information from the original exception. In doing so, rethrow enables you to retrace the path taken to the source of the error.

Tips

There are four ways to throw an exception in MATLAB (see the list below). Use the first of these when testing the outcome of some action for failure and reporting the failure to MATLAB. Use one of the remaining three techniques to throw an existing exception.

1. Test the result of some action taken by your program. If the result is found to be incorrect or unexpected, compose an appropriate message and message identifier, and pass these to MATLAB using the error function.

2. Reissue the original exception by throwing the initial error record unmodified. Use the MException rethrow method to do this.

3. Collect additional information on the cause of the error, store it in a new or modified error record, and issue a new exception based on that record. Use the MException addCause and throw methods to do this.

4. Make it appear that the error originated in the caller of the currently running function. Use the MException throwAsCaller method to do this.

rethrow can only issue a previously caught exception. Calling rethrow on an exception that was not previously thrown is an error.

Examples

This example shows the difference between using throw and rethrow at the end of a catch block. The combineArrays function vertically concatenates arrays A and B. When the two arrays have rows of unequal length, the function throws an error.

The first time you run the function, comment out the rethrow command at the end of the catch block so that the function calls throw instead:

function C = combineArrays(A, B)
try
    catAlongDim1(A, B);              % Line 3
catch exception
    throw(exception)                 % Line 5
    % rethrow(exception)             % Line 6
end
    
function catAlongDim1(V1, V2)
    C = cat(1, V1, V2);              % Line 10

When MATLAB throws the exception, it reports an error on line 5 which is the line that calls throw. In some cases, that might be what you want but, in this case, it does not show the true source of the error.

A = 4:3:19;     B = 3:4:19;
combineArrays(A, B)

Error using combineArrays (line 5)
CAT arguments dimensions are not consistent.

Make the following changes to combineArrays.m so that you use rethrow instead:

% throw(exception)                   % Line 5
rethrow(exception)                   % Line 6

Run the function again. This time, line 10 is the first line reported which is where the MATLAB concatenation function cat was called and the exception originated. The next error reported is on line 3 which is where the call to catAlongDim1 was called:

combineArrays(A, B)

Error using cat
CAT arguments dimensions are not consistent.

Error in combineArrays>catAlongDim1 (line 10)
    C = cat(1, V1, V2);              % Line 10
Error in combineArrays (line 3)
    catAlongDim1(A, B);              % Line 3

See Also

addCause(MException) | assert | catch | error | getReport(MException) | last(MException) | MException | throw(MException) | throwAsCaller(MException) | try

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS