VMS Help
FORTRAN, Statements, OPEN
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
|
Opens an existing file or creates a new file. If you do not
explicitly open a file before accessing it, the file is created
(for write operations) or opened with default attributes.
OPEN (par[,par]...)
par Is a keyword specification in one of the
following forms:
keywd
keywd=value
keywd Is a keyword. (See the subtopic headings
listed at the end of this Help topic.)
value Is a keyword value. (Some keywords do not
have keyword values.)
If an OPEN statement is executed for a unit that is already open,
and the file specification is different from that of the current
open file, the previously opened file is closed and the new file is
opened. If the file specification is the same for both files, the
new value of the BLANK= specifier is in effect, but the position of
the file is unaffected.
Keyword specifications can appear in any order. In most cases,
they are optional. Default values apply in their absence. If the
logical unit specifier is the first parameter in the list, the UNIT
keyword is optional.
You can specify character values at run time by substituting a
general character expression for a keyword value in the OPEN
statement. The character value can contain trailing spaces but not
leading or embedded spaces; for example:
CHARACTER*6 FINAL /' '/
.
.
.
IF (exp) FINAL = 'DELETE'
OPEN (UNIT=1, STATUS='NEW', DISP=FINAL)
NOTE: Keyword values that are numeric expressions can be any
integer or real expression. The value of the expression is
converted to integer data type before it is used in the OPEN
statement.
ACCESS = acc
acc Is a character expression with one of the following
values:
'DIRECT' Access by record number
'SEQUENTIAL' Access sequentially (*DEFAULT*)
'KEYED' Access by a specified key
'APPEND' Access sequentially, after the last record
of the file
ASSOCIATEVARIABLE = asv
asv Is an integer variable. It cannot be a dummy argument
to the routine in which the OPEN statement appears.
Use only in direct access mode.
NOTE: Direct access READ, direct access WRITE, FIND, DELETE, and
REWRITE statements can affect the value of the variable.
BLANK = blnk
blnk Is a character expression with one of the following
values:
'NULL' Ignore all blanks in a numeric field (unless the field
is all blanks, in which case treat blanks as zero).
'ZERO' Treat all blanks other than leading blanks as zeros.
The default is 'NULL'. However, if you specify the /NOF77 compiler
option (or OPTIONS /NOF77), the file is implicitly opened, or the
file is opened for internal I/O, the default is 'ZERO'.
BLOCKSIZE = bks
bks Is a numeric expression whose value specifies a
number of bytes.
For magnetic tape files, the value of "bks" specifies the physical
record size in the range 18 to 32767 bytes. The default value is
2048 bytes.
For sequential disk files, "bks" is rounded up to an integral
number of 512-byte blocks and used to specify multiblock transfers.
The number of blocks transferred can be 1 to 127, and defaults to
the current count for the device at program run time.
For indexed and relative files, "bks" is rounded up to an integral
number of 512-byte blocks and used to specify the RMS bucket size.
This must fall in the range 1 to 63 blocks, and defaults to the
smallest value capable of holding one record.
BUFFERCOUNT = bc
bc Is a numeric expression whose value specifies
the number of buffers to be associated with the
logical unit for multibuffered I/O. The range
for "bc" is 1 to 127.
If you do not specify BUFFERCOUNT or you specify 0, the system
default is assumed.
CARRIAGECONTROL = cc
cc Is a character expression with one of the following
values:
'FORTRAN' Process with normal FORTRAN interpretation of
the first character
'LIST' Process with single spacing between records
'NONE' Do not use implied carriage control
The default for unformatted files is 'NONE'. The default for
formatted files is 'FORTRAN'.
CONVERT = fm
fm Is a character expression with one of the following
options:
'LITTLE_ENDIAN'- Little endian integer data of the
appropriate size (INTEGER*1, INTEGER*2,
or INTEGER*4) and IEEE floating-point
data of the appropriate size and
type (REAL*4, REAL*8, COMPLEX*8, COMPLEX*16).
INTEGER*1 data is the same for little endian
and big endian.
'BIG_ENDIAN' - Big endian integer data of the appropriate
size (INTEGER*1, INTEGER*2, or INTEGER*4)
and IEEE floating-point data of the
appropriate size and type (REAL*4, REAL*8,
COMPLEX*8, COMPLEX*16). INTEGER*1 data is
the same for little endian and big endian.
'CRAY' - Big endian integer data of the appropriate
size (INTEGER*1, INTEGER*2, or INTEGER*4)
and CRAY floating-point data of size REAL*8
or COMPLEX*16.
'IBM' - Big endian integer data of the appropriate
size (INTEGER*1, INTEGER*2, or INTEGER*4)
and IBM System\370 floating-point data of
size REAL*4 or COMPLEX*8 (IBM short 4)
and size REAL*8 or COMPLEX*16 (IBM long 8).
'VAXD' - Little endian integer data of the appropriate
size (INTEGER*1, INTEGER*2, or INTEGER*4)
and Compaq VAX floating-point data of
format F_floating for size REAL*4 or COMPLEX*8,
and D_floating for size REAL*8 or COMPLEX*16.
'VAXG' - Little endian integer data of the appropriate
size (INTEGER*1, INTEGER*2, or INTEGER*4)
and Compaq VAX floating-point data of
format F_floating for size REAL*4 or COMPLEX*8,
and G_floating for size REAL*8 or COMPLEX*16.
'NATIVE' - No data conversion. This is the default.
You can use CONVERT to specify multiple formats in a single
program, usually one format for each specified unit number.
When reading a non-native format, the non-native format on disk is
converted to native format in memory. If a converted non-native
value is outside the range of the native data type, a run-time
message appears.
There are other ways to specify numeric format for unformatted
files: you can specify a VMS logical name or the compiler option
CONVERT (or OPTIONS/CONVERT). The order of precedence is VMS
logical name, OPEN (CONVERT=), OPTIONS/CONVERT, and then compiler
option CONVERT. The CONVERT compiler option and OPTIONS/CONVERT
affect all unit numbers used by the program, while logical names
and OPEN (CONVERT=) affect specific unit numbers.
The following source code shows how to code the OPEN statement to
read unformatted CRAY numeric data from unit 15, which might be
processed and possibly written in little endian format to unit 20:
OPEN (CONVERT='CRAY', FILE='graph3.dat', FORM='UNFORMATTED',
1 UNIT=15)
.
.
.
OPEN (FILE='graph3_native.dat', FORM='UNFORMATTED', UNIT=20)
For more information on transporting data to or from an OpenVMS VAX
system and on supported ranges for data types, see your user
manual.
DEFAULTFILE = ce
ce Is a character expression that specifies a default file
specification string.
This keyword supplies a value to the RMS default file specification
string for the missing components of a file specification. If you
do not specify the DEFAULTFILE keyword, Fortran uses the default
value 'FORnnn.DAT', where nnn is the unit number with leading
zeros.
The default file pathname string is used primarily when accepting
file specifications interactively. File specifications known to a
user program are normally completely specified in the FILE keyword.
You can specify default values for any one of the following file
specification components: node, device, directory, file name, file
type, and file version number.
When you specify any of the above components in the FILE keyword,
they override those values specified in the DEFAULTFILE keyword.
The following example uses the file name supplied by the user and
the default file specification supplied by the DEFAULTFILE keyword
to define the file specification for an existing file:
TYPE *, 'ENTER NAME OF DOCUMENT'
ACCEPT *, DOC
OPEN (UNIT=1, FILE=DOC, DEFAULTFILE='[ARCHIVE].TXT',
1 STATUS='OLD')
DISPOSE = dis
or DISP = dis
dis Is a character expression with one of the following
values:
'KEEP' or 'SAVE' Retain the file after the unit is closed.
(*DEFAULT FOR ALL BUT SCRATCH FILES*)
'DELETE' Delete the file after the unit is closed.
(*DEFAULT FOR SCRATCH FILES*)
'PRINT' Submit the file as a print job and retain it.
Use this value only with sequential files.
'PRINT/DELETE' Submit the file as a print job and then
delete it. Use this value only with sequential
files.
'SUBMIT' Submit the file as a batch job and retain it.
'SUBMIT/DELETE' Submit the file as a batch job and then
delete it.
The disposition specified in a CLOSE statement supersedes the
disposition specified in the OPEN statement, except that a file
opened as a scratch file cannot be saved, printed, or submitted,
nor can a file opened for read-only access be deleted.
ERR = s
s Is the label of an executable statement that is to receive
control when an error occurs.
ERR applies only to the OPEN statement in which it is specified,
and not in following I/O operations on the unit. If an error
occurs, no file is opened or created. However, you can use IOSTAT
in following I/O statements to perform a similar function.
EXTENDSIZE = e
e Is a numeric expression whose value specifies
the number of blocks to extend a disk file when
additional file storage is allocated. The space
used to extend a file is contiguous if possible
otherwise, noncontiguous space is used. Defaults
to the system default for the device.
FILE = fln
fln Is a character scalar reference, numeric scalar memory
reference, or numeric array name reference.
The FILE parameter specifies the name of the file to be connected
to the unit. The name can be any file specification accepted by
the operating system.
If the file name is stored in a numeric scalar or array, the name
must consist of ASCII characters terminated by an ASCII null
character (zero byte). However, if it is stored in a character
scalar or array, it must not contain a zero byte.
FORM = ft
ft Is a character expression with one of the following
values:
'FORMATTED' Formatted *DEFAULT FOR SEQUENTIAL ACCESS*
'UNFORMATTED' Unformatted *DEFAULT FOR DIRECT AND KEYED ACCESS*
INITIALSIZE = e
e Is a numeric expression whose value specifies the
number of blocks in the initial allocation of space
for a new file on a disk. Defaults to no initial allocation.
If you do not specify INITIALSIZE or if you specify zero, no
initial allocation is made. The system attempts to allocate
contiguous space for INITIALSIZE. If not enough contiguous space
is available, noncontiguous space is allocated.
INITIALSIZE is effective only at the time the file is created. If
EXTENDSIZE is specified when the file is created, the value
specified is the default value used to allocate additional storage
for the file. If you specify EXTENDSIZE when you open an existing
file, the value you specify supersedes any EXTENDSIZE value
specified when the file was created, and remains in effect until
you close the file. Unless specifically overridden, the default
EXTENDSIZE value is in effect on later openings of the file.
IOSTAT = ios
ios Is an integer scalar memory reference.
If no error exists, ios is defined as zero; if an error exists, ios
is defined as a positive integer. IOSTAT applies only to the OPEN
statement in which it appears and not to later I/O operations on
the logical unit that it opened. However, you can use the IOSTAT
parameter in later I/O statements to perform a similar function.
Secondary operating system messages do not display when IOSTAT is
specified. To display these messages, remove IOSTAT or use a
platform-specific method such as a OpenVMS condition handler. (For
more information, see your user manual.)
KEY = (kspec[,kspec]...)
kspec Takes the following form:
e1:e2[:dt[:dr]]
e1 Is the position of the first byte of the
key in the record.
e2 Is the position of the last byte of the
key in the record.
dt Is the data type of the key: CHARACTER (*DEFAULT*)
or INTEGER.
dr Is the direction of the key: ASCENDING (*DEFAULT*)
or DESCENDING.
The length of the key must not exceed 255 bytes. The first byte
position of the key must be at least 1 and the last byte position
must not exceed the length of the record.
If the key type is INTEGER, the key length must be either 2 or 4.
Defining Primary and Alternate Keys:
You must define at least one key in an indexed file. This primary
key is the default key. It usually has a unique value for each
record (no duplicates). Alternate keys can be duplicated.
You can choose to define alternate keys. RMS allows up to 254
alternate keys. However, individual OPEN statements only allow up
to 85 key definitions, a number that is further reduced when
multiple OPEN statements appear together in a program unit.
If a file requires more keys than the OPEN statement limit, you
must create it from another language or with the File Definition
Language (FDL).
Specifying and Referencing Keys:
You must specify the KEY parameter when creating an indexed file.
However, you do not have to respecify it when opening an existing
file because key attributes are permanent aspects of the file.
These attributes include key definitions and reference numbers for
later I/O operations. If you do choose to specify the KEY
parameter for an existing file, your specification must be
identical to the established key attributes.
Following I/O operations use a reference number, called the
key-of-reference number, to identify a particular key. You do not
specify this number; it is determined by the key's position in the
specification list: the primary key is key-of-reference number 0;
the first alternate key is key-of-reference number 1, and so forth.
MAXREC = mr
mr Is an numeric expression whose value specifies the
maximum number of records permitted in a direct access
file. The default is the maximum allowed (2**32-1).
NAME is a nonstandard synonym for FILE. (See FILE.)
NOSPANBLOCKS
Specifies that records are not to cross disk block boundaries. If
a record exceeds the size of a physical block, an error occurs.
ORGANIZATION = org
org Is a character expression with one of the following
values:
'SEQUENTIAL' Records are stored in the order that
they are written. Access mode must be
sequential, append, or direct (fixed-length
records only). (*DEFAULT FOR NEW FILES*)
'RELATIVE' Records are stored in numbered positions.
Access mode must be direct or sequential.
'INDEXED' Records are stored according to the values
of their keys. Access mode must be indexed
or sequential.
The default for an existing file is its current organization.
READONLY
Prohibits write access to the file. Enables users with read access
but not write access to access the file.
The Fortran I/O system's default file access privileges are
read-write, which can cause run-time I/O errors if the file
protection does not permit write access.
The READONLY keyword has no effect on the protection specified for
a file. Its main purpose is to allow a file to be read
simultaneously by two or more programs. For example, if you wish
to open a file to read the file but want to allow others to read
the same file while you have it open, specify the READONLY keyword.
RECL = rl
rl Is an numeric expression whose value indicates the length
of logical records in a file.
The value of "rl" does not include space for control information,
such as for two segment control bytes (if present) or the bytes
that RMS requires for maintaining record length and deleted record
control information. The specification is for record data only.
The value of "r1" is expressed in units of bytes or longwords,
depending on the record's format. Formatted records use byte units
and unformatted records use longword units (which are equal to 4
bytes).
The following are the maximum values that can be specified for "r1"
for disk files that use the fixed-length record format:
Sequential formatted 32767 bytes
Sequential unformatted 8191 longwords
Relative formatted 32255 bytes
Relative unformatted 8063 longwords
Indexed formatted 32224 bytes
Indexed unformatted 8056 longwords
Tape formatted 9999 bytes
Tape unformatted 2499 longwords
For other record formats and device types, the record size limit
can be less, as described in the "OpenVMS Record Management
Services Reference Manual".
RECL is mandatory when opening new files (STATUS='NEW', 'UNKNOWN,
or 'SCRATCH') and when one or more of the following conditions
exists:
o The record format is fixed length (RECORDTYPE='FIXED').
o The file organization is relative or indexed
(ORGANIZATION='RELATIVE' or 'INDEXED').
o The file is opened for direct access (ACCESS='DIRECT').
RECL is optional in all other cases. Default values for optional
cases depend on the value of the RECORDTYPE parameter.
The following are the RECL default values:
RECORDTYPE value RECL value
---------------- -----------------------------------------
'FIXED' None; value must be explicitly specified.
All other types 133 bytes (for formatted records)
511 longwords (for unformatted records)
The interpretation and effect of the logical record length varies
as follows:
o If the file contains segmented records, RECL specifies the
maximum length for any segment (including the two
segment-control bytes).
o If the file contains fixed-length records, RECL specifies the
size of each record.
o If the file contains variable-length records, RECL specifies
the maximum length for any record.
o If your program attempts to write to an existing file a record
that is longer than the logical record length, an error occurs.
o If you are opening an existing file that contains fixed-length
records or has relative organization and you specify a value
for RECL that is different from the actual length of the
records in the file, an error occurs.
RECORDSIZE = e
RECORDSIZE is the nonstandard synonym for RECL.
RECORDTYPE = typ
typ Is a character expression with one of the following
values:
'FIXED' All records are one size. Short records are padded
with blanks (formatted files) or zeros (unformatted
files).
'VARIABLE' Records can vary in length.
'SEGMENTED' A record consists of one or more variable length
records, which can exist in different physical blocks.
Valid only for unformatted, sequential files with
sequential access.
'STREAM' Data is not grouped into records and contains no
control information.
'STREAM_CR' Variable-length records whose length is indicated by
carriage-returns embedded in the data.
'STREAM_LF' Variable-length records whose length is indicated by
line-feeds (new lines) embedded in the data.
When you open a file, default record types are as follows:
+-------------------------------------+---------------------+
| File Type | Default Record Type |
+-------------------------------------+---------------------+
| Relative or indexed files | 'FIXED' |
| Direct access sequential files | 'FIXED' |
| Formatted sequential access files | 'VARIABLE' |
| Unformatted sequential access files | 'SEGMENTED' |
+-------------------------------------+---------------------+
A segmented record consists of one or more variable-length records.
Using segmented records allows a Fortran logical record to span
several physical records. Only unformatted sequential access files
with sequential organization can use segmented records. You cannot
specify <SINGLE_QUOTE>SEGMENTED<SINGLE_QUOTE> for any other file
type.
If you do not specify the RECORDTYPE parameter when you are
accessing an existing file, the record type of the file is used ---
except for unformatted sequential-access files with sequential
organization and variable-length records. These files have a
default of 'SEGMENTED'.
If you do specify the RECORDTYPE parameter when you are accessing
an existing file, the type that you specify must match the type of
an existing file.
In fixed-length record files, if an output statement does not
specify a full record, the record is filled with spaces in a
formatted file and zeros in an unformatted file.
You cannot use an unformatted READ statement to access an
unformatted sequential organization file containing variable-length
records, unless you specify the corresponding RECORDTYPE value in
your OPEN statement.
Files containing segmented records can be accessed only by
unformatted sequential Fortran I/O statements.
SHARED
Specifies that the file can be accessed by more than one user at
the same time.
STATUS = sta
sta Is a character expression with one of the following
values:
'OLD' Open an existing file
'NEW' Create a new file; if the file already exists an
error occurs
'SCRATCH' Create a new file and delete it when the file is
closed
'UNKNOWN' Open the file as OLD; if it does not exist, then
open the file as NEW
The default is 'UNKNOWN'. However, if you implicitly open a file
using WRITE, or you specify the /NOF77 compiler option, or OPTIONS
/NOF77, the default value is 'NEW'. If you implicitly open a file
using READ, the default value is 'OLD'.
Scratch files (STATUS='SCRATCH') are created on the user's default
disk (SYS$DISK) and are not placed in a directory or given a name
that is externally visible. To specify a different device, use the
FILE keyword.
TYPE is a nonstandard synonym for STATUS (see STATUS).
[UNIT=] u
u Is a numeric expression that specifies the logical unit to
which a file is to be connected.
The unit specification must appear in the parameter list, unless
the unit specifier is the first element in the list.
The logical unit may already be connected to a file when an OPEN
statement is executed. If this file is not the same as the one to
be opened, the OPEN statement executes as if a CLOSE statement had
executed just before it.
If the file to be opened is already connected to the unit or if the
file specifier (FILE keyword) is not included in the OPEN
statement, only the blank specifier (BLANK keyword) can have a
value different from the one currently in effect. The position of
the file is unaffected.
USEROPEN = p
p Is the symbolic name of the USEROPEN procedure.
The USEROPEN parameter specifies a user-written
EXTERNAL function that controls the opening of
the file.
The name must be declared EXTERNAL in the program unit with the
OPEN statement, and if typed, it must be INTEGER*4.
[legal]
[privacy]
[GNU]
[policy]
[netiquette]
[sponsors]
[FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.