Learn more about MATLAB

rethrow (MException) - Reissue existing exception

Syntax

rethrow(errRecord)

Description

rethrow(errRecord) 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 reported within a try-catch statement, 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 errRecord argument is a data structure derived from 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 errRecord              catch block
   error-handling code           |
       :                         |
   rethrow(errRecord)            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 errRecord

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 passes the error record to the caller of this function and then terminates the function:

rethrow(errRecord)

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 one record in what is often a chain of thrown exceptions:

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 M-file containing that function.

Functions such as error, assert, or throw, purposely overwrite the stack with the location from which one of those commands was executed. Calling rethrow, however, preserves information on the stack, keeping it as it was when the exception was first thrown. In doing so, rethrow maintains the location of the original exception, enabling you to retrace the path taken to the source of the error.

Remarks

There are four ways to throw an exception in MATLAB. Use the first of these when testing the outcome of some action for failure and reporting the failure to MATLAB:

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 or assert function.

Use one of the remaining three techniques to resume an exception that is already in progress but has been temporarily suspended in a try-catch statement:

Reissue the original exception by returning the initial error record unmodified. Use the MException rethrow method to do this.
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.
Set or modify the stack field of a new or existing error record to make it appear that the error originated in the caller of the currently running function. Use the MException throwAsCaller method to do this.

You should always either rethrow or throw an exception when exiting the catch block if the faulty condition still exists. Otherwise your function can complete with normal status, even though function may have failed.

rethrow can only issue a previously caught exception. If an exception that was not previously thrown is passed to rethrow, the MATLAB software generates a new exception.

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 errRecord
    fprintf('** ERROR: Dim 2 is %d for A, %d for B **\n', ...
        size(A,2), size(B,2))
    throw(errRecord)                 % Line 7
    % rethrow(errRecord)             % Line 8
end
    
function catAlongDim1(V1, V2)
    C = cat(1, V1, V2);              % Line 12

When MATLAB throws the exception, it reports an error on line 7 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: Incompatible array sizes 6 and 5 **
??? Error using ==> combineArrays at 7
CAT arguments dimensions are not consistent.

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

% throw(errRecord)                   % Line 7
rethrow(errRecord)                   % Line 8

Run the function again. This time, line 12 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:

** ERROR: Incompatible array sizes 6 and 5 **
??? Error using ==> cat
CAT arguments dimensions are not consistent.

Error in ==> combineArrays>catAlongDim1 at 12
    C = cat(1, V1, V2);
Error in ==> combineArrays at 3
    catAlongDim1(A, B);

rethrow (MException) - Reissue existing exception

Syntax

Description

Remarks

Examples

See Also

Recommended Products