Enterprise COBOL for z/OS, V4.2, Language Reference

WRITE statement

The WRITE statement releases a logical record to an output or input/output file.

When the WRITE statement is executed:

Read syntax diagramSkip visual syntax diagram
Format 1: WRITE statement for sequential files

>>-WRITE--record-name-1--+------------------------+------------->
                         |                    (1) |   
                         '-FROM--identifier-1-----'   

>--+-+------------------------------------------------------------+--| phrase 1 |-+-->
   | '-+-BEFORE-+--+-----------+--+-+-identifier-2-+--+-------+-+-'               |   
   |   '-AFTER--'  '-ADVANCING-'  | '-integer-1----'  +-LINE--+ |                 |   
   |                              |                   '-LINES-' |                 |   
   |                              +-mnemonic-name-1-------------+                 |   
   |                              '-PAGE------------------------'                 |   
   '-| invalid_key |--| not_invalid_key |-----------------------------------------'   

>--+-----------+-----------------------------------------------><
   '-END-WRITE-'   

phrase 1

|--+-------------------------------------------------+---------->
   '-+----+--+-END-OF-PAGE-+--imperative-statement-3-'   
     '-AT-'  '-EOP---------'                             

>--+------------------------------------------------------+-----|
   '-NOT--+----+--+-END-OF-PAGE-+--imperative-statement-4-'   
          '-AT-'  '-EOP---------'                             

invalid_key

|--+------------------------------------------+-----------------|
   '-INVALID--+-----+--imperative-statement-1-'   
              '-KEY-'                             

not_invalid_key

|--+----------------------------------------------+-------------|
   '-NOT INVALID--+-----+--imperative-statement-2-'   
                  '-KEY-'                             

Notes:
  1. The BEFORE, AFTER, INVALID KEY, and AT END OF PAGE phrases are not valid for VSAM files.
Read syntax diagramSkip visual syntax diagram
Format 2: WRITE statement for indexed and relative files

>>-WRITE--record-name-1--+--------------------+----------------->
                         '-FROM--identifier-1-'   

>--+------------------------------------------+----------------->
   '-INVALID--+-----+--imperative-statement-1-'   
              '-KEY-'                             

>--+----------------------------------------------+------------->
   '-NOT INVALID--+-----+--imperative-statement-2-'   
                  '-KEY-'                             

>--+-----------+-----------------------------------------------><
   '-END-WRITE-'   

Read syntax diagramSkip visual syntax diagram
Format 3: WRITE statement for line-sequential files

>>-WRITE--record-name-1--+--------------------+----------------->
                         '-FROM--identifier-1-'   

>----+-----------------------------------------------------------+---->
     '---AFTER----+-----------+--+-+-identifier-2-+--+-------+-+-'     
                  '-ADVANCING-'  | '-integer-1----'  +-LINE--+ |       
                                 |                   '-LINES-' |       
                                 '-PAGE------------------------'       

>--+-----------+-----------------------------------------------><
   '-END-WRITE-'   

record-name-1
Must be defined in a data division FD entry. record-name-1 can be qualified. It must not be associated with a sort or merge file.

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.

FROM phrase
The result of the execution of the WRITE statement with the FROM identifier-1 phrase is equivalent to the execution of the following statements in the order specified:
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
identifier-1 can reference any of the following:
  • A data item defined in the working-storage section, the local-storage section, or the linkage section
  • A record description for another previously opened file
  • An alphanumeric function
  • A national function

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".)

identifier-2
Must be an integer data item.

ADVANCING phrase

The ADVANCING phrase controls positioning of the output record on the page.

The BEFORE and AFTER phrases are not supported for VSAM files. QSAM files are sequentially organized. The ADVANCING and END-OF-PAGE phrases control the vertical positioning of each line on a printed page.

You can specify the ADVANCING PAGE and END-OF-PAGE phrases in a single WRITE statement.

If the printed page is held on an intermediate device (a disk, for example), the format can appear different from the expected format when the output is edited or browsed.

ADVANCING phrase rules

When the ADVANCING phrase is specified, 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 name an elementary integer data item. identifier-2 cannot name a windowed date field.
  4. When integer is specified, the page is advanced the number of lines equal to the value of integer.
  5. Integer or the value in identifier-2 can be zero.
  6. 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.

  7. When mnemonic-name is specified, a skip to channels 1 through 12, or space suppression, takes place. mnemonic-name must be equated with environment-name-1 in the SPECIAL-NAMES paragraph.

    The mnemonic-name phrase can also be specified for stacker selection with a card punch file. When using stacker selection, WRITE AFTER ADVANCING must be used.

The ADVANCING phrase of the WRITE statement, or the presence of a LINAGE clause on the file, causes a carriage control character to be generated in the record that is written. If the corresponding file is described with the EXTERNAL clause, all file connectors within the run unit must be defined such that carriage control characters will be generated for records that are written. That is, if all the files have a LINAGE clause, some of the programs can use the WRITE statement with the ADVANCING phrase and other programs can use the WRITE statement without the ADVANCING phrase. However, if none of the files has a LINAGE clause, then if any of the programs use the WRITE statement with the ADVANCING phrase, all of the programs in the run unit that have a WRITE statement must use the WRITE statement with the ADVANCING phrase.

When the ADVANCING phrase is omitted, automatic line advancing is provided, as if AFTER ADVANCING 1 LINE had been specified.

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 is specified, LINAGE-COUNTER is increased by the value in identifier-2 or integer.
  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.

Usage note: If you use the ADV compiler option, the compiler adds 1 byte to the record length in order to allow for the control character. If in your record definition you already reserve the first byte for the control character, you should use the NOADV option. For files defined with the LINAGE clause, the NOADV option has no effect. The compiler processes these files as if the ADV option were specified.

END-OF-PAGE phrases

The AT END-OF-PAGE phrase is not supported for VSAM files.

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.

INVALID KEY phrases

The INVALID KEY phrase is not supported for VSAM sequential files.

An invalid key condition is caused by the following:

  • For sequential files, an attempt is made to write beyond the externally defined boundary of the file.
  • For indexed files:
    • An attempt is made to write beyond the externally defined boundary of the file.
    • ACCESS SEQUENTIAL is specified and the file is opened OUTPUT, and the value of the prime record key is not greater than that of the previous record.
    • The file is opened OUTPUT or I-O and the value of the prime record key equals that of an already existing record.
  • For relative files:
    • An attempt is made to write beyond the externally defined boundary of the file.
    • When the access mode is random or dynamic and the RELATIVE KEY data item specifies a record that already exists in the file.
    • The number of significant digits in the relative record number is larger than the size of the relative key data item for the file.

When an invalid key condition occurs:

  • If the INVALID KEY phrase is specified, imperative-statement-1 is executed. For details of invalid key processing, see Invalid key condition.
  • Otherwise, the WRITE statement is unsuccessful and the contents of record-name are unaffected (except for QSAM files) and the following occurs:
    • For sequential files, the file status key, if specified, is updated and an EXCEPTION/ERROR condition exists.

      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.

    • For relative and indexed files, program execution proceeds according to the rules described by Invalid key condition under "Common processing facilities".

      The INVALID KEY conditions that apply to a relative file in OPEN OUTPUT mode also apply to one in OPEN EXTEND mode.

  • If the NOT INVALID KEY phrase is specified and a valid key condition exists at the end of the execution of the WRITE statement, control is passed to imperative-statement-4.

Both the INVALID KEY phrase and an applicable EXCEPTION/ERROR procedure can be omitted.

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

For more information, see Delimited scope statements.

WRITE for sequential files

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:

  • The associated file is named in a SAME RECORD AREA clause (in which case, the record is also available as a record of the other files named in the SAME RECORD AREA clause)
  • The WRITE statement is unsuccessful because of a boundary violation.

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 or EXTEND mode for QSAM files.

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:

  • The standard ending volume label procedure
  • A volume switch
  • The standard beginning volume label procedure

Punch function files with the IBM 3525

When the punch function is used, the next I-O operation after the READ statement must be a WRITE statement for the punch function file.

If you want to punch additional data into some of the cards and not into others, a dummy WRITE statement must be issued for the null cards, first filling the output area with SPACES.

If stacker selection for the punch function file is desired, you can specify the appropriate stacker function-names in the SPECIAL-NAMES paragraph, and then issue WRITE ADVANCING statements using the associated mnemonic-names.

Print function files

After the punch function operations (if specified) are completed, you can issue WRITE statements for the print function file.

If you wish to print additional data on some of the data cards and not on others, the WRITE statement for the null cards can be omitted. Any attempt to write beyond the limits of the card results in abnormal termination of the application, thus, the END-OF-PAGE phrase cannot be specified.

Depending on the capabilities of the specific IBM® 3525 model in use, the print file can be either a two-line print file or a multiline print file. Up to 64 characters can be printed on each line.

  • For a two-line print file, the lines are printed on line 1 (top edge of card) and line 3 (between rows 11 and 12). Line control cannot be specified. Automatic spacing is provided.
  • For a multiline print file, up to 25 lines of characters can be printed. Line control can be specified. If line control is not specified, automatic spacing is provided.

Line control is specified by issuing WRITE AFTER ADVANCING statements for the print function file. If line control is used for one such statement, it must be used for all other WRITE statements issued to the file. The maximum number of printable characters, including any space characters, is 64. Such WRITE statements must not specify space suppression.

Identifier and integer have the same meanings they have for other WRITE AFTER ADVANCING statements. However, such WRITE statements must not increase the line position on the card beyond the card limit, or abnormal termination results.

The mnemonic-name option of the WRITE AFTER ADVANCING statement can also be specified. In the SPECIAL-NAMES paragraph, the environment-names can be associated with the mnemonic-names, as shown in the following table:

Table 1. Meanings of environment-names in SPECIAL NAMES paragraph
environment-name Meaning
C02 Line 3
C03 Line 5
C04 Line 7
C05 Line 9
... ...
C22 Line 21
C12 Line 23

Advanced Function Printing

When you use the WRITE ADVANCING phrase with a mnemonic-name associated with environment-name AFP-5A, a Print Services Facility™ (PSF) control character is placed in the control character position of the output record. This control character (X'5A') allows Advanced Function Printing (AFP) services to be used. For more information, refer to the documentation for the Print Services Facility product: PSF for OS/390® & z/OS (5655-B17).

WRITE for indexed files

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.

WRITE for relative files

For relative record OUTPUT files, the WRITE statement causes the following actions:

  • If ACCESS IS SEQUENTIAL is specified:

    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.

  • If ACCESS IS RANDOM or ACCESS IS DYNAMIC is specified, 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.

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.



Rate this page

[ Index | Table of contents ]