Function
The WRITE statement causes a record to be released to an output file.
Format 1 can also be used to control form feeds in print files.
Format 1 for sequential file organization
WRITE record-name [FROM identifier-1]
[{AFTER | BEFORE} ADVANCING{{identifier-2 | integer} [LINES | LINE] | {mnemonic-name | PAGE}}]
[AT {END-OF-PAGE | EOP} imperative-statement-1]
[NOT AT {END-OF-PAGE | EOP} imperative-statement-2]
[END-WRITE]
Syntax rules
record-name and identifier-1 must not refer to the same storage area.
record-name must be associated with a file description (FD) entry in the Data Division of the program and may be qualified.
record-name must not be part of a sort file.
If identifier-2 is used in the ADVANCING phrase, it must be the name of an elementary integer data item.
The value of integer or the data item referenced by identifier-2 must be greater than or equal to zero, but not greater than 15.
For files with the ASSIGN entry PRINTER literal-1, integer must be greater than 15 and less than 100.
If END-OF-PAGE or NOT END-OF-PAGE is used, a LINAGE clause must be present as part of the file description entry for the corresponding file (see section "LINAGE clause").
The EOP and END-OF-PAGE phrases are equivalent.
mnemonic-name, if specified, must have an entry associated with it in the SPECIAL-NAMES paragraph.
mnemonic-name must not be supplied in the ADVANCING phrase if a LINAGE clause was specified for the file referenced in the WRITE statement.
ADVANCING PAGE and END-OF-PAGE may not be specified together in a single WRITE statement.
General rules
The record supplied by a WRITE statement is no longer available in the record area, unless the file associated with the record was specified in a SAME RECORD AREA clause or the execution of the WRITE statement was unsuccessful. The record is also available to any other files which may have been referenced in any SAME RECORD AREA clause together with the specified file.
Execution of a WRITE statement with the FROM phrase is equivalent to the execution of the following statements:
MOVE identifier-1 TO record-name
the same WRITE statement without the FROM phraseData is transferred according to the rules for a MOVE statement without the CORRESPONDING phrase.
The content of the record area before execution of the implicit MOVE statement has no effect on the execution of the WRITE statement.
After the WRITE statement is successfully executed, the information is still available in the area referenced by identifier-1; however, as pointed out in general rule 1, this is not necessarily true for the record area.
If the end-of-volume condition is encountered on a multi-volume output file for tape or disk storage and sequential access mode, the following steps will be performed during execution of the WRITE statement:
The standard volume header label procedures and the user volume trailer label procedures specified via a USE procedure are performed. The order in which these procedures are executed depends on the BEFORE/AFTER phrases supplied in the USE procedure, if any.
A volume swap is effected.
The standard volume header label procedures and the user volume header label procedures specified via a USE procedure are performed. The order in which these procedures are executed depends on the BEFORE/AFTER phrases supplied in the USE procedure, if any.
After execution of a WRITE statement, the value of the data item of any FILE STATUS clause existing for that file is updated (see also "FILE STATUS clause").
If a file is open in extend mode, the WRITE statement causes records to be added to the end of the file as if the file were open in output mode. The first record written after execution of the OPEN EXTEND statement is the successor of the last record in the file.
If the VARYING phrase has been specified for the file associated with record-name, the number of character positions in the record referenced by record-name must not be larger than integer-3 or smaller than integer-2 (see section "RECORD clause"). If no RECORD clause is specified with the VARYING phrase, the number of character positions must not be longer than the largest record (as determined by the record description entry) of the associated file. If either of these cases occur, the WRITE statement is unsuccessful, and the WRITE operation does not take place. The content of the record area remains unchanged. The I-O status of the file associated with record-name is set to a value indicating the cause of the condition (see section "I-O status").
Both the ADVANCING and the END-OF-PAGE phrases allow control of the vertical positioning of each individual line on a representation of a printed page.
When the BEFORE/AFTER ADVANCING phrase is used, the corresponding record is printed before or after the page is advanced according to the rules described below.
If the end-of-page condition does not occur during the execution of a WRITE statement with the NOT END-OF-PAGE phrase, control is transferred to imperative-statement-2 if the WRITE statement is executed successfully. The transfer of control takes place after the record is written and after updating of the I/O status of the file from which the record originates.
If the execution of the WRITE statement is unsuccessful, the I/O status of the file is updated, then the USE procedure specified for this file is executed, and finally control is transferred to the imperative-statement-2.
The ADVANCING phrase causes the representation of the printed page to be advanced according to the following rules:
If identifier-2, integer or mnemonic-name is present, the page is advanced in accordance with the rules specified in table 34.
If PAGE is present, the record is printed either before or after positioning to the beginning of the first line on a new page. The beginning of a new page is defined either by the physical properties of the printer (advance to channel 1) or, if a LINAGE clause is present, by the beginning of the next logical page (see section "LINAGE clause").
If the ADVANCING phrase is omitted, a WRITE...AFTER ADVANCING 1 LINE will be executed for files with the ASSIGN specification PRINTER or PRINTER literal-1 (see also table 35).
If the end of a logical page is encountered during execution of a WRITE statement with the END-OF-PAGE phrase, control is transferred to imperative-statement-1. The logical end of a page is defined by the LINAGE clause in the file description entry of the file.
An END-OF-PAGE condition occurs when the execution of a WRITE statement with the END-OF-PAGE phrase causes printing or spacing within the page footing area. This is the case whenever, during the execution of such a WRITE statement, the value of the special register LINAGE-COUNTER becomes equal to or greater than the value of integer-2 of the LINAGE clause data item referenced by data-name-2. In this case, the WRITE statement is executed, and control is then transferred to the imperative statement which follows the END-OF-PAGE phrase.
An automatic page overflow condition occurs when the execution of a given WRITE statement (with or without an END-OF-PAGE phrase) cannot be fully accommodated within the current page body.
This is the case whenever, during the execution of such a WRITE statement, the value of the special register LINAGE-COUNTER becomes equal to or greater than the value of integer-1 or the LINAGE clause data item referenced by data-name-1. In this case, the record is printed either before or after positioning to the first line of the next logical page (depending on the BEFORE/AFTER phrase). This line is defined by specification of the LINAGE clause. The imperative statement specified in the END-OF-PAGE phrase is executed after the record has been written and the device repositioned.
If the integer-2 or data-name-2 phrases of the LINAGE clause are not used, the END-OF-PAGE condition will occur whenever a WRITE statement is executed (with EOP phrase specified) and the value in the special LINAGE-COUNTER register is greater than or equal to the value of integer-1 or the LINAGE clause data item referenced by data-name-1.
If integer-2 or data-name-2 is specified in the LINAGE clause but execution of a WRITE statement would result in the value of the LINAGE-COUNTER being both
equal to or greater than the value of data-name-2 or integer-2, and
equal to or greater than the value of data-name-1 or integer-1
processing proceeds as if integer-2 or data-name-2 had not been specified.
When the ADVANCING phrase is used together with the LINAGE clause for a device which does not represent a physical printer, any blank lines at the top and bottom margins as well as within the page body are represented on the appropriate storage medium as records containing blank characters.
Execution of a WRITE statement which attempts to write outside the physical boundaries of a file results in an exception condition. The following steps are performed:
The value of the FILE STATUS data item of the file is set to indicate violation of the boundaries of the file (see section "FILE STATUS clause").
Any USE ERROR/EXCEPTION procedure that is explicitly or implicitly specified for this file will be executed.
If there is neither an explicit nor an implicit USE procedure for this file, the program will terminate abnormally.
When a WRITE statement is executed, the file must have been opened with an OPEN statement containing the OUTPUT or EXTEND phrase.
Table 36 gives precise detail of the use of the first character in the record, depending on the symbolic device names of the ASSIGN clause and the WRITE statement phrases.
When a WRITE statement is used with AFTER-ADVANCING phrase, the printer is positioned to the line requested and is advanced one additional line after printing.
If PRINTER literal-1 is specified in the ASSIGN phrase, a WRITE AFTER phrase is performed as follows:
An empty record is printed with corresponding form-feed specification (WRITE BEFORE).
The record is written.
For all devices, form-feed suppression is only possible when the WRITE BEFORE phrase is specified.
Example 8-88
The file LOADFILE is read and written to the print file called AFILE.
Each current record is written before advancing 5 blank lines.
IDENTIFICATION DIVISION.
PROGRAM-ID. WP1.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT AFILE ASSIGN TO PRINTER "PRINTOUT".
SELECT LOADFILE ASSIGN TO "MASTER-FILE".
DATA DIVISION.
FILE SECTION.
FD AFILE
LINAGE IS 24 LINES
LINES AT TOP 24
LINES AT BOTTOM 24.
01 CUSTMRREC PIC X(95).
FD LOADFILE
LABEL RECORD IS STANDARD.
01 CUSTREC.
05 CNA PIC X(30).
05 STR PIC X(20).
05 LOC PIC X(20).
05 ZIP PIC X(5).
05 TYP PIC X(20).
WORKING-STORAGE SECTION.
01 FILE-SWITCH PIC X VALUE LOW-VALUE.
88 EOF VALUE HIGH-VALUE.
PROCEDURE DIVISION.
MAIN SECTION.
FILE-OPEN.
OPEN OUTPUT AFILE.
OPEN INPUT LOADFILE.
READS.
PERFORM UNTIL EOF
READ LOADFILE INTO CUSTMRREC
AT END
CLOSE AFILE LOADFILE
SET EOF TO TRUE
NOT AT END
WRITE CUSTMRREC BEFORE ADVANCING 5.
END-READ
END-PERFORM
STOP RUN.
Indicator | Format | Action | |
identifier-2 | Numeric integer with a value in the range from 01 to 15 | n-line spacing | |
identifier-2 | Alphanumeric data item, length 1 (PIC X). Following values are valid: blank 0 - + 1-8 A B | Single-spacing Double-spacing Triple-spacing Suppress spacing Skip to channel 1-8 Skip to channel 10 Skip to channel 11 | |
integer | Numeric literal in the range 01 to 15 | n-line spacing | |
mnemonic-name | A name related to an implementor-name in a SPECIAL-NAMES paragraph. | implementor-name | Action |
C01 through C08 | Skip to channel 1-8 | ||
Table 34: Meaning and result of spacing indicators in a WRITE ADVANCING statement
Symbolic device name | WRITE statement without ADVANCING phrase | WRITE statement with ADVANCING phrase | Comments |
PRINTER literal | Standard spacing when ADVANCING is omitted as if AFTER 1 LINE had been specified; the first character of the record is available for user data. | The first character of the record is available for user data. | The place for the carriage control character is reserved by the compiler and is not accessible to the user. This type of printer supports specification of the LINAGE clause in the file description entry. WRITE statements both with and without the ADVANCING phrase specified are allowed for a given file. |
PRINTER | As above. | As above. | The place for the carriage control character is reserved by the compiler and is not accessible to the user. The LINAGE clause is not permitted for this file. Use of WRITE statements with and without the ADVANCING phrase for the same file is not permitted. If this does occur, a WRITE AFTER ADVANCING is executed implicitly for the records without the ADVANCING phrase. |
literal | Spacing is controlled by the first character in each logical record; the user must therefore supply the appropriate control character before every execution of such WRITE statement. | The user must reserve the first character of a logical record; the runtime system inserts the feed control character of the record program execution. Any user data there will be overwritten. | Mixed use of WRITE statements both with and without specifications of the ADVANCING phrase is permitted. In either case, however, the user information of the printer record begins only with the second character of the record. |
Table 35: Use of symbolic device names for printers in connection with the WRITE statement
Format 2 for relative and indexed file organization
WRITE record-name [FROM identifier-1] [INVALID KEY imperative-statement-1] [NOT INVALID KEY imperative-statement-2] [END-WRITE]Syntax rules
record-name and identifier-1 must not reference the same storage area.
record-name must be associated with a file description (FD) entry in the Data Division of the program and may be qualified.
The INVALID KEY phrase must be specified for a file unless an applicable USE procedure was declared.
General rules
For relative and indexed file organization, the following also applies:
The file whose record is referenced by the WRITE statement must be open in the OUTPUT, I-O or EXTEND mode.
The record released by a WRITE statement is no longer available in the record area, unless the file associated with the record was specified in a SAME RECORD AREA clause, or the execution of the WRITE statement was abnormally terminated as unsuccessful because of the occurrence of an invalid key condition. The record is also available to those files which were referenced in a SAME RECORD AREA clause together with the specified file.
Execution of a WRITE statement with the FROM phrase is equivalent to execution of the following statements:
MOVE identifier-1 TO record-name
the same WRITE statement without the FROM phraseData is transferred according to the rules for a MOVE statement without the CORRESPONDING phrase.
The contents of the record area before execution of the implicit MOVE statement has no effect on the execution of the WRITE statement.
Execution of a WRITE statement causes the contents of the data item that was specified in the FILE STATUS clause of the related file description entry to be updated (see also section "FILE STATUS clause").
If, during the execution of a WRITE statement with the NOT INVALID KEY phrase, the invalid key condition does not occur, control is transferred to imperative-statement-2 as follows:
If the execution of the WRITE statement is successful: after the record is written and after updating the I/O status of the file from which the record originates.
If the execution of the WRITE statement is unsuccessful: after the I/O status of the file has been updated and after executing the USE procedure that was specified for the file from which the record originates.
Occurrence of an invalid key condition indicates that the WRITE statement was unsuccessful; the contents of the record area are still available, and any existing FILE STATUS data item in that file is set to a value indicating the cause of the invalid key condition. The program resumes execution in accordance with the rules for the invalid key condition.
The number of character positions in the record referenced by record-name must not be larger than the largest or smaller than the smallest number of character positions allowed by the associated RECORD IS VARYING clause. Otherwise, the WRITE statement is unsuccessful, the WRITE operation does not take place, the content of the record area is unaffected and the I-O status of the file associated with record-name is set to a value indicating a record length conflict (see section "I-O status").
For relative file organization, the following also applies:When a WRITE statement is executed, the position within the file of the record to be output is located by means of the contents of the RECORD KEY data item. Before the WRITE statement is executed, the content of the associated key field must be set accordingly (see RELATIVE KEY in section "ACCESS MODE clause").
If a file is opened in output mode (OPEN statement with OUTPUT phrase), the following should be noted:
In sequential access mode, the WRITE statement causes output of a record for creation of a new file. The first record is assigned a relative record number of 1 (one) while the subsequent records are numbered 2, 3, 4,... If RELATIVE KEY was specified, the File Control Processor will enter the relative record number in the RELATIVE KEY phrase during the execution of the write statement.
In random or dynamic access modes (which are equivalent for OUTPUT), the value of the data item in the (here mandatory) RELATIVE KEY phrase must be set by the user to equal the relative record number which is to be assigned to the record contained in the record area. That record is then output as the nth record of the file, where "n" is the value of the relative record number.
If a file is in extend mode (OPEN statement with EXTEND phrase), a WRITE statement causes a record to be appended to the file. The first record released in this manner receives a relative record number which is 1 higher than the highest existing relative record number in the file. The relative record number of each subsequent record is incremented by 1 (with respect to the previous record). If the RELATIVE KEY phrase is specified, the relative record number of the MOVE statement is transferred to the record key field with each WRITE statement.
If a file is opened in update mode (OPEN statement with I-O phrase), and its access mode is either random or dynamic (which means the same in this case), the WRITE statement inserts records in the associated existing file. The value of the data item of the (here mandatory) RELATIVE KEY phrase must be set by the user to equal the relative record number which is to be assigned to the record contained in the record area. As the WRITE statement is executed, the contents of the record with the appropriate record number are transferred to the File Control Processor.
The invalid key condition is caused by the events listed in table 36.
ACCESS MODE clause
OPEN mode and action taken
Reason for INVALID KEY condition
SEQUENTIAL
OUTPUT or EXTEND
A record is appended to an existing or newly created file.There is no room in the file for the new record.
RANDOM
or
DYNAMICOUTPUT or I-O
A record is appended to an existing file.The content of the RELATIVE KEY field specifies a record which already exists in the file or there is no room in the file for the new record.
Table 36: WRITE statement - Causes of invalid key conditions
For indexed file organization, the following also applies:When a WRITE statement is executed, the position within the file of the record to be output is located by means of the contents of the RECORD KEY data item. Before the WRITE statement is executed, the content of the associated key field must be set accordingly (see RELATIVE KEY in section "RECORD KEY clause").
If a file is opened in output mode (OPEN statement with OUTPUT phrase), the following should be noted:
In sequential access mode, the WRITE statement releases a record for the creation of a new file. In this context, the records must be transferred in ascending order of RECORD KEY values. Before execution of the WRITE statement, the RECORD KEY data item must be set to the required value.
In random or dynamic access modes (which are equivalent for OUTPUT), records may be released to the File Control Processor in any program-specified order.
The invalid key condition is caused by the events listed in table 37.
Access mode
OPEN mode and action taken
Cause of invalid key condition
SEQUENTIAL
OUTPUT / EXTEND
A record is added to a file to be newly created.
("load mode").Either the value of the primary key is not greater than that of the preceding record (the primary record keys must be sorted in ascending alphanumeric order), or
no more space is available in the file for writing the record.RANDOM
or
DYNAMICOUTPUT/ I-O / EXTEND
A record is added to an existing fileThe record has the same primary key value as a record already existing in the file, or
no more space is available on the file for writing the record, or
an alternate key value for which duplicates are not permitted already exists in a record in the file.Table 37: WRITE statement - Causes of invalid key conditions
If the file was opened in extend mode, the first record passed to DMS must have a primary key whose value is higher than the highest existing primary key value in the file.
If ALTERNATE RECORD KEY WITH DUPLICATES is specified, the alternate key value of the record does not need to be unique.