12.1.2 Catching Errors

When an error occurs, it can be detected and handled using the try statement as described in The try Statement. As an example, the following piece of code counts the number of errors that occurs during a for loop.

number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    number_of_errors++;
  end_try_catch
endfor

The above example treats all errors the same. In many situations it can however be necessary to discriminate between errors, and take different actions depending on the error. The lasterror function returns a structure containing information about the last error that occurred. As an example, the code above could be changed to count the number of errors related to the ‘*’ operator.

number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    msg = lasterror.message;
    if (strfind (msg, "operator *"))
      number_of_errors++;
    endif
  end_try_catch
endfor

Alternatively, the output of the lasterror function can be found in a variable indicated immediately after the catch keyword, as in the example below showing how to redirect an error as a warning:

try
  …
catch err
  warning(err.identifier, err.message);
  …
end_try_catch

Built-in Function: lasterr = lasterror ()

Built-in Function: lasterror (err)

Built-in Function: lasterror ("reset")

Query or set the last error message structure.

When called without arguments, return a structure containing the last error message and other information related to this error. The elements of the structure are:

message

The text of the last error message

identifier

The message identifier of this error message

stack

A structure containing information on where the message occurred. This may be an empty structure if the information cannot be obtained. The fields of the structure are:

file

The name of the file where the error occurred

name

The name of function in which the error occurred

line

The line number at which the error occurred

column

An optional field with the column number at which the error occurred

The last error structure may be set by passing a scalar structure, err, as input. Any fields of err that match those above are set while any unspecified fields are initialized with default values.

If lasterror is called with the argument "reset", all fields are set to their default values.

See also: lasterr, error, lastwarn.

Built-in Function: [msg, msgid] = lasterr ()

Built-in Function: lasterr (msg)

Built-in Function: lasterr (msg, msgid)

Query or set the last error message.

When called without input arguments, return the last error message and message identifier.

With one argument, set the last error message to msg.

With two arguments, also set the last message identifier.

See also: lasterror, error, lastwarn.

It is also possible to assign an identification string to an error. If an error has such an ID the user can catch this error as will be shown in the next example. To assign an ID to an error, simply call error with two string arguments, where the first is the identification string, and the second is the actual error. Note that error IDs are in the format "NAMESPACE:ERROR-NAME". The namespace "Octave" is used for Octave’s own errors. Any other string is available as a namespace for user’s own errors.

The next example counts indexing errors. The errors are caught using the field identifier of the structure returned by the function lasterror.

number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    id = lasterror.identifier;
    if (strcmp (id, "Octave:invalid-indexing"))
      number_of_errors++;
    endif
  end_try_catch
endfor

The functions distributed with Octave can issue one of the following errors.

Octave:invalid-context

Indicates the error was generated by an operation that cannot be executed in the scope from which it was called. For example, the function print_usage () when called from the Octave prompt raises this error.

Octave:invalid-input-arg

Indicates that a function was called with invalid input arguments.

Octave:invalid-fun-call

Indicates that a function was called in an incorrect way, e.g., wrong number of input arguments.

Octave:invalid-indexing

Indicates that a data-type was indexed incorrectly, e.g., real-value index for arrays, nonexistent field of a structure.

Octave:bad-alloc

Indicates that memory couldn’t be allocated.

Octave:undefined-function

Indicates a call to a function that is not defined. The function may exist but Octave is unable to find it in the search path.

When an error has been handled it is possible to raise it again. This can be useful when an error needs to be detected, but the program should still abort. This is possible using the rethrow function. The previous example can now be changed to count the number of errors related to the ‘*’ operator, but still abort if another kind of error occurs.

number_of_errors = 0;
for n = 1:100
  try
    …
  catch
    msg = lasterror.message;
    if (strfind (msg, "operator *"))
      number_of_errors++;
    else
      rethrow (lasterror);
    endif
  end_try_catch
endfor

Built-in Function: rethrow (err)

Reissue a previous error as defined by err.

err is a structure that must contain at least the "message" and "identifier" fields. err can also contain a field "stack" that gives information on the assumed location of the error. Typically err is returned from lasterror.

See also: lasterror, lasterr, error.

Built-in Function: err = errno ()

Built-in Function: err = errno (val)

Built-in Function: err = errno (name)

Return the current value of the system-dependent variable errno, set its value to val and return the previous value, or return the named error code given name as a character string, or -1 if name is not found.

See also: errno_list.

Built-in Function: errno_list ()

Return a structure containing the system-dependent errno values.

See also: errno.