Controlling Errors Using CATCH

The CATCH procedure provides a generalized mechanism for handling any type of errors and exceptions within IDL. Calling CATCH establishes an error handler for the current procedure that intercepts all errors that can be handled by IDL, with the exception of non-fatal warnings such as math errors (e.g., floating-point underflow). The CATCH mechanism is similar to C's setjmp/longjmp facilities or C++'s catch/throw facilities.

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 and is also stored in !ERROR_STATE.CODE. 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.

For more information, see CATCH and !ERROR_STATE.

Interaction of CATCH, ON_ERROR, and ON_IOERROR

Error handlers established by calls to CATCH supersede calls to ON_ERROR. However, calls to ON_IOERROR made in the procedure that causes an I/O error supersede any error handling mechanisms created with CATCH and the program branches to the label specified by ON_IOERROR.

The following figure is a flow chart of how errors are handled in IDL.

Canceling an Error Handler

Call CATCH with the CANCEL keyword set to cancel a procedure's error handler. This cancellation does not effect other error handlers that may be established in other active procedures.

Generating an Exception

To generate an exception and cause control to return to the error handler, use the MESSAGE procedure. Calling MESSAGE generates an exception that sets the !ERROR_STATE system variable. !ERROR_STATE.MSG is set to the string used as an argument to MESSAGE. See Error Signaling.

Example Using CATCH

The following procedure illustrates the use of CATCH:

PRO ABC 
 
;Define variable A. 
A = FLTARR(10) 
 
;Establish error handler. When errors occur, the index of the error  
;is returned in the variable Error_status. Initially, this  
;argument is set to zero. 
CATCH, Error_status 
 
;This statement begins the error handler. 
IF Error_status NE 0 THEN BEGIN 
 
   PRINT, 'Error index: ', Error_status 
   PRINT, 'Error message:', !ERR_STRING 
 
   ;Handle the error by extending A. 
   A=FLTARR(12) 
   CATCH, /CANCEL 
ENDIF 
 
A[11]=12     ;Cause an error. 
 
;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 ABC procedure causes IDL to produce the following output and control returns to the interactive prompt:

Error index:         -101 
Error message: 
Attempt to subscript A with <INT (      11)> is out of range. 
A               FLOAT     = Array(12)