NAME
set_io_err_handler, get_io_err_handler - set/get I/O Error
Handler
SYNOPSIS
USE SUN_IO_HANDLERS
SUBROUTINE SET_IO_ERR_HANDLER(IU, SUB_NAME, ISTAT)
INTEGER(8) IU
EXTERNAL SUB_NAME
INTEGER(4) ISTAT
SUBROUTINE GET_IO_ERR_HANDLER(IU, SUB_PTR, ISTAT)
INTEGER(8) IU
EXTERNAL SUB_NAME
POINTER (SUB_PTR, SUB_NAME)
INTEGER(4) ISTAT
DESCRIPTION
SET_IO_ERR_HANDLER sets the user-supplied subroutine
SUB_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 SUB_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.
SET_IO_ERR_HANDLER and GET_IO_ERR_HANDLER are module subrou-
tines and can only be accessed when USE SUN_IO_HANDLERS
appears in the calling routine.
SUB_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 SUB_NAME, enabling this
routine to diagnose the problem and possibly fix the error
before continuing.
The interface to the I/O handler is as follows:
SUBROUTINE SUB_NAME(UNIT, SRC_FILE, SRC_LINE,
X DATA_FILE, FILE_POS, CURR_BUFF,
X CURR_ITEM, CORRECT,CHAR, CORR_ACTION )
INTENT (IN) UNIT, SRC_FILE, SRC_LINE, DATA_FILE
INTENT (IN) FILE_POS, CURR_BUFF, CURR_ITEM
INTENT (OUT) CORRECT_CHAR, CORR_ACTION
INTEGER(8) UNIT Logical unit of the input file where the
error occurred.
CHARACTER*(*) SRC_FILE
Name of the Fortran source file where
the input operation originated.
INTEGER(8) SRC_LINE Line number in SRC_FILE of the input
operation.
CHARACTER*(*) DATA_FILE
Name of the data file being read. This
is only available if the file is an
external file which has been opened. If
the file name is not available, (for
example, logical unit 5), DATA_FILE is
set to a zero length character data
item.
INTEGER(8) FILEPOS Current position in the input file, in
bytes. This is defined only if the name
of the input file DATA_FILE is known.
CHARACTER*(*) CURR_BUFF
Character string containing the remain-
ing data in the input record with the
bad input character as the first charac-
ter in the string.
INTEGER(8) CURR_ITEM
The number of the input items in the
record that have been read, including
the current one, when the error happens.
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.
CHARACTER CORRECT_CHAR
The user-supplied corrected character to
be returned by the handler. This param-
eter is used only when the CORR_ACTION
parameter is set to a non-zero value.
If CORRECT_CHAR is set to an invalid
character, the handler routine will be
called again until a valid character is
returned. This could potentially cause
an infinite loop if the handler never
provides a valid character. The user is
required to detect and protect against
this happening.
INTEGER CORR_ACTION Specifies the corrective action to be
taken by the I/O runtime library, and
can have two possible values:
0 Do nothing. Use default error pro-
cessing.
1 Continue using the CORRECT_CHAR
returned by the user error handler rou-
tine.
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 associ-
ated 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 ter-
minate 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.
FILES
libfui.so
sun_io_handlers.mod