MATLAB Function Reference

addCause (MException) - Append `MException` objects

Syntax

new_ME = addCause(base_ME, cause_ME) base_ME = addCause(base_ME, cause_ME)

Description

new_ME = addCause(base_ME, cause_ME) creates a new MException object new_ME from two existing MException objects, base_ME and cause_ME. addCause constructs new_ME by making a copy of the base_ME object and appending cause_ME to the cause property of that object.

If other errors have contributed to the exception currently being thrown, you can add the MException objects that represent these errors to the cause field of the current MException to provide further information for diagnosing the error at hand. All objects of the MException class have a property called cause which is defined as a vector of additional MException objects that can be added onto a base object of that class.

base_ME = addCause(base_ME, cause_ME) modifies existing MException object base_ME by appending cause_ME to the cause property of that object.

Examples

Example 1

This example attempts to assign data from array D. If D does not exist, the code attempts to recreate D by loading it from a MAT-file. The code constructs a new MException object new_ME to store the causes of the first two errors, cause1_ME and cause2_ME:

try
    x = D(1:25);
catch cause1_ME
    try
        filename = 'test204';
        testdata = load(filename);
        x = testdata.D(1:25)
    catch cause2_ME
        base_ME = MException('MATLAB:LoadErr', ...
               'Unable to load from file %s', filename);
        new_ME = addCause(base_ME, cause1_ME);
        new_ME = addCause(new_ME, cause2_ME);
        throw(new_ME);
    end
end

When you run the code, the MATLAB^® software displays the following message:

??? Unable to load from file test204

There are two exceptions in the cause field of new_ME:

new_ME.cause
ans = 
    [1x1 MException]
    [1x1 MException]

Examine the cause field of new_ME to see the related errors:

new_ME.cause{:}
ans =

	MException object with properties:

    identifier: 'MATLAB:UndefinedFunction'
       message: 'Undefined function or method 'D' for input 
            arguments of type 'double'.'
         stack: [0x1 struct]
         cause: {}
ans =

	MException object with properties:

    identifier: 'MATLAB:load:couldNotReadFile'
       message: 'Unable to read file test204: No such file 
            or directory.'
         stack: [0x1 struct]
         cause: {}

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 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
   fid = fopen(filename, 'r');
   data = fread(fid);
catch ME1
   if strcmp(ME1.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(ME1);
      end
      addpath(newdir);
      try
         fid = fopen(filename, 'r');
         data = fread(fid);
      catch ME2
         ME3 = addCause(ME2, ME1)
         throw(ME3);
      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 MException object by assigning it to a variable (e) with the catch command.

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

e
e =
	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