Learn more about MATLAB

throw (MException) - Issue exception and terminate function

Syntax

throw(errRecord)

Description

throw(errRecord) issues an exception based on the information contained in error record errRecord. The exception terminates the currently running function and returns control to its caller. The errRecord argument is a data structure derived from the MException class that contains information on the cause of the error and where it occurred. The throw function passes errRecord back to the caller of the currently running function. and eventually back to the Command Window when the program terminates. The error record is made available to any calling function by means of the catch function, and to the Command Window by means of the MException.last function.

Unlike throwAsCaller and rethrow, the throw function also sets the stack field of the errRecord to the location from which throw was called.

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.

Examples

Example 1

This example tests the output of M-file evaluate_plots and throws an exception if it is not acceptable:

[minval, maxval] = evaluate_plots(p24, p28, p41);
if minval < lower_bound || maxval > upper_bound
    errRecord = MException('VerifyOutput:OutOfBounds', ...
       'Results are outside the allowable limits');
    throw(errRecord);
end

Example 2

This example attempts to open a file in a directory that is not on the MATLAB path. It uses a nested try-catch block to give the user the opportunity to extend the path. If the file still cannot be found, the program uses throw to issue an exception with the first error appended to the second:

function data = read_it(filename);
try
   fid = fopen(filename, 'r');
   data = fread(fid);
catch errRecord1
   if strcmp(errRecord1.identifier, 'MATLAB:FileIO:InvalidFid')
      msg = sprintf('\n%s%s%s', 'Cannot open file ', filename, ...
         '. Try another location?  ');
      reply = input(msg, 's')
      if reply(1) == 'y'
          newdir = input('Enter directory name:  ', 's');
      else
          throw(errRecord1);
      end
      addpath(newdir);
      try
         fid = fopen(filename, 'r');
         data = fread(fid);
      catch errRecord2
         errRecord3 = addCause(errRecord2, errRecord1)
         throw(errRecord3);
      end
      rmpath(newdir);
   end
end
fclose(fid);

If you run this function in a try-catch block at the command line, you can look at the error record by assigning it to a variable (errRecord) with the catch command.

try
   d = read_it('anytextfile.txt');
catch errRecord
end

errRecord
errRecord =
	MException object with properties:

    identifier: 'MATLAB:FileIO:InvalidFid'
       message: 'Invalid file identifier.  Use fopen to generate a valid file identifier.'
         stack: [1x1 struct]
         cause: {[1x1 MException]}

  Cannot open file anytextfile.txt. Try another location?y
Enter directory name:  xxxxxxx
Warning: Name is nonexistent or not a directory: xxxxxxx.
> In path at 110
  In addpath at 89