The ON_IOERROR procedure specifies a statement to be jumped to if an I/O error occurs in the current procedure. Normally, when an I/O error occurs, an error message is printed and program execution is stopped. If ON_IOERROR is called and an I/O related error later occurs in the same procedure activation, control is transferred to the designated statement with the error code stored in the system variable !ERROR_STATE. The text of the error message is contained in !ERROR_STATE.MSG.

The effect of ON_IOERROR can be canceled by using the label “NULL” in the call.

Note: Note that 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.

Examples

The following code segment reads an integer from the keyboard. If an invalid number is entered, the program re-prompts.

i = 0 ; Number to read:
 
valid = 0 ; Valid flag
 
WHILE valid EQ 0 DO BEGIN
   ON_IOERROR, bad_num
   READ, 'Enter Number: ', i
   ;If we get here, i is good.
   VALID = 1
bad_num: IF ~ valid THEN $
         PRINT, 'You entered an invalid number.'
ENDWHILE
END

When writing procedures and functions that are to be used by others, it is good practice to anticipate and handle errors caused by the user. For example, the following procedure segment, which opens a file specified by the user, handles the case of a nonexistent file or read error.

; Define a function to read, and return a 100-element, 
; floating-point array.
FUNCTION READ_DATA, FILE_NAME
 
; Declare error label.
ON_IOERROR, BAD
 
; Use the GET_LUN keyword to allocate a logical file unit.
OPENR, UNIT, FILE NAME, /GET_LUN
 
A = FLTARR(100)     ;Define data array.
 
READU, UNIT, A      ;Read the data array.
 
; Clean up and return.
GOTO, DONE
 
; Exception label. Print the error message.
BAD:  PRINT, !ERROR_STATE.MSG
 
; Close and free the input/output unit.
DONE: FREE_LUN, UNIT
 
; Return the result. This will be undefined if an error occurred.
RETURN, A
 
END

The important things to note in this example are that the FREE_LUN procedure is always called, even in the event of an error, and that this procedure always returns to its caller. It returns an undefined value if an error occurs, causing its caller to encounter the error.

Syntax

ON_IOERROR, Label

Arguments

Label

Statement to jump to when I/O error is encountered.

Keywords

None.

Version History

Original

Introduced

See Also

CATCH, MESSAGE