ILE COBOL Language Reference

Sequential Files

The ADVANCING and END-OF-PAGE phrases control the vertical positioning of each line on a printed page. If the printed page is held on an intermediate device (a disk, for example), the format may appear different than the expected output when it is edited or browsed.

Note:
The ADVANCING PAGE and END-OF-PAGE phrases must not both be specified in a single WRITE statement.

When an attempt is made to write beyond the externally defined boundaries of the file, the processing of the WRITE statement is unsuccessful and an EXCEPTION/ERROR condition exists. The contents of record-name are unaffected. Processing then follows the rules for error handling as described under USE Statement Programming Notes.

For sequential files on device type TAPEFILE or DISKETTE, when end-of-volume is recognized for a multivolume OUTPUT file, the WRITE statement processes the following operations in order:

  1. The standard ending volume label procedure is run.
  2. A volume switch occurs.
  3. The standard beginning volume label procedure is run.

No indication that an end-of-volume has occurred is returned to the program.

WRITE Statement - Format 1 - Sequential Files
 
>>-WRITE--record-name-1--+--------------------+----------------->
                         '-FROM--identifier-1-'
 
>--+------------------------------------------------------------+-->
   '-+-BEFORE-+--+-----------+--+-+-identifier-2-+--+-------+-+-'
     '-AFTER--'  '-ADVANCING-'  | '-integer-1----'  +-LINE--+ |
                                |                   '-LINES-' |
                                +-mnemonic-name-1-------------+
                                '-PAGE------------------------'
 
>--+-------------------------------------+---------------------->
   |          (1)                        |
   '-NULL-MAP-------+----+--identifier-9-'
                    '-IS-'
 
>--+-----------------------------------------------+------------>
   '-+----+-+-END-OF-PAGE-+-imperative-statement-1-'
     '-AT-' '-EOP---------'
 
>--+------------------------------------------------------+----->
   '-NOT--+----+--+-END-OF-PAGE-+--imperative-statement-2-'
          '-AT-'  '-EOP---------'
 
>--+-----------+-----------------------------------------------><
   '-END-WRITE-'
 
 

Notes:

  1. IBM Extension.

record-name-1

Must be defined in a Data Division FD entry. Record-name-1 may be qualified. It must not be associated with a sort or merge file.

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

Record-name-1 can be a floating-point data item.

Record-name-1 can define a DBCS data item. Identifier-1 must be a DBCS data-item if record-name-1 is a DBCS data item.

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

FROM
When FROM is specified, the result is the same as:
MOVE identifier-1 TO record-name-1
WRITE record-name-1

The move is performed according to the rules of the MOVE statement, without the CORRESPONDING phrase.

After the WRITE statement is executed, the information is still available in identifier-1, even though it may not be in record-name-1. (See INTO/FROM Identifier Phrase.)

identifier-1
Must be an alphanumeric or numeric edited data item. Data is transferred from this field to the receiving fields.

Identifier-1 can be the name of an alphanumeric or DBCS function identifier.

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

Identifier-1 can be a floating-point or date-time data item.

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

identifier-2
Must be an integer data item.

The maximum record size for the file is established at the time the file is created, and cannot subsequently be changed.

Record-name-1 and identifier-1 must not refer to the same storage area.

After the WRITE statement is executed, the record is no longer available in record-name-1, unless:

In either of these two cases, the 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 may or may 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 status key is updated when the WRITE statement is executed, whether or not execution is successful.

The WRITE statement cannot be executed for a sequential file opened in I-O mode.

Related Information:

ADVANCING Phrase

The ADVANCING phrase controls positioning of the output record on the page. It only applies to device type PRINTER. The following rules apply:

  1. When BEFORE ADVANCING is specified,

    the line is printed before the page is advanced.

  2. When AFTER ADVANCING is specified,

    the page is advanced before the line is printed.

  3. When identifier-2 is specified, the page is advanced the number of lines equal to the current value in identifier-2. Identifier-2 must be an integer data item.
  4. When integer-1 is specified, the page is advanced the number of lines equal to the value of integer-1.
  5. Integer-1 or the value in identifier-2 may be zero.
  6. When mnemonic-name is specified, a system-specific action takes place. Mnemonic-name must be equated with environment-name-1 in the SPECIAL-NAMES paragraph (valid environment-names are listed in Table 2). For more information on acceptable values for mnemonic-name, see SPECIAL-NAMES Paragraph.
  7. When PAGE is specified, the record is printed on the logical page BEFORE or AFTER (depending on the phrase used) the device is positioned to the next logical page. If PAGE has no meaning for the device used, then BEFORE or AFTER (depending on the phrase specified) ADVANCING 1 LINE is provided.

    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.

    LINAGE-COUNTER Rules: 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:

    1. If ADVANCING PAGE is specified, LINAGE-COUNTER is reset to 1.
    2. If ADVANCING identifier-2 or integer-1 is specified, LINAGE-COUNTER is increased by the value in identifier-2 or integer-1.
    3. If the ADVANCING phrase is omitted, LINAGE-COUNTER is increased by 1.
    4. When the device is repositioned to the first available line of a new page, LINAGE-COUNTER is reset to 1.

When this phrase is omitted, automatic line advancing is provided, as if the user had written AFTER ADVANCING 1 LINE.

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

NULL-MAP IS Phrase

Refer to the description supplied for this phrase on page NULL-MAP IS Phrase.

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

END-OF-PAGE Phrase

When this phrase is specified (and the FD entry for this file contains a LINAGE clause), and the logical end of the printed page is reached during execution of the WRITE statement, the imperative-statement is executed.

If an END-OF-PAGE condition does not exist after the processing of a WRITE statement with the NOT AT END-OF-PAGE phrase, control transfers to the imperative statement associated with that phrase.

Related Information:

Special Considerations for Printer Files

The keywords END-OF-PAGE and EOP are equivalent. When the END-OF-PAGE phrase is specified, the FD entry for this file must contain a LINAGE clause. When END-OF-PAGE is specified, and an END-OF-PAGE condition exists after the processing of the WRITE statement, the END-OF-PAGE imperative-statement is processed. The logical end of the printed page is specified in the LINAGE clause associated with record-name.

An END-OF-PAGE condition for a printer file is reached when the processing of a WRITE statement for that file causes printing or spacing within the footing area of a page body. This occurs when the processing of such a WRITE statement causes the value in the LINAGE-COUNTER to equal or exceed the value specified in the WITH FOOTING phrase of the LINAGE clause. The WRITE statement is processed, and then the END-OF-PAGE imperative statement is processed, if coded.

An automatic page overflow condition is reached whenever the processing of any WRITE statement with or without the END-OF-PAGE phrase cannot be completely processed within the current page body. This occurs when a processed WRITE statement 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 processed. The END-OF-PAGE condition and automatic page overflow condition occur simultaneously in the following cases:

The keywords END-OF-PAGE and EOP are equivalent.

Note:
The phrases ADVANCING PAGE and END-OF-PAGE must not both be specified in a single WRITE statement.

Special Considerations for FORMATFILEs

The keywords END-OF-PAGE and EOP are equivalent. When the END-OF-PAGE phrase is specified, and an EOP condition exists after the processing of the WRITE statement for the FORMATFILE file, the END-OF-PAGE imperative statement is processed. An EOP condition for a FORMATFILE file occurs when the logical end of page is reached during the processing of a WRITE statement for that file. The logical end of the printed page is specified in the overflow line number parameter of the CRTPRTF command or the OVRPRTF command.

END-WRITE Phrase

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 may also be used with an imperative WRITE statement.

For more information, see Delimited Scope Statements.

Multivolume Files

When end-of-volume is recognized for a multivolume OUTPUT file (tape or sequential direct-access file), the WRITE statement performs the following operations:


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]