The WRITE statement releases a logical record to an output or input/output file.
When the WRITE statement is executed:
For relative files, the number of character positions in the record being written can be different from the number of character positions in the record being replaced.
MOVE identifier-1 TO record-name-1. WRITE record-name-1.
The MOVE is performed according to the rules for a MOVE statement without the CORRESPONDING phrase.
identifier-1 must be a valid sending item for a MOVE statement with record-name-1 as the receiving item.
identifier-1 and record-name-1 must not refer to the same storage area.
After the WRITE statement is executed, the information is still available in identifier-1. (See INTO and FROM phrases under “Common processing facilities”.)
The ADVANCING phrase controls positioning of the output record on the page.
When you use WRITE ADVANCING with environment names C01-C012 or S01-S05, one line is advanced.
When the ADVANCING phrase is specified, the following rules apply:
If the FD entry contains a LINAGE clause, the repositioning is to the first printable line of the next page, as specified in that clause. If the LINAGE clause is omitted, the repositioning is to line 1 of the next succeeding page.
When the ADVANCING phrase is omitted, automatic line advancing is provided, as if AFTER ADVANCING 1 LINE had been specified.
If the LINAGE clause is specified for this file, the associated LINAGE-COUNTER special register is modified during the execution of the WRITE statement, according to the following rules:
When END-OF-PAGE is specified, and the logical end of the printed page is reached during execution of the WRITE statement, the END-OF-PAGE imperative-statement is executed. When the END-OF-PAGE phrase is specified, the FD entry for this file must contain a LINAGE clause.
The logical end of the printed page is specified in the associated LINAGE clause.
An END-OF-PAGE condition is reached when execution of a WRITE END-OF-PAGE statement causes printing or spacing within the footing area of a page body. This occurs when execution of such a WRITE statement causes the value in the LINAGE-COUNTER special register to equal or exceed the value specified in the WITH FOOTING phrase of the LINAGE clause. The WRITE statement is executed, and then the END-OF-PAGE imperative-statement is executed.
An automatic page overflow condition is reached whenever the execution of any given WRITE statement (with or without the END-OF-PAGE phrase) cannot be completely executed within the current page body. This occurs when a WRITE statement, if executed, would cause the value in the LINAGE-COUNTER to exceed the number of lines for the page body specified in the LINAGE clause. In this case, the line is printed BEFORE or AFTER (depending on the option specified) the device is repositioned to the first printable line on the next logical page, as specified in the LINAGE clause. If the END-OF-PAGE phrase is specified, the END-OF-PAGE imperative-statement is then executed.
If the WITH FOOTING phrase of the LINAGE clause is not specified, the automatic page overflow condition exists because no end-of-page condition (as distinct from the page overflow condition) can be detected.
If the WITH FOOTING phrase is specified, but the execution of a given WRITE statement would cause the LINAGE-COUNTER to exceed both the footing value and the page body value specified in the LINAGE clause, then both the end-of-page condition and the automatic page overflow condition occur simultaneously.
The keywords END-OF-PAGE and EOP are equivalent.
You can specify both the ADVANCING PAGE phrase and the END-OF-PAGE phrase in a single WRITE statement.
An invalid key condition is caused by the following:
When an invalid key condition occurs:
If an explicit or implicit EXCEPTION/ERROR procedure is specified for the file, the procedure is executed. If no such procedure is specified, the results are unpredictable.
The INVALID KEY conditions that apply to a relative file in OPEN OUTPUT mode also apply to one in OPEN EXTEND mode.
Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure can be omitted.
This explicit scope terminator serves to delimit the scope of the WRITE statement. END-WRITE permits a conditional WRITE statement to be nested in another conditional statement. END-WRITE can also be used with an imperative WRITE statement.
For more information, see Delimited scope statements.
The maximum record size for sequential files is established at the time the file is created and cannot subsequently be changed.
After the WRITE statement is executed, the logical record is no longer available in record-name-1 unless either:
In either of these two cases, the logical record is still available in record-name-1.
The file position indicator is not affected by execution of the WRITE statement.
The number of character positions required to store the record in a file might or might not be the same as the number of character positions defined by the logical description of that record in the COBOL program. (See PICTURE clause editing and USAGE clause.)
If the FILE STATUS clause is specified in the file-control entry, the associated file status key is updated when the WRITE statement is executed, whether or not execution is successful.
The WRITE statement can only be executed for a sequential file opened in OUTPUT mode.
Before the WRITE statement is executed for indexed files, you must set the prime record key (the RECORD KEY data item, as defined in the file-control entry) to the desired value. Note that RECORD KEY values must be unique within a file.
If the ALTERNATE RECORD KEY clause is also specified in the file-control entry, each alternate record key must be unique, unless the DUPLICATES phrase is specified. If the DUPLICATES phrase is specified, alternate record key values might not be unique. In this case, the system stores the records so that later sequential access to the records allows retrieval in the same order in which they were stored.
When ACCESS IS SEQUENTIAL is specified in the file-control entry, records must be released in ascending order of RECORD KEY values.
When ACCESS IS RANDOM or ACCESS IS DYNAMIC is specified in the file-control entry, records can be released in any programmer-specified order.
For relative record OUTPUT files, the WRITE statement causes the following actions:
The first record released has relative record number 1, the second record released has relative record number 2, the third number 3, and so on.
If the RELATIVE KEY is specified in the file-control entry, the relative record number of the record just released is placed in the RELATIVE KEY during execution of the WRITE statement.
For I-O files, either ACCESS IS RANDOM or ACCESS IS DYNAMIC must be specified; the WRITE statement inserts new records into the file. The RELATIVE KEY must contain the desired relative record number for this record before the WRITE statement is issued. When the WRITE statement is executed, this record is placed at the specified relative record number position in the file.