Purpose
The OPEN statement can be used to connect an existing external file to a unit, create an external file that is preconnected, create an external file and connect it to a unit, or change certain specifiers of a connection between an external file and a unit.
Syntax
- open_list
- is a list that must contain either one unit specifier
([UNIT=u])
or one NEWUNIT= specifier
. The list can optionally contain one of each of the other
valid specifiers. When the list contains more than one specifier,
use a comma (,) as the separator. The valid specifiers are as follows: - [UNIT=] u
- is a unit specifier in which u must
be an external unit identifier whose value is not an asterisk. An
external unit identifier refers to an external file that is represented
by an integer expression. The integer expression has one of the following
values:
- A value in the range 1 through 2147483647
- A NEWUNIT
value
- ACCESS= char_expr
- specifies the access method for the connection of the file. char_expr is
a scalar character expression whose value, when any trailing blanks
are removed, is either SEQUENTIAL, DIRECT or STREAM.
If ACCESS= is DIRECT, RECL= must
be specified.
If ACCESS= is STREAM, RECL= must
not be specified
. SEQUENTIAL is the default, for which RECL= is optional
- ACTION= char_expr
- specifies the allowed input/output operations. char_expr is
a scalar character expression whose value evaluates to READ, WRITE or READWRITE.
If READ is specified, WRITE, PRINT and ENDFILE statements
cannot refer to this connection. If WRITE is
specified, READ statements cannot refer
to this connection. The value READWRITE permits
any input/output statement to refer to this connection. If the ACTION= specifier
is omitted, the default value depends on the actual file permissions:
- If the STATUS= specifier has the value OLD or UNKNOWN and
the file already exists:
- The file is opened with READWRITE
- If the above is not possible, the file is opened with READ
- If neither of the above is possible, the file is opened with WRITE.
- If the STATUS= specifier has the value NEW, REPLACE, SCRATCH or UNKNOWN and
the file does not exist:
- The file is opened with READWRITE
- If the above is not possible, the file is opened with WRITE.
- If the STATUS= specifier has the value OLD or UNKNOWN and
the file already exists:
- ASYNCH= char_expr (IBM extension)
- is
an asynchronous I/O specifier that indicates whether an explicitly
connected unit is to be used for asynchronous I/O.
char_expr is a scalar character expression whose value is either YES or NO. YES specifies that asynchronous data transfer statements are permitted for this connection. NO specifies that asynchronous data transfer statements are not permitted for this connection. The value specified will be in the set of transfer methods permitted for the file. If this specifier is omitted, the default value is NO.
Preconnected units are connected with an ASYNCH= value of NO.
The ASYNCH= value of an implicitly connected unit is determined by the first data transfer statement performed on the unit. If the first statement performs an asynchronous data transfer and the file being implicitly connected permits asynchronous data transfers, the ASYNCH= value is YES. Otherwise, the ASYNCH= value is NO.
- ASYNCHRONOUS=char_expr (fortran 2003)
- specifies
whether or not asynchronous I/O on the unit is allowed.
char_expr is a scalar character expression whose value is either YES or NO. If char_expr is the value YES asynchronous I/O on the unit is allowed. If char_expr is the value NO asynchronous I/O on the unit is not allowed. If ASYNCHRONOUS= is not present, the default value is NO.
-
An
ASYNCH= specifier 
and an ASYNCHRONOUS= specifier should
not appear on the same OPEN statement, the
second one is ignored.
- BLANK= char_expr
- controls the default interpretation of blanks when you are using a format specification. char_expr is a scalar character expression whose value, when any trailing blanks are removed, is either NULL or ZERO. If BLANK= is specified, you must use FORM='FORMATTED'. If BLANK= is not specified and you specify FORM='FORMATTED', NULL is the default.
- DECIMAL= char_expr (Fortran 2003)
- specifies the default decimal edit mode for the corresponding unit. char_expr is a scalar character expression whose value must evaluate to either POINT or COMMA. If DECIMAL= is not specified, the decimal point mode is in effect by default.
- DELIM= char_expr
- specifies what delimiter, if any, is used to delimit character constants written with list-directed or namelist formatting. char_expr is a scalar character expression whose value must evaluate to APOSTROPHE, QUOTE, or NONE. If the value is APOSTROPHE, apostrophes delimit character constants and all apostrophes within character constants are doubled. If the value is QUOTE, double quotation marks delimit character constants and all double quotation marks within character constants are doubled. If the value is NONE, character constants are not delimited and no characters are doubled. The default value is NONE. The DELIM= specifier is permitted only for files being connected for formatted input/output, although it is ignored during input of a formatted record.
- ENCODING= char_expr (Fortran 2003)
- specifies the encoding form of the file. char_expr is a scalar character expression whose value, when any trailing blanks are removed, is DEFAULT. The ENCODING= specifier must only appear in formatted I/O statements. If omitted, the default value is DEFAULT.
- ERR= stmt_label
- is an error specifier that specifies the statement label of an executable statement in the same scoping unit to which control is to transfer in the case of an error. Coding the ERR= specifier suppresses error messages.
- FILE= char_expr
-
is a file specifier that specifies the name of the file to be connected to the specified unit.
char_expr is a scalar character expression whose value, when any trailing blanks are removed, is a valid Linux operating system file name. If the file specifier is omitted and is required, the unit becomes implicitly connected (by default) to fort.u, where u is the unit specified with any leading zeros removed. Use the UNIT_VARS run-time option to allow alternative files names to be used for files that are implicitly connected.Note: A valid Linux operating system file name must have a full path name of total length ≤1023 characters, with each file name ≤255 characters long (although the full path name need not be specified). - FORM= char_expr
- specifies whether the file is connected for formatted or unformatted
input/output. char_expr is a scalar character
expression whose value, when any trailing blanks are removed, is either FORMATTED or UNFORMATTED.
If you connect the file for sequential access, FORMATTED is
the default. If you connect the file for direct access or stream
access , UNFORMATTED is
the default.
- IOMSG= iomsg_variable (Fortran 2003)
- is an input/output status specifier that specifies the message
returned by the input/output operation. iomsg_variable is
a scalar default character variable. It must not be a use-associated
nonpointer protected variable. When the input/output statement containing
this specifier finishes execution, iomsg_variable is
defined as follows:
- If an error, end-of-file, or end-of-record condition occurs, the variable is assigned an explanatory message as if by assignment.
- If no such condition occurs, the value of the variable is unchanged.
- IOSTAT= ios
- An input/output status specifier for the status of the input/output
operation. ios is a scalar integer variable.
When the input/output statement containing this specifier finishes
execution, ios is defined with:
- A zero value if no error condition occurs
- A positive value if an error occurs
- NEWUNIT= var (Fortran 2008)
- an input/output specifier that specifies the NEWUNIT value for the connection. var is a scalar default integer variable. The NEWUNIT value is a negative number that is less than -2 and is unequal to the unit number of any currently connected file. If you specify NEWUNIT= specifier in the OPEN statement, you must also specify the STATUS= specifier with value SCRATCH or specify the FILE= specifier.
- PAD= char_expr
- specifies if input records are padded with blanks. char_expr is
a scalar character expression that must evaluate to YES or NO. If
the value is YES, a formatted input record
is padded with blanks if an input list is specified and the format
specification requires more data from a record than the record contains. If NO is
specified, the input list and format specification must not require
more characters from a record than the record contains. The
default value is YES. The PAD= specifier
is permitted only for files being connected for formatted input/output,
although it is ignored during output of a formatted record. If the -qxlf77 compiler
option specifies the noblankpad suboption
and the file is being connected for formatted direct input/output,
the default value is NO when the PAD= specifier
is omitted.
- POSITION= char_expr
- specifies the file position for a file connected for sequential
or stream access. A file that did not exist previously is positioned
at its initial point. char_expr is a scalar
character expression whose value, when any trailing blanks are removed,
is either ASIS, REWIND,
or APPEND. REWIND positions
the file at its initial point. APPEND positions
the file before the endfile record or, if there is no endfile record,
at the terminal point. ASIS leaves the position
unchanged. The default value is ASIS except
under the following conditions:
- The first input/output statement (other than the INQUIRE statement)
referring to the unit after the OPEN statement
is a WRITE statement, and either:
- The STATUS= specifier is UNKNOWN and the -qposition compiler option specifies appendunknown, or
- The STATUS= specifier is OLD and the -qposition compiler option specifies appendold.
In such cases, the default value for the POSITION= specifier is APPEND at the time the WRITE statement is executed.
- The first input/output statement (other than the INQUIRE statement)
referring to the unit after the OPEN statement
is a WRITE statement, and either:
- RECL= integer_expr
-
specifies the length of each record in a file being connected for direct access or the maximum length of a record in a file being connected for sequential access. integer_expr is an integer expression whose value must be positive. This specifier must be present when a file is being connected for direct access. For formatted input/output, the length is the number of characters for all records that contain character data. For unformatted input/output, the length is the number of bytes required for the internal form of the data. The length of an unformatted sequential record does not count the four-byte fields surrounding the data.
If RECL= is omitted when a file is being connected for sequential access in 32-bit, the length is 2**31–1, minus the record terminator. For a formatted sequential file in 32-bit, the default record length is 2**31-2. For an unformatted file that can be accessed in 32-bit, the default record length is 2**31-9.
For a file that cannot be accessed randomly in 32-bit, the default length is 2**15 (32,768).
If RECL= is omitted when a file is being connected for sequential access in 64-bit, the length is 2**63–1, minus the record terminator. For a formatted sequential file in 64-bit, the default record length is 2**63-2 For an unformatted file in 64-bit, the default record length is 2**63-17 when the UWIDTH run-time option is set to 64.
- ROUND= char_expr (Fortran 2003)
-
states the current value of the I/O rounding mode for formatted input and output. The ROUND= can be changed by other statements. If omitted, then the processor can choose the rounding mode. char_expr evaluates to either UP, DOWN, ZERO, NEAREST, COMPATIBLE or PROCESSOR_DEFINED
The rounding mode helps specify how decimal numbers are converted to an internal representation, (that is, in binary) from a character representation and vice versa during formatted input and output. The rounding modes have the following functions:
- In the UP rounding mode the value from the conversion is the smallest value that is greater than or equal to the original value.
- In the DOWN rounding mode the value from the conversion is the greatest value that is smaller than or equal to the original value.
- In the ZERO rounding mode the value from the conversion is the closest value to the original value, and not greater in magnitude.
- In the NEAREST rounding mode the value from the conversion is the closer of the two nearest representable values. If both values are equally close then the even value will be chosen. In IEEE rounding conversions, NEAREST corresponds to the ieee_nearest rounding mode as specified by the IEEE standard.
- In the COMPATIBLE rounding mode the value from the conversion is the closest of the two nearest representable values, or the value further away from zero if halfway between.
- In the PROCESSOR_DEFINED rounding mode the value from the conversion is processor-dependent and may correspond to the other modes. In XL Fortran, the PROCESSOR_DEFINED rounding mode will be the rounding mode you choose in the floating-point control register. If you do not set the floating-point control register explicitly, the default rounding mode is NEAREST.
- SIGN= char_expr (Fortran 2003)
- indicates the sign mode in effect for a connection for formatted input/output. If char_expr is assigned the value PLUS, the processor shall produce a plus sign in any position that normally contains an optional plus sign and suppresses plus signs in these positions if char_expr is assigned the value SUPPRESS. char_expr can also be assigned the value PROCESSOR_DEFINED which is the default sign mode and acts the same as SUPPRESS. If there is no connection, or if the connection is not for formatted input/output, char_expr is assigned the value UNDEFINED. The sign mode may be temporarily changed in a single data transfer statement. When the statement terminates, the sign mode resumes its previous value.
- STATUS= char_expr
- specifies the status of the file when it is opened. char_expr is
a scalar character expression whose value, when any trailing blanks
are removed, is one of the following:
- OLD, to connect an existing file to a unit. If OLD is specified, the file must exist. If the file does not exist, an error condition will occur.
- NEW, to create a new file, connect it to a unit, and change the status to OLD. If NEW is specified, the file must not exist. If the file already exists, an error condition will occur.
- SCRATCH, to create and connect a new file that will be deleted when it is disconnected. SCRATCH must not be specified with a named file (that is, FILE=char_expr must be omitted).
- REPLACE. If the file does not already exist, the file is created and the status is changed to OLD. If the file exists, the file is deleted, a new file is created with the same name, and the status is changed to OLD.
- UNKNOWN, to connect an existing file, or to create and connect a new file. If the file exists, it is connected as OLD. If the file does not exist, it is connected as NEW.
UNKNOWN is the default.
Rules
If a unit is connected to a file that exists, an OPEN statement for that unit can be performed. If the FILE= specifier is not included in the OPEN statement, the file to be connected to the unit is the same as the file to which the unit is connected.
If an OPEN statement
containing a NEWUNIT= specifier is executed
successfully, the variable specified by NEWUNIT= is
assigned with a new NEWUNIT value. However, if an error occurs during
the execution of the OPEN statement, the
variable specified by NEWUNIT= keeps its
original value.
If the file to be connected to the unit is not the same as the file to which the unit is connected, the effect is as if a CLOSE statement without a STATUS= specifier had been executed for the unit immediately prior to the execution of the OPEN statement.
If the file to be connected to the unit is the same as the file to which the unit is connected, only the BLANK=, DELIM=, PAD=, ERR=, and IOSTAT= specifiers can have a value different from the one currently in effect. Execution of the OPEN statement causes any new value for the BLANK=, DELIM= or PAD= specifiers to be in effect, but does not cause any change in any of the unspecified specifiers or the position of the file. Any ERR= and IOSTAT= specifiers from OPEN statements previously executed have no effect on the current OPEN statement. If you specify the STATUS= specifier it must have the value OLD. To specify the same file as the one currently connected to the unit, you can specify the same file name, omit the FILE= specifier, or specify a file symbolically linked to the same file.
If a file is connected to a unit, an OPEN statement on that file and a different unit cannot be performed.
If the STATUS= specifier has the
value OLD, NEW or REPLACE,
the FILE= specifier is optional.
Unit
0 cannot be specified to connect to a file other than the preconnected
file, the standard error device, although you can change the values
for the BLANK=, DELIM= and PAD= specifiers.
If the ERR= and IOSTAT= specifiers are set and an error is encountered, transfer is made to the statement specified by the ERR= specifier and a positive integer value is assigned to ios.
If IOSTAT= and ERR= are
not specified, - The program stops if a severe error is encountered
- The program continues to the next statement if a recoverable error
is encountered and the ERR_RECOVERY run-time
option is set to YES. If the option is set
to NO, the program stops.
Examples
INTEGER unit_number
OPEN(newunit = unit_number, file = 'hello')
WRITE(unit_number, *) 'hello world'
CLOSE(unit_number)Example 2:
! Open a new file with name fname
CHARACTER*20 FNAME
FNAME = 'INPUT.DAT'
OPEN(UNIT=8,FILE=FNAME,STATUS='NEW',FORM='FORMATTED')
OPEN (4,FILE="myfile")
OPEN (4,FILE="myfile", PAD="NO") ! Changing PAD= value to NO
! Connects unit 2 to a tape device for unformatted, sequential
! write-only access:
OPEN (2, FILE="/dev/rmt0",ACTION="WRITE",POSITION="REWIND", &
& FORM="UNFORMATTED",ACCESS="SEQUENTIAL",RECL=32767)Related information
- Units
- Item 3 under Compatibility across standards
- XL Fortran Input/Output
- Setting Run-Time Options in the XL Fortran Compiler Reference
- -qposition option in the XL Fortran Compiler Reference
- -qxlf77 option in the XL Fortran Compiler Reference
- CLOSE
- READ
- WRITE