Language Reference

OPEN

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.

Format

>>-OPEN--(--open_list--)---------------------------------------><
 
 

open_list

is a list that must contain one unit specifier (UNIT=u) and can also contain one of each of the other valid specifiers. The valid specifiers are:

[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 a scalar integer expression, whose value is in the range 0 through 2,147,483,647. If the optional characters UNIT= are omitted, u must be the first item in open_list.

+-------------------------------IBM Extension--------------------------------+

ASYNCH= char_expr

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.

+----------------------------End of IBM Extension----------------------------+

IOSTAT= ios

is an input/output status specifier that specifies the status of the input/output operation. ios is a scalar variable of type INTEGER(4) or default integer. 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.

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.

+-------------------------------IBM Extension--------------------------------+

char_expr is a scalar character expression whose value, when any trailing blanks are removed, is a valid AIX 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 AIX 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).

+----------------------------End of IBM Extension----------------------------+

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.

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 or DIRECT. SEQUENTIAL is the default. If ACCESS is DIRECT, RECL= must be specified. If ACCESS is SEQUENTIAL, RECL= is optional.

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 the file is being connected for sequential access, FORMATTED is the default. If the file is being connected for direct access, UNFORMATTED is the default.

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 a scalar 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.

+-------------------------------IBM Extension--------------------------------+

If RECL= is omitted when a file is being connected for sequential access in 32-bit, the length is 2**31 minus the record terminator. For a formatted sequential file in 32-bit, the default record length is 2**31-1. For an unformatted file that can be accessed in 32-bit, the default record length is 2**31-8. For a file that cannot be accessed randomly in 32-bit, the default length is 32,768.

If RECL= is omitted when a file is being connected for sequential access in 64-bit, the length is 2**64 minus the record terminator. For a formatted sequential file in 64-bit, the default record length is 2**64-1 For an unformatted file in 64-bit, the default record length is 2**64-16 when the UWIDTH run-time option is set to 64.

+----------------------------End of IBM Extension----------------------------+

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.

POSITION= char_expr

specifies the file position for a file connected for sequential 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.

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 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.

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.

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.

+-------------------------------IBM Extension--------------------------------+

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.

+----------------------------End of IBM Extension----------------------------+

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 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.

+-------------------------------IBM Extension--------------------------------+

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.

+----------------------------End of IBM Extension----------------------------+

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.

+-------------------------------IBM Extension--------------------------------+

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.

+----------------------------End of IBM Extension----------------------------+

Examples

!   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

• Connection of a Unit
• Item 3 under Appendix A, Compatibility Across Standards
• Conditions and IOSTAT Values
• "Setting Runtime Options for Input/Output" in the User's Guide
• "-qposition Option" in the User's Guide
• "-qxlf77 Option" in the User's Guide
• CLOSE
• READ
• WRITE