Products & Services Solutions Academia Support User Community Company

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 StackDescription
lineLine number from which the exception was thrown.
nameName of the function being executed at the time.
fileName 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:

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:

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);

See Also

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

  


Recommended Products

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

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