One approach is simply to use the ADAM File Input/Output (FIO) routines to get a free logical unit number and then do normal Fortran I/O. This is the method adopted here. The alternative strategy of reading and writing character buffers (also using FIO routines) is described in APN/9.
A free logical unit number is obtained by associating a file with a file descriptor and then finding which logical unit number has been allocated to that file descriptor. The call to associate a file with a file descriptor (FD) has the form:
where the arguments are: FILE, the ADAM parameter used to retrieve the filename; ACCESS, the access mode which should be one of ’READ’, ’WRITE’, ’UPDATE’ or ’APPEND’; FORM, the file format, which should be one of ’FORTRAN’, ’LIST’, ’NONE’ or ’UNFORMATTED’; RECZ, maximum record size in bytes, or zero if the Fortran default is required; FD, the file descriptor, and the usual STATUS.
The logical unit number (UNIT) allocated to the file is then obtained with the call below and can be used to perform normal Fortran I/O.
ADAM_EXAMPLES:RDDATA.FOR reads various data from a text file and finds the mean of a set of numbers. The file format it expects is simple – a title on the first line, the number of data elements on the second, followed by the data elements in free format.
The portion of RDDATA.FOR which reads the text file is reproduced below.
Note that after each read the variable IOSTAT is checked and if a non-zero value is found the program control moves to the statement labelled 998. Any ADAM program which uses READ or WRITE in this way must check for I/O errors, i.e. IOSTAT becoming non-zero. If an I/O error occurs, a program may be able to handle it – otherwise it should make an error report and abort. An error report is made using the routine ERR_FIOER which puts the message appropriate to the value of IOSTAT into a message token. The token is then reported using ERR_REP as shown in the further extract from RDDATA.FOR which follows.
After opening a file with FIO_ASSOC it is necessary to cancel the ADAM parameter used for the filename, and deactivate the FIO package when interaction with the file has ceased, as shown below.
The FIO routines must be explicitly included during linking thus:
The program RDDATA can be tested with the data file DATA.DAT in ADAM_EXAMPLES.
Explicit error checking.
The program RDDATA.FOR gives up if it encounters any errors when trying to read the input file.
However a program may wish to cope with various possibilities. This can be done by explicitly
testing STATUS against the FIO error codes. These are made available to a program by
including the file with logical name FIO_ERR. For example, if FIO_ASSOC tries to open a
non-existent file for ’READ’ an error will result, and STATUS will be set to the symbolic constant
FIO_NOTFD. (A complete list of the FIO error codes is contained in APN/9 – or you can $ TYPE
FIO_ERR.)
When a particular error condition is trapped in this way, the program should call the routine ERR_FLUSH as shown below. This has two effects; firstly it resets STATUS to SAI__OK, and secondly it forces the immediate output of any pending error messages. (If the error message is not flushed immediately, the user may be bewildered by error messages on program termination which refer to error conditions which have been corrected.)
However the errors may happen not during FIO calls but during Fortran READ statements which set IOSTAT on failure. The IOSTAT returned by these statements can be converted to an FIO STATUS value with the routine FIO_SERR as shown in the example below.