File Handling and the Use of Input/Output Units

The assignment of FORTRAN units is handled by CCSL. Interactive terminal input and output units, the line-printer and the plotter are assigned to the units named ITI, ITO, LPT, and IPLO respectively, and are given values appropriate to the system by INITIL. They are held in the COMMON /IOUNIT/.

Assignment of files to FORTRAN units is done using FUNCTION NOPFIL to open a file and SUBROUTINE CLOFIL to close it.

Fifteen units are required by CCSL and managed by it; if not forbidden by the particular operating system they are units 20-34. The user of standard programs should find that his input and output are taken care of by calls of NOPFIL already in the system. A user writing or modifying a main program will need to know more details, in order to deal with his own files.

Note The length of the leaf part of file-names in CCSL is restricted to 10 characters: a main part of up to 6 characters optionally followed by a period (.) and and extension of up to 3 characters.

Opening a File to be Read

To open a file to be read by a program in the simplest possible way the code:
      LUN=NOPFIL(1)
should be obeyed. The system will respond with the message:
Give name of input file
to which the user should respond with the file name. Under VMS on a VAX, this can include the full path name and an extension if required but it may be simply the letters (up to 6) of the file name, in which case the extension .DAT is added. LUN will be set to the value of the Fortran unit allocated by the system. The value of LUN should not normally concern the user; he reads the file by code such as:
      READ (LUN,42) FRED
but if he needs for some reason to open a specifically numbered file he may use SUBROUTINE OPNFIL, thus:

 

      LUNIT=14
      CALL OPNFIL(LUNIT,1)

NOPFIL can interpret relative directory specifications in UNIX (eg ../) or VMS (eg [-.]) and absolute file or directory names given as environment variables ($$\cdots$) in UNIX or as logical assignments ($\cdots:$) in VMS.

Opening an Output File

To open for writing a file which is not destined for a line printer, the code:
      LUN=NOPFIL(2)
should be obeyed. The file is then written using, for example,
      WRITE (LUN,43) JOAN
To open for writing a file which is destined for a line printer, a VMS user may write:
      LUN=NOPFIL(2002)
When the file is opened this will use:

      CARRIAGECONTROL='FORTRAN'

Fortran carriage control is not recognised by UNIX.

Options Available when Opening Files

Other options can be obtained by obeying:
      LUN=NOPFIL(MODE)
where MODE indicates the type of file to be opened and how to obtain the file-name.

MODE may have up to 5 digits.The least significant, MODE1, indicates the file-type; the second digit, MODE2, shows how to obtain the file name; the third, MODE3, deals with default extensions; the fourth, MODE4, selects formatted or unformatted files and the fifth, MODE5, selects sequential or direct access files.

Character data such as a message or the file name are transmitted to NOPFIL via the COMMON /SCRACH/ which can contain 200 characters, and within NOPFIL is divided into MESSAG and NAMFIL of 100 characters each. The maximum length of both these strings is configurable when building the system.

The significance of MODE is as follows:

MODE1

= 1 for a read file
= 2 for a write file status new
= 3 for a write file status undefined (UNKNOWN)
= 4 for a write file to be modified (APPEND for sequential files)
= 5 for a scratch file.

MODE2

= 0 give the standard messages for read or write files; machine specific information like the path name and file extension may be included in the user's response.
= 1 use the message in MESSAG; otherwise as MODE2=0
= 2 use the file-name in MESSAG. Report that the file is opened.
= 3 as 2 but do not give file-opened message.
= 4 as 0 but do not give file-opened message.

MODE3

= 0 use the system default for path and default extension .DAT
= 1 use defaults for extension, disc and path-name found in characters 1-4, 5-10, and 11-30 respectively of NAMFIL (up to 40 characters, in common SCRACH after item MESSAG). If the disc or path-name is absent, default as system.
= 2 use the file-name exactly as given in response to the request.

MODE4

= 0 for a formatted file, not expecting FORTRAN carriage control characters (and therefore not a line-printer file)
= 1 for an unformatted file
= 2 for a formatted file with FORTRAN carriage control characters, such as would be sent to a line printer.

MODE5

= 0 for a sequential file
= 1 for a direct access file
= 2 for RECORDTYPE='FIXED' (needed for ``GENIE" files).

Exit from NOPFIL

After a successful exit from the call:
      LUN=NOPFIL(MODE)
LUN is set to a small positive number, which is the unit number allocated to the opened file by NOPFIL. LUN is zero if no response is obtained (i.e. the RETURN key is pressed) when a file name is reqested. LUN is negative if the file could not be opened, although NOPFIL allows the user to try again after typing errors or other blunders from which it has a sensible way to recover.

The short names (10 characters) are stored in COMMON FILNAM and may be obtained by declaring the COMMON and obeying:

         CHARACTER*10 NAME,FILNOM
         NAME=FILNOM(LUN)

Closing Files

When input or output operations are terminated on a particular unit it should be returned to the system by obeying: CALL CLOFIL(LUN)

Examples of the Use of NOPFIL

The main program for a Fourier calculation is given below:

C MINIMAL FOURIER PROGRAM.
      CALL PREFIN
      LUNI= NOPFIL(1)
      CALL RECIP
      CALL OPSYM(2)
      CALL SETFOU
   . . . map-producing code - see various main program examples
      STOP
      END

It contains one explicit call to NOPFIL; however the call to PREFIN provokes several other calls to NOPFIL, one of which sends the message:
Give name of Crystal Data File :
to which the user must reply by typing the appropriate file name. Another call to NOPFIL does not result in a message as it just opens an internal scratch file. (If the Libary has been generated for RAL rather than ILL, an early call of NOPFIL asks for the name of the printer output file.)

The call to NOPFIL in the main program sends the message:
Give name of input file :
and the user should type the name of the file containing his reflection data.

A less trivial example is given in the fragments from the main program ABSMSF reproduced below. ABSMSF is a program which reads a file containing reflection intensities in the special format produced by the sorting programs ARRNGE and ARRINC. The file name has the extension .ARR. It then makes an absorption correction if required and calculates the average of the corrected intensity over all equivalent reflections. Finally it writes an output file containing the mean structure factors and their standard deviations.

      PROGRAM ABSMSF
            .
            .
      DIMENSION LUN(2)
      CHARACTER*56 HEDING
      LOGICAL INC
            .
            .
      COMMON /IOUNIT/LPT,ITI,ITO,IPLO,LUNI,IOUT
      COMMON /REFS/K(3,2),LL(48,2),R(500,2),SCALE(2),INC,II,FF(3,2)
      COMMON/SCRACH/MESSAG,NAMFIL
      CHARACTER *40 MESSAG
      CHARACTER *60 NAMFIL
      DATA HEADNG/'(5X,''h'',4X,''k'',4X,''l'',10X,''Fobs'',7X,
     1''DFobs''/)'/
            .
            .
      IF (INC.EQ.0) GO TO 2
C ALTER THE FORMAT FOR FLOATING POINT OUTPUT:
      HEADNG(2:2)='6'
      HEADNG(9:9)='7'
      HEADNG(16:16)='7'
      HEADNG(23:24)='12'
            .
            .
      NAMFIL='.ARR'
      LUN(1)=NOPFIL(101)
      NAMFIL='.SF '
      LOUT=NOPFIL(102)
            .
            .
      STOP
      END

The first call to NOPFIL asks the user for the name of the input file and uses the default .ARR if no ``." is found in the reply. The second call creates a new file for output with the same name as the input file but with extension .SF (structure factors).