| Fortran Language Reference Manual, Volume 2 - S-3693-50 | ||
|---|---|---|
| Prev Section | Chapter 1. Input and Output (I/O) Processing | Next Section |
The OPEN statement establishes a connection between a unit and an external file and determines the connection properties. In order to perform data transfers (reading and writing), the file must be connected with an OPEN statement or be preconnected. It can also be used to change certain properties of the connection between the file and the unit, to create a file that is preconnected, or create a file and connect it.
The OPEN statement can appear anywhere in a program, and once executed, the connection of the unit to the file is valid in the main program or any subprogram for the remainder of that execution, unless a CLOSE statement affecting the connection is executed.
If a file is already connected to one unit, it must not be connected to a different unit.
The OPEN statement connects an external file to a unit. If the file does not exist, it is created. If a unit is already connected to a file that exists, an OPEN statement referring to that unit may be executed. If the FILE= specifier is not included, the unit remains connected to the file. If the FILE= specifier names the same file, the OPEN statement may change the connection properties. If it specifies a different file by name, the effect is as if a CLOSE statement without a STATUS= specifier is executed on that unit and the OPEN statement is then executed. For information on default values for the STATUS= specifier, see Section 1.6.1.3.
If a unit is preconnected to a file that does not exist, the OPEN statement creates the file and establishes properties of the connection.
Execution of an OPEN statement can change the properties of a connection that is already established. The properties that can be changed are those indicated by BLANK=, DELIM=, PAD=, ERR=, and IOSTAT= specifiers. If new values for DELIM=, PAD=, and BLANK= specifiers are specified, these will be used in subsequent data transfer statements; otherwise, the old ones will be used. However, the values in ERR= and IOSTAT= specifiers, if present, apply only to the OPEN statement being executed; after that, the values of these specifiers have no effect. If no ERR= or IOSTAT= specifier appears in the new OPEN statement, error conditions will terminate the execution of the program.
The OPEN statement and the connection specifier are defined as follows:
Table 1-10.
| open_stmt | is |
| |
| connect_spec | is |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
|
| or |
| |
| file_name_expr | is |
|
A unit specifier is required. If the keyword UNIT is omitted, the scalar integer expression must be the first item in the list. Note that the form * for the unit specifier is not allowed in the OPEN statement. However, in cases where the default external unit specified by an asterisk also corresponds to a nonnegative unit specifier (such as unit numbers 5 and 6), inquiries about these default units and connection properties are possible.
A specifier must not appear more than once in an OPEN statement.
The character expression established for many of the specifiers must contain one of the permitted values from the list of alternative values for each specifier described in the following section. For example, OLD, NEW, REPLACE, UNKNOWN, or SCRATCH are permitted for the STATUS= specifier; any other combination of letters is not permitted. Trailing blanks in any specifier are ignored. The value specified can contain both uppercase and lowercase letters.
If the last data transfer to a unit connected for sequential access to a particular file is an output data transfer statement, an OPEN statement for that unit connecting it to a different file writes an end-of-file record to the original file.
The OPEN statement specifies the connection properties between the file and the unit, using keyword specifiers, which are described in this section. Table 1-11 indicates the possible values for the specifiers in an OPEN statement and their default values when the specifier is omitted.
Table 1-11. Values for Keyword Specifier Variables in an OPEN Statement
Specifier | Possible values | Default value |
|---|---|---|
ACCESS= | DIRECT, SEQUENTIAL | SEQUENTIAL |
ACTION= | READ, WRITE, READWRITE | File dependent |
BLANK= | NULL, ZERO | NULL |
DELIM= | APOSTROPHE, QUOTE, NONE | NONE |
ERR= | Label | No default |
FILE= | Character expression | fort. is prepended to the unit number |
FORM= | FORMATTED | FORMATTED for sequential access |
| UNFORMATTED | UNFORMATTED for direct access |
| SYSTEM (EXTENSION) |
|
IOSTAT= | Scalar default integer variable | No default |
PAD= | YES, NO | YES |
POSITION= | ASIS, REWIND, APPEND | ASIS |
RECL= | Positive scalar integer expression | File dependent |
STATUS= | OLD, NEW, UNKNOWN, REPLACE, SCRATCH | UNKNOWN |
UNIT= | Scalar integer expression | No default |
Note: The Fortran standard does not describe the FORM=SYSTEM specifier.
The UNIT= specifier has the following format:
[ UNIT= ] scalar_int_expr |
The value of scalar_int_expr must be nonnegative.
A unit specifier with an external unit is required. If the keyword UNIT is omitted, the unit specifier must be the first item in the list.
A unit number identifies one and only one external unit in all program units in a Fortran program.
The ACCESS= specifier has the following format:
ACCESS= scalar_char_expr |
For scalar_char_expr, specify either DIRECT or SEQUENTIAL. DIRECT specifies the direct access method for data transfer. SEQUENTIAL specifies the sequential access method for data transfer; SEQUENTIAL is the default.
If the file exists, the method specified must be an allowed access method for the file.
If the file is new, the allowed access methods given for the file must include the one indicated.
If the ACCESS= specifier has the value DIRECT, a RECL= specifier must be present.
The ACTION= specifier has the following format:
ACTION= scalar_char_expr |
Specify one of the following for scalar_char_expr:
| Value | Function | |
| READ | Indicates that WRITE, PRINT, and ENDFILE statements are prohibited. | |
| WRITE | Indicates that READ statements are prohibited. | |
| READWRITE | Indicates that any I/O statement is permitted. |
The default value depends on the file structure.
If READWRITE is an allowed ACTION= specifier, READ and WRITE must also be allowed ACTION= specifiers.
For an existing file, the specified action must be an allowed action for the file.
For a new file, the value of the ACTION= specifier must be one of the allowed actions for the file.
The BLANK= specifier has the following format:
BLANK= scalar_char_expr |
For scalar_char_expr, specify either NULL or ZERO. NULL specifies that the compiler should ignore all blanks in numeric fields; this is the default. ZERO specifies that the I/O library should interpret all blanks except leading blanks as zeros.
A field of all blanks evaluates to zero regardless of the argument specified to BLANK=.
The BLANK= specifier may be specified for files connected only for formatted I/O.
The DELIM= specifier has the following format:
DELIM= scalar_char_expr |
Specify one of the following for scalar_char_variable:
If the DELIM= specifier is APOSTROPHE, any occurrence of an apostrophe within a character constant will be doubled; if the DELIM= specifier is QUOTE, any occurrence of a quote within a character constant will be doubled.
The specifier is permitted only for a file connected for formatted I/O; it is ignored for formatted input.
The ERR= specifier has the following format:
ERR= label |
The program branches to the label in the ERR= specifier if an error occurs in the OPEN statement. The label must be the label of a branch target statement in the same scoping unit as the OPEN statement.
If an error condition occurs, the position of the file becomes indeterminate.
If an IOSTAT= specifier is present and an error condition occurs, the IOSTAT variable specified becomes defined with a positive value.
The FILE= specifier has the following format:
FILE= scalar_char_expr |
For scalar_char_expr, specify the name of the file to be connected. This is called the file name expression.
Trailing blanks in the file name are ignored.
The maximum length of a file name and path is 256 and 1023 characters, respectively. For information on file name lengths and other system limits, see the limits.h(3c) man page.
Example:
FILENM = 'dir/fnam' FNUM = '/subfnum' OPEN (UNIT = 8, FILE = 'beauty') OPEN (UNIT = 9, FILE = FILENM) OPEN (UNIT = 10, FILE = FNAME//FNUM) |
The FILE= specifier must appear if the STATUS= specifier is OLD, NEW, or REPLACE; the FILE= specifier must not appear if the STATUS= specifier is SCRATCH.
If the FILE= specifier is omitted and the unit is not already connected to a file, the STATUS= specifier must have the value SCRATCH and the unit becomes connected to a file with the unit number appended to the fort. string.
The FORM= specifier has the following format:
FORM= scalar_char_expr |
For scalar_char_expr, specify either FORMATTED, UNFORMATTED, or SYSTEM. FORMATTED indicates that all records are formatted. UNFORMATTED indicates that all records are unformatted.
The default value is UNFORMATTED if the file is connected for direct access and the FORM= specifier is absent.
The default value is FORMATTED if the file is connected for sequential access and the FORM= specifier is absent.
A file opened with SYSTEM is unformatted and has no record marks.
If the file is new, the allowed forms given for the file must include the one indicated.
If the file exists, the form specified by the FORM= specifier must be one of the allowed forms for the file.
Note: The Fortran standard does not define the SYSTEM argument to the FORM= specifier.
The IOSTAT= specifier has the following format:
IOSTAT= scalar_default_int_variable |
The I/O library will return an integer value in scalar_default_int_variable. If scalar_default_int_variable > 0, an error condition occurred. If scalar_default_int_variable = 0, no error condition occurred. Note that the value cannot be negative.
The IOSTAT= specifier applies to the execution of the OPEN statement itself.
The PAD= specifier has the following format:
PAD= scalar_char_expr |
For scalar_char_expr, specify either YES or NO. YES indicates that the I/O library should use blank padding when the input item list and format specification require more data than the record contains; this is the default. NO indicates that the I/O library requires that the input record contain the data indicated by the input list and format specification.
The PAD= specifier is permitted only for a file connected for formatted I/O; it is ignored for formatted output.
If this specifier has the value YES and an end-of-record condition occurs, the data transfer behaves as if the record were padded with sufficient blanks to satisfy the input item and the corresponding data edit descriptor.
The POSITION= specifier has the following format:
POSITION= scalar_char_expr |
Specify one of the following for scalar_char_expr:
The file must be connected for sequential access.
If the file is new, it is positioned at its initial point, regardless of the value of the POSITION= specifier.
The RECL= specifier has the following format:
RECL= scalar_int_expr |
For scalar_int_expr, specify a positive value that specifies either the length of each direct access record or the maximum length of a sequential access record.
If the RECL= specifier is absent for a file connected for sequential access, the default value is 1024 characters for a write operation. For sequential access read operations, the RECL value is automatically increased as necessary.
The RECL= specifier must be present for a file connected for direct access.
If the file is connected for formatted I/O, the length is the number of characters.
If the file is connected for unformatted I/O, the length is measured in 8-bit bytes.
If the file exists, the length of the record specified must be an allowed record length.
If the file does not exist, the file is created with the specified length as an allowed length.
The STATUS= specifier has the following format:
STATUS= scalar_char_expr |
Specify one of the following for scalar_char_expr:
Scratch files must be unnamed; that is, the STATUS= specifier must not be SCRATCH when a FILE= specifier is present. The term scratch file refers to this temporary file.
Note that if the STATUS= specifier is REPLACE, the specifier in this statement is not changed to OLD; only the file status is considered to be OLD when the file is used in subsequently executed I/O statements, such as a CLOSE statement.
| Prev Section | Table of Contents | Title Page | Index | Next Section |
| Error and Other Conditions in I/O Statements | Up one level | CLOSE Statement |