1.4.44 set_io_err_handler, get_io_err_handler: Set and Get I/O Error Handler (Sun Studio 12: Fortran Library Reference)

Sun Studio 12: Fortran Library Reference

1.4.44 `set_io_err_handler`, `get_io_err_handler`: Set and Get I/O Error Handler

set_io_err_handler() declares a user-defined routine to be called whenever errors are detected on a specified input logical unit.

get_io_err_handler() returns the address of the currently declared error handling routine.

These routines are module subroutines and can only be accessed when USE SUN_IO_HANDLERS appears in the calling routine.

`USE SUN_IO_HANDLERS` `call set_io_err_handler(``iu, subr_name, istat``)`
`iu`	*`INTEGER8`**	Input	Logical unit number
`subr_name`	`EXTERNAL`	Input	Name of user-supplied error handler subroutine.
`istat`	*`INTEGER4`**	Output	Return status.

`USE SUN_IO_HANDLERS` `call get_io_err_handler(``iu, subr_pointer, istat``)`
`iu`	*`INTEGER8`**	Input	Logical unit number
`subr_pointer`	`POINTER`	Output	Address of currenly declared handler routine.
`istat`	*`INTEGER4`**	Output	Return status.

SET_IO_ERR_HANDLER sets the user-supplied subroutine subr_name to be used as the I/O error handler for the logical unit iu when an input error occurs. iu has to be a connected Fortran logical unit for a formatted file. istat will be set to a non-zero value if there is an error, otherwise it is set to zero.

For example, if SET_IO_ERR_HANDLER is called before the logical unit iu has been opened, istat will be set to 1001 ("Illegal Unit"). If subr_name is NULL user error-handling is turned off and the program reverts to default Fortran error handling.

Use GET_IO_ERR_HANDLER to get the address of the function currently being used as the error handler for this logical unit. For example, call GET_IO_ERR_HANDLER to save the current I/O before switching to another handler routine. The error handler can be restored with the saved value later.

subr_name is the name of the user-supplied routine to handle the I/O error on logical unit iu. The runtime I/O library passes all relevant information to subr_name, enabling this routine to diagnose the problem and possibly fix the error before continuing.

The interface to the user-supplied error handler routine is as follows:

`SUBROUTINE SUB_NAME(UNIT, SRC_FILE, SRC_LINE, DATA_FILE, FILE_POS,` `CURR_BUFF, CURR_ITEM, CORR_CHAR, CORR_ACTION )` `INTENT (IN) UNIT, SRC_FILE, SRC_LINE, DATA_FILE` `INTENT (IN) FILE_POS, CURR_BUFF, CURR_ITEM` `INTENT (OUT) CORR_CHAR, CORR_ACTION`
`UNIT`	*`INTEGER8`**	Input	Logical unit number of the input file reporting an error.
`SRC_FILE`	*`CHARACTER()`*	Input	Name of the Fortran source file originating the input operation.
`SRC_LINE`	*`INTEGER8`**	Input	Line number in `SRC_FILE` of the input operation with an error.
`DATA_FILE`	*`CHARACTER()`*	Input	Name of the data file being read. Avaliable only if the file is an opened external file. If the name is not available, (logical unit 5 for example), `DATA_FILE` is set to a zero-length character data item.
`FILE_POS`	*`INTEGER8`**	Input	Current position in the input file, in bytes. Defined only if the name of the `DATA_FILE` is known.
`CURR_BUFF`	*`CHARACTER()`*	Input	Character string containing the remaining data from the input record. The bad input character is the first character in the string.
`CURR_ITEM`	*`INTEGER8`**	Input	The number of input items in the record that have been read, including the current one, when the error is detected. For example:`READ(12,10)L,(ARR(I),I=1,L)` IF the value of `CURR_ITEM` is 15 in this case, it means the error happens while reading the 14th element of `ARR`, with `L` being the first item and `ARR(1)` being the second, and so on.
`CORR_CHAR`	`CHARACTER`	Output	The user-supplied corrected character to be returned by the handler. This value is used only when `CORR_ACTION` is non-zero. If `CORR_CHAR` is an invalid character, the handler will be called again until a valid character is returned. This could cause an infinite loop, a situation the user is required to protect against.
`CORR_ACTION`	`INTEGER`	Output	Specifies the corrective action to be taken by the I/O library. With a zero value no special action is taken and the library reverts to its default error processing. A value of `1` returns `CORR_CHAR` to the I/O error processing routine.

1.4.44.1 Limitations

The I/O handler can only replace once character with another character. It cannot replace one character with more than one character.

The error recovery algorithm can only fix a bad character it currently reads, not a bad character which has already been interpreted as a valid character in a different context. For example,in a list-directed read, if the input is "1.234509.8765" when the correct input should be "1.2345 9.8765" then the I/O library will run into an error at the second period because it is not a valid number. But, by that time, it is not possible to go back and change the ’0’ into a blank.

Currently, this error-handling capability does not work for namelist-directed input. When doing namelist-directed input, the specified I/O error handler will not be invoked when an error occurs.

I/O error handlers can only be set for external files, not internal files, because there are no logical units associated with internal files.

The I/O error handler is called only for syntactic errors, not system errors or semantic errors(such as an overflowed input value).

It is possible to have an infinite loop if the user-supplied I/O error handler keeps providing a bad character to the I/O library, causing it to call the user-supplied I/O error handler over and over again. If an error keeps occuring at the same file position then the error handler should terminate itself. One way to do this is to take the default error path by setting CORR_ACTION to 0. Then the I/O library will continue with the normal error handling.