Learn more about MATLAB

addCause (MException) - Record additional causes of exception

Syntax

errRecord = addCause(errRecord, causeRecord)

Description

errRecord = addCause(errRecord, causeRecord) adds information to an existing exception record errRecord to help determine the cause of the exception. The added information is in the form of a second error record causeRecord. Both errRecord and causeRecord are objects of the MException class.

The error record data structure has a field called cause in which you can store a series of additional error records, each saving information on what caused the initial error. (See the figure in the documentation for The MException Class.) When your program calls addCause, MATLAB appends a new error record causeRecord to this field in the base error record errRecord. When your error handling code catches the error in a try-catch statement, execution of the catch part of this statement makes the base error record, along with all of the appended cause records, available to help diagnose the error.

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_errRec to store the causes of the first two errors, causeRec1 and causeRec2:

try
    x = D(1:25);
catch causeRec1
    try
        filename = 'test204';
        testdata = load(filename);
        x = testdata.D(1:25)
    catch causeRec2
        base_errRec = MException('MATLAB:LoadErr', ...
               'Unable to load from file %s', filename);
        new_errRec = addCause(base_errRec, causeRec1);
        new_errRec = addCause(new_errRec, causeRec2);
        throw(new_errRec);
    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_errRec:

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

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

new_errRec.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 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
   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 MException object by assigning it to a variable (e) 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