CATCH

The CATCH procedure provides a generalized mechanism for the handling of exceptions and errors within IDL. Calling CATCH establishes an error handler for the current procedure that intercepts all errors that can be handled by IDL, excluding non-fatal warnings such as math errors (e.g., floating-point underflow).

When an error occurs, each active procedure, beginning with the offending procedure and proceeding up the call stack to the main program level, is examined for an error handler (established by a call to CATCH). If an error handler is found, control resumes at the statement after the call to CATCH. The index of the error is returned in the argument to CATCH. The !ERROR_STATE system variable is also set. The associated error message is stored in !ERROR_STATE.MSG. If no error handlers are found, program execution stops, an error message is issued, and control reverts to the interactive mode. A call to ON_IOERROR in the procedure that causes an I/O error supersedes CATCH, and takes the branch to the label defined by ON_IOERROR.

This mechanism is similar, but not identical to, the setjmp/longjmp facilities in C and the catch/throw facilities in C++.

Error handling is discussed in more detail in Controlling and Recovering from Errors.

Examples

The following procedure illustrates the use of CATCH:

PRO CATCH_EXAMPLE

   ; Define variable A:

   A = FLTARR(10)

   ; Establish error handler. When errors occur, the index of the

   ; error is returned in the variable Error_status:

   CATCH, Error_status

   ;This statement begins the error handler:

   IF Error_status NE 0 THEN BEGIN

      PRINT, 'Error index: ', Error_status

      PRINT, 'Error message: ', !ERROR_STATE.MSG

      ; Handle the error by extending A:

      A=FLTARR(12)

      CATCH, /CANCEL

   ENDIF

   ; Cause an error:

   A[11]=12

   ; Even though an error occurs in the line above, program

   ; execution continues to this point because the event handler

   ; extended the definition of A so that the statement can be

   ; re-executed.

   HELP, A

END

Running the CATCH_EXAMPLE procedure causes IDL to produce the following output and control returns to the interactive prompt:

Error index:         -144

Error message:

Attempt to subscript A with <INT (      11)> is out of range.

A               FLOAT     = Array[12]

Syntax

CATCH, [Variable] [, /CANCEL]

Arguments

Variable

A named variable in which the error index is returned. When an error handler is established by a call to CATCH, Variable is set to zero. If an error occurs, Variable is set to the error index, and control is transferred to the statement after the call to CATCH. The error index is also returned in the CODE field of the !ERROR_STATE system variable, i.e., !ERROR_STATE.CODE.

Keywords

CANCEL

Set this keyword to cancel the error handler for the current procedure. This cancellation does not affect other error handlers that may be established in other active procedures.

Note: If the CANCEL keyword is set, the Variable argument must not be present.

Version History

Pre 4.0

Introduced