intro_io

Date:: 10-20-2011

NAME

intro_io - Introduction to Fortran-callable I/O routines

IMPLEMENTATION

Cray Linux Environment (CLE)

DESCRIPTION

The I/O routines include the following:

Assign processing routines
File positioning routines
Auxiliary NAMELIST routines
Logical record I/O routines
Random-access file I/O routines
Miscellaneous I/O routines
Fortran I/O units

Routines

Assign processing routines provide a library interface to assign processing. See the assign(1) man page for details about assign processing.

The following routines are available for assign processing:

ASNCTL(3F): Controls functioning of ASSIGN, ASUNIT, ASNFILE, and ASNRM
ASSIGN(3F): Provides interface to assign processing from Fortran
ASUNIT(3F): Assigns attributes to units (documented on the assign(3f) man page)
ASNFILE(3F): Assigns attributes to files (documented on the assign(3f) man page)
ASNRM(3F): Removes all entries in the assign environment (documented on the assign(3f) man page)
ASNQFILE(3F): Returns attributes for a file
ASNQUNIT(3F): Returns attributes for a unit (documented on the asnqfile(3f) man page)

Auxiliary Namelist Routines

NAMELIST routines let you control input and output defaults. No arguments are returned. For a more complete description of the NAMELIST feature, see the Cray Fortran Reference Manual.

The following routines are used for auxiliary NAMELIST routines:

RNLCOMM(3F): Deletes or adds a trailing comment indicator (documented on the rnl(3f) man page)
RNLDELM(3F): Deletes or adds a delimiting character (documented on the rnl(3f) man page)
RNLFLAG(3F): Deletes or adds an echo character (documented on the rnl(3f) man page)
RNLREP(3F): Deletes or adds a replacement character (documented on the rnl(3f) man page)
RNLSEP(3F): Deletes or adds a separator character (documented on the rnl(3f) man page)
RNLECHO(3F): Specifies the output unit for error messages and echo lines
RNLSKIP(3F): Takes action when an undesired NAMELIST group is encountered
RNLTYPE(3F): Determines the action if a type mismatch occurs across the equal sign on an input record
WNLDELM(3F): Defines an ASCII NAMELIST delimiter (documented on the wnl(3f) man page)
WNLFLAG(3F): Indicates the first ASCII character of the first line (documented on the wnl(3f) man page)
WNLREP(3F): Defines an ASCII NAMELIST separator (documented on the wnl(3f) man page
WNLLINE(3F): Allows each NAMELIST variable to begin on a new line
WNLLONG(3F): Indicates output line length

Read Routines

Read routines transfer partial or full records of data from the external device to the user data area. Depending on the read request issued, the data is placed in the user data area either 1 character per word or in full words. In partial mode, the file maintains its position after the read is executed. In record mode, the file position is maintained after the end-of-record (EOR) that terminates the current record. Operation of these routines depends on the -F and -s options on the assign(1) command.

Write Routines

Write routines transfer partial or full records of data from the user data area to the external device. Depending on the write operation requested, data is either taken from the user data area 1 character per word and packed 8 characters per word or is transferred in full words. In partial mode, no end-of-record (EOR) is inserted in the external device in the word following the data that terminates the record. Operation of these routines depends on the -F and -s options on the assign(1) command.

NOTES

The Fortran implementation allows I/O units to be connected to files, and they serve as a means of referring to that file. This section describes the characteristics of those unit identifiers.

A Fortran unit identifier is one of the following:

An integer variable or expression with a 0 or positive value. Each integer unit identifier (i) is associated with the file fort.i, which may exist. For example, unit 10 is associated with the file fort.10 in the current working directory.
An asterisk, identifying a particular file that is connected for formatted, sequential access (allowed only on READ and WRITE statements). On READ statements, an asterisk refers to unit 100 (standard input). On WRITE statements, an asterisk refers to unit 101 (standard output).
A Hollerith (integer) variable consisting of 1 to 7 left-justified, zero-filled ASCII characters. Each Hollerith unit identifier is associated with the file of the same name, which may or may not exist. For example, unit ‘red’L is associated with the file red in the current working directory.

Certain Fortran I/O statements have an implied unit number. The PRINT statement always refers to unit 101 (standard output).

Fortran INQUIRE and CLOSE statements may refer to any valid or invalid unit number. All other Fortran I/O statements may refer only to valid unit numbers. For the purposes of an executing Fortran program, all unit numbers in use or available for use by that program are valid (that is, they exist). All unit numbers that are not available for use are invalid (that is, they do not exist).

A valid unit number is any positive integer. Unit numbers 100 through 102 are reserved. Unit numbers 0, 5, and 6 are normally associated with the standard error, standard input, and standard output files, respectively, although that association can be overridden. All other valid unit numbers are associated with the file fort.i, as previously indicated. You can use the INQUIRE statement to check the validity (existence) of any unit number prior to using it. For example:

LOGICAL UNITOK, UNITOP
...
INQUIRE (UNIT = I, EXIST = UNITOK, OPENED = UNITOP)
IF (UNITOK .AND. .NOT. UNITOP) THEN
 OPEN (UNIT = I, ...)
ENDIF

Initially, all valid units are closed. A unit is connected to a file as the result of one of three types of opens:

An implicit open occurs when the first reference to a unit number is an I/O statement other than OPEN, CLOSE, INQUIRE, BACKSPACE, ENDFILE, or REWIND. For example:

WRITE (4) I, J, K

If unit number 4 is not open, the WRITE statement will cause it to be connected to the associated file (fort(4)), unless overridden by an assign(1) command referencing unit 4.
An explicit unnamed open occurs when the first reference to a unit number is an OPEN statement without a FILE specifier. For example:

OPEN (7, FORM='UNFORMATTED')

If unit number 7 is not open, the OPEN statement will cause it to be connected to the associated file (fort(7)), unless overridden by an assign command referencing unit 7.
An explicit named open occurs when the first reference to a unit number is an OPEN statement with a FILE specifier. Example:

OPEN (9, FILE='blue')

If unit number 9 is not open, the OPEN statement will cause it to be connected to the file blue, unless overridden by an assign command referencing unit 9 or the file blue.

The BACKSPACE, ENDFILE, and REWIND statements will not do an implicit open. If the unit is not connected to a file, the requested operation is disregarded.

Unit numbers 100 through 102 are permanently associated with the standard input, standard output, and standard error files, respectively. They may be referenced on READ and WRITE statements. A CLOSE statement on these unit numbers has no effect. An INQUIRE statement on these unit numbers will indicate they are nonexistent (invalid). These unit numbers exist to allow guaranteed access to the standard input, standard output, and standard error files, without regard to any unit actions taken by an executing program. Thus, a READ or WRITE I/O statement with an asterisk unit identifier (or a PRINT statement) will always work. Nonstandard I/O operations on these units (for example, BUFFER IN, BUFFER OUT, READMS, WRITEMS, and so on) are not supported.

Fortran application or library subroutines that want to access the standard error file, standard input file, or standard output file can use unit numbers 100 through 102, even if the user program closes or reuses unit numbers 0, 5, and 6.

Special Files

For all unit numbers associated with the standard input, standard output, and standard error files, the nature of that association is sequential and formatted. That is, unformatted and/or direct-access statements are not allowed on those files. Furthermore, the standard input file is read-only. ENDFILE, PRINT, and WRITE statements are not allowed, and the standard error and standard output files are write-only (READ statements are not allowed).

REWIND and BACKSPACE statements are permitted on terminal files, but with no effect.

ENDFILE is permitted on terminal files, unless they are read-only (standard input); it writes a logical endfile record.

For all unit numbers associated with pipes, the REWIND statement is invalid. If the file logically has to be repositioned, the BACKSPACE statement is invalid. A situation in which the file may not have to be positioned is a BACKSPACE over an endfile record for a file that has only a logical representation of an endfile record (for example, text files).

Inquire-by-Unit Processing

The INQUIRE statement can be used to retrieve the name of a file connected to a specified unit, if the file has a name. The Fortran standard allows for unnamed files.

The standard input, standard output, and standard error files are unnamed, and an INQUIRE on a unit connected to any of these files indicates that it is unnamed (the NAMED parameter is set to .FALSE.).

An INQUIRE on any unit connected using an explicit named open will indicate that the file is named and will return as the name, the name that was given on the FILE specifier on the OPEN statement.

An INQUIRE on any unit connected using an explicit unnamed open or an implicit open, may or may not indicate that the file is named. A name will be returned only if the Fortran run-time library can ensure that a subsequent open, with the FILE specified as the name, will connect to the same file. For scratch files (files opened with STATUS=’SCRATCH’), a name is returned so the same assign(1) options associated with the file name are used.

CAUTIONS

The property of unit numbers 100 through 102, whereby they appear nonexistent or invalid on an INQUIRE or OPEN and yet I/O is permitted, is an extension to the Fortran standard.

It is possible that the special files (standard input, standard output, and standard error) can have two different units connected to them simultaneously (units 0/102, 5/100, and 6/101). This is an extension to the Fortran standard.