| Previous | Contents | Index |
The format specifier indicates the format to use for data editing. It takes the following form:
|
format
Is one of the following:
- The statement label of a FORMAT statement
The FORMAT statement must be in the same scoping unit as the data transfer statement.- An asterisk (*), indicating list-directed formatting
- A scalar default integer variable that has been assigned the label of a FORMAT statement (through an ASSIGN statement)
The FORMAT statement must be in the same scoping unit as the data transfer statement.- A character expression (which can be an array or character constant) containing the run-time format
A default character expression must evaluate to a valid format specification. If the expression is an array, it is treated as if all the elements of the array were specified in array element order and were concatenated.- The name of a numeric array (or array element) containing the format
If the keyword FMT is omitted, the format specifier must be the second specifier in the control list; the io-unit specifier must be first.
If a format specifier appears in a control list, a namelist group specifier must not appear.
The namelist specifier indicates namelist formatting and identifies the namelist group for data transfer. It takes the following form:
|
group
Is the name of a namelist group previously declared in a NAMELIST statement.
If the keyword NML is omitted, the namelist specifier must be the second specifier in the control list; the io-unit specifier must be first.
If a namelist specifier appears in a control list, a format specifier must not appear.
On namelist input, see Section 10.3.1.3; output, see Section 10.5.1.3.
10.2.1.4 Record Specifier
The record specifier identifies the number of the record for data transfer in a file connected for direct access. It takes the following form:
|
r
Is a scalar numeric expression indicating the record number. The value of the expression must be greater than or equal to 1, and less than or equal to the maximum number of records allowed in the file.If necessary, the value is converted to integer data type before use.
If REC is present, no END specifier, * format specifier, or namelist group name can appear in the same control list.
On an alternate form of a record specifier, see Section B.8.
The key-field-value specifier identifies the key field
of a record that you want to access in an indexed file. The key-field
value is equal to the contents of a key field. The key field can be
used to access records in indexed files because it determines their
location.
A key field has attributes, such as the number, direction, length, byte
offset, and type of the field. The attributes of the key field are
specified at file creation. Records in an indexed file have the same
attributes for their key fields.
A key-field-value specifier takes the following form:
The specifiers KEY, KEYEQ, KEYNXT, and KEYNXTNE are interchangeable
between ascending-key files and descending-key files. However, KEYNXT
and KEYNXTNE are interpreted differently depending on the direction of
the keys in the file, as follows:
The specifiers KEYGE and KEYGT can only be used with ascending-key
files, while the specifiers KEYLE and KEYLT can only be used with
descending-key files. Any other use of these key specifiers causes a
run-time error to occur.
When a program must be able to use either ascending-key or
descending-key files, you should use KEYNXT and KEYNXTNE.
To select key-field integer values, the process compares values using
the signed integers themselves.
To select key-field character values, the process compares values by
using the ASCII collating sequence.1 The comparative length
of val and a key-field value, as well as any specified
selection condition, determine the kind of selection that occurs. The
selection can be exact, generic, or approximate-generic, as follows:
If val is longer than the key-field value, no selection is
made and a run-time error occurs.
The key-of-reference specifier can optionally accompany the
key-field-value specifier. The key-of-reference specifier indicates the
key-field index that is searched to find the designated key-field
value. It takes the following form:
A value of zero indicates the primary key, a value of
1 indicates the first alternate key, a value of 2
indicates the second alternate key, and so forth.
If no kn is indicated, the default number is the last
specification given in a keyed I/O statement for that I/O unit.
10.2.1.5 Key-Field-Value Specifier
con
Is a selection condition keyword specifying how to compare val
with key-field values. The keyword can be any of the following:
In Ascending-Key Files:
Keyword
Meaning
EQ
The key-field value must be equal to
val. KEYEQ is the same as specifying KEY without the optional
con.
GE
The key-field value must be greater than or equal to
val.
GT
The key-field value must be greater than
val.
NXT
The key-field value must be the next value of the key equal to or
greater than
val.
NXTNE
The key-field value must be the next value of the key strictly greater
than
val.
In Descending-Key Files:
Keyword
Meaning
EQ
The key-field value must be equal to
val. KEYEQ is the same as specifying KEY without the optional
con.
LE
The key-field value must be less than or equal to
val.
LT
The key-field value must be less than
val.
NXT
The key-field value must be the next value of the key equal to or less
than
val.
NXTNE
The key-field value must be the next value of the key that is strictly
less than
val.
val
Is an integer or character expression. The expression must match the
type of key defined for the file. For an integer key, you must pass an
integer expression; it cannot contain real or complex data. For a
character key, you can pass either a CHARACTER expression or a BYTE
array that contains CHARACTER data.
In Ascending-Key Files
In Descending-Key Files
Specifier:
Is Equivalent to Specifier:
KEYNXT
KEYGE
KEYLE
KEYNXTNE
KEYGT
KEYLT
The process compares all the characters in val,
from left to right, with the same amount of characters in the key field
(also from left to right). Remaining key-field characters are ignored.
For example, consider that a record's key field is 10 characters
long and the following statement is entered:
READ (3, KEYEQ = 'ABCD')
In this case, the process can select a record with a key-field
value 'ABCDEFGHIJ'.
As with generic selections, the process uses only the
leftmost characters in the key field to compare values. It selects the
first key field that satisfies the generic selection criterion.
For
example, consider that a record's key field is 5 characters long and
the following statement is entered:
READ (3, KEYGT = 'ABCD')
In this case, the process can select the key-field value 'ABCEx'
(and not the key-field value 'ABCDA').
10.2.1.6 Key-of-Reference Specifier
kn
Is an integer expression indicating the key-field index. This
expression is called the key of reference. Its value
must be in the range 0 to 254.
On the key-field-value specifier, see Section 10.2.1.5.
10.2.1.7 I/O Status Specifier
The I/O status specifier designates a variable to store a value indicating the status of a data transfer operation. It takes the following form:
|
i-var
Is a scalar integer variable. When a data transfer statement is executed, i-var is set to one of the following values:
A positive integer Indicating an error condition occurred. A negative integer Indicating an end-of-file or end-of-record condition occurred. The negative integers differ depending on which condition occurred. Zero Indicating no error, end-of-file, or end-of-record condition occurred.
Execution continues with the statement following the data transfer statement, or the statement identified by a branch specifier (if any).
An end-of-file condition occurs only during execution of a sequential READ statement; an end-of-record condition occurs only during execution of a nonadvancing READ statement.
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 condition handler.
A branch specifier identifies a branch target statement that receives control if an error, end-of-file, or end-of-record condition occurs. There are three branch specifiers, taking the following forms:
|
label
Is the label of the branch target statement that receives control when the specified condition occurs.The branch target statement must be in the same scoping unit as the data transfer statement.
The following rules apply to these specifiers:
If one of the conditions occurs, no branch specifier appears in the control list, but an IOSTAT specifier appears, execution continues with the statement following the I/O statement. If neither a branch specifier nor an IOSTAT specifier appears, the program terminates.
The advance specifier determines whether nonadvancing I/O occurs for a data transfer statement. It takes the following form:
|
c-expr
Is a scalar character expression that evaluates to ' YES ' for advancing I/O or ' NO ' for nonadvancing I/O. The default value is ' YES ' .Trailing blanks in the expression are ignored.
The ADVANCE specifier can appear only in a formatted, sequential data transfer statement that specifies an external unit. It must not be specified for list-directed or namelist data transfer.
Advancing I/O always positions a file at the end of a record, unless an error condition occurs. Nonadvancing I/O can position a file at a character position within the current record.
On advancing and nonadvancing I/O, see the HP Fortran for OpenVMS User Manual.
10.2.1.10 Character Count Specifier
The character count specifier defines a variable to contain the count of how many characters are read when a nonadvancing READ statement terminates. It takes the following form:
|
i-var
Is a scalar integer variable.If PAD= ' YES ' was specified for file connection, blanks inserted as padding are not counted.
The SIZE specifier can appear only in a formatted, sequential READ
statement that has the specifier ADVANCE=
'
NO
'
(nonadvancing input). It must not be specified for list-directed or
namelist data transfer.
10.2.2 I/O Lists
In a data transfer statement, the I/O list specifies the entities whose values will be transferred. The I/O list is either an implied-do list or a simple list of variables (except for assumed-size arrays).
In input statements, the I/O list cannot contain constants and expressions because these do not specify named memory locations that can be referenced later in the program.
However, constants and expressions can appear in the I/O lists for output statements because the compiler can use temporary memory locations to hold these values during the execution of the I/O statement.
If an input item is a pointer, it must be currently associated with a definable target; data is transferred from the file to the associated target. If an output item is a pointer, it must be currently associated with a target; data is transferred from the target to the file.
If an input or output item is an array, it is treated as if the elements (if any) were specified in array element order. For example, if ARRAY_A is an array of shape (2,1), the following input statements are equivalent:
READ *, ARRAY_A READ *, ARRAY_A(1,1), ARRAY_A(2,1) |
However, no element of that array can affect the value of any expression in the input list, nor can any element appear more than once in an input list. For example, the following input statements are invalid:
INTEGER B(50) ... READ *, B(B) READ *, B(B(1):B(10)) |
If an input or output item is an allocatable array, it must be currently allocated.
If an input or output item is a derived type, the following rules apply:
The following sections describe simple list items in I/O lists, and
implied-do lists in I/O lists.
10.2.2.1 Simple List Items in I/O Lists
In a data transfer statement, a simple list of items takes the following form:
|
item
Is one of the following:
- For input statements: a variable name
The variable must not be an assumed-size array, unless one of the following appears in the last dimension: a subscript, a vector subscript, or a section subscript specifying an upper bound.- For output statements: a variable name, expression, or constant
Any expression must not attempt further I/O operations on the same logical unit. For example, it must not refer to a function subprogram that performs I/O on the same logical unit.
The data transfer statement assigns values to (or transfers values from) the list items in the order in which the items appear, from left to right.
When multiple array names are used in the I/O list of an unformatted input or output statement, only one record is read or written, regardless of how many array name references appear in the list.
The following example shows a simple I/O list:
WRITE (6,10) J, K(3), 4, (L+4)/2, N |
When you use an array name reference in an I/O list, an input statement reads enough data to fill every item of the array. An output statement writes all of the values in the array.
Data transfer begins with the initial item of the array and proceeds in the order of subscript progression, with the leftmost subscript varying most rapidly. The following statement defines a two-dimensional array:
DIMENSION ARRAY(3,3) |
If the name ARRAY appears with no subscripts in a READ statement, that statement assigns values from the input record(s) to ARRAY(1,1), ARRAY(2,1), ARRAY(3,1), ARRAY(1,2), and so on through ARRAY(3,3).
An input record contains the following values:
1,3,721.73 |
The following example shows how variables in the I/O list can be used in array subscripts later in the list:
DIMENSION ARRAY(3,3) ... READ (1,30) J, K, ARRAY(J,K) |
When the READ statement is executed, the first input value is assigned to J and the second to K, establishing the subscript values for ARRAY(J,K). The value 721.73 is then assigned to ARRAY(1,3). Note that the variables must appear before their use as array subscripts.
Consider the following derived-type definition and structure declaration:
TYPE EMPLOYEE INTEGER ID CHARACTER(LEN=40) NAME END TYPE EMPLOYEE ... TYPE(EMPLOYEE) :: CONTRACT ! A structure of type EMPLOYEE |
The following statements are equivalent:
READ *, CONTRACT READ *, CONTRACT%ID, CONTRACT%NAME |
On the general rules for I/O lists, see Section 10.2.2.
1 Other collating sequences are available. For more information, see the Guide to OpenVMS File Applications. |
| Previous | Next | Contents | Index |