Reporting and handling errors

FIO/RIO routines all report errors if they return bad status values, so programs that do all I/O through calls to FIO/RIO do not have to worry about this. However, some programs use direct FORTRAN statements to perform I/O and may still need to report errors. Two routines are provided to assist with this; FIO_SERR and FIO_REP. FIO_SERR is the simpler of the two. It takes an IOSTAT value as its first argument, returns a corresponding FIO error value in its status argument and reports an error. The error report is of the form:

FIO_SERR: IOSTAT error $=$ Unit not connected

This is fine if all you want to do is translate the IOSTAT value, but the error report does not contain any contextual information such as the unit that was not connected nor the file that it should have been connected to. For a fuller report, the routine FIO_REP is provided. This takes as input arguments the unit number, the file name, the IOSTAT value and a message to be printed. FIO_REP sets three message tokens, FNAME, UNIT and IOSTAT and then reports the message that it was given. This message can contain references to the message tokens to provide a more meaningful error message. For example:

      OPEN( UNIT=UNUM, FILE=FILNAM, STATUS='OLD', IOSTAT=ISTAT )
      CALL FIO_REP( UNUM, FILNAM, ISTAT,
     :  'Error opening file ^FNAME. Status = ^IOSTAT', STATUS )

In this case, the error report contains the fact that this error has been generated when trying to open a file. To save having to generate an error message for every call to FIO_REP, it is possible to give a blank message, which is equivalent to

      'Error with file ^FNAME on unit number ^UNIT; IOSTAT = ^IOSTAT'

For a given value of IOSTAT, the value of status that is returned by FIO_REP is the same as that returned by FIO_SERR.