SET_IO_ERR_HANDLER(3F)SET_IO_ERR_HANDLER(3F)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 for‐
matted 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 subroutines 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 remaining data in
the input record with the bad input character as
the first character 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 ele‐
ment 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 parameter 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 val‐
ues:
0 Do nothing. Use default error processing.
1 Continue using the CORRECT_CHAR returned by the
user error handler routine.
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 con‐
tinue with the normal error handling.
FILES
libfui.so
sun_io_handlers.mod
2003/03/11 SET_IO_ERR_HANDLER(3F)
