Quantcast

Documentation Center

  • Trial Software
  • Product Updates

throw (MException)

Issue exception and terminate function

Syntax

throw(exception)

Description

throw(exception) issues an exception based on the information contained in exception. The exception terminates the currently running function and returns control to its caller. The exception argument is scalar object of the MException class that contains information on the cause of the error and where it occurred. The throw function passes exception back to the caller of the currently running function. and eventually back to the Command Window when the program terminates. The exception is made available to any calling function by means of the try, 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 exception to the location from which throw was called.

Examples

Example 1

This example tests the output of function 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
    exception = MException('VerifyOutput:OutOfBounds', ...
       'Results are outside the allowable limits');
    throw(exception);
end

Example 2

This example attempts to open a file in a folder 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 issues an exception with the first error appended to the second using addCause:

function data = read_it(filename);
try
   % Attempt to open and read from a file.
   fid = fopen(filename, 'r');
   data = fread(fid);
catch exception1
   % If the error was caused by an invalid file ID, try 
   % reading from another location.
   if strcmp(exception1.identifier, 'MATLAB:FileIO:InvalidFid')
      msg = sprintf( ...
         '\nCannot open file %s. Try another location?  ', ...
         filename);
      reply = input(msg, 's')
      if reply(1) == 'y'
          newFolder = input('Enter folder name:  ', 's');
      else
          throw(exception1);
      end
      oldpath = addpath(newFolder);
      try
         fid = fopen(filename, 'r');
         data = fread(fid);
      catch exception2
         exception3 = addCause(exception2, exception1)
         path(oldpath);
         throw(exception3);
      end
      path(oldpath);
   end
end
fclose(fid);
try
   d = read_it('anytextfile.txt');
catch exception
end

exception
exception =
	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 folder name:  xxxxxxx
Warning: Name is nonexistent or not a directory: xxxxxxx.
> In path at 110
  In addpath at 89

More About

expand all

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

See Also

| | | | | | | |

Was this topic helpful?