WRITE Statement

The WRITE statement adds a record to a file.

Format 1

WRITE record-name [ FROM source ]

   [ {BEFORE} ADVANCING { number [LINE ] } ]
     {AFTER }           {        [LINES] }
                        {      PAGE      }
                        { mnemonic-name  }         (HP COBOL)

   [ AT {END-OF-PAGE} statement-1 ]
        {EOP        }

   [ NOT AT {END-OF-PAGE} statement-2 ]
            {EOP        }

   [ END-WRITE ]

Format 2

WRITE record-name [ FROM source ]

   [ INVALID KEY statement-1 ]

   [ NOT INVALID KEY statement-2 ]

   [ END-WRITE ]

Format 3

WRITE record-name [ FROM source ] WITH NO { CONTROL    }
                                          { CONVERSION }

Syntax Rules

  1. record-name is the name of a record associated with a file described in the File Section of the Data Division. The associated file may not be a sort file.
  2. source is a data item or literal. It may not share any storage area with record-name.
  3. number is an integer numeric literal or data item. It must be non-negative.
  4. Mnemonic-name is a user-defined word that may be assigned to Special Names in the ADVANCING clause of the WRITE statement. (This is a feature of HP COBOL. See Special-Names Paragraph in Transitioning to ACUCOBOL-GT for more information.
  5. statement-1 and statement-2 are imperative statements.
  6. A Format 1 WRITE statement must be associated with a sequential file. A Format 2 WRITE statement must be associated with a relative or indexed file.
  7. The words END-OF-PAGE and EOP are equivalent.
  8. If the END-OF-PAGE phrase is used, the file description entry containing record-name must have a LINAGE clause.
  9. The ADVANCING PAGE and END-OF-PAGE phrases cannot both be used in the same WRITE statement.
  10. A Format 3 WRITE statement must be associated with a sequential file.

General Rules

  1. The file associated with record-name must be open when the WRITE statement executes. For sequential access mode files, the file must be open in the OUTPUT or EXTEND modes. For random and dynamic access mode files, the file must be open in the OUTPUT, I-O, or EXTEND mode.
  2. The WRITE statement adds the contents of record-name to the file according to the following rules:
    1. For sequential access mode files, the record is added to the end of the file. If the file is indexed, the record's primary key must contain a value that is larger than all of the primary keys currently in the file. If a relative file has a RELATIVE KEY data item specified for it, the record number of the added record is moved to this data item when the WRITE statement completes.
    2. For random and dynamic access mode files, the record is inserted into the file according to its key value. For relative files, the record is placed at the record number described by the file's RELATIVE KEY data item. For indexed files, the values of record-name's key items are used to insert the record in the file to maintain the correct key orderings.
  3. If the FROM phrase is used, the source item is moved to record-name according to the rules of the MOVE statement before record-name is written to the file.
  4. The FILE STATUS data item is updated by the WRITE statement.
  5. Some sequential files are considered to be print files. A print file has page positioning information specified in it along with the record data. A file with the PRINT option of the ASSIGN clause specified for it is a print file. A file that is referenced by any WRITE statement that contains an ADVANCING phrase is also a print file.
  6. If the ADVANCING phrase is specified, the file is treated as a print file and the following occurs:
    1. If number is positive, the representation of the printed page is advanced a number of lines equal to that value.
    2. If number is zero, no repositioning of the representation of the printed page is performed.
    3. If the PAGE phrase is used, the representation of the printed page is advanced to the next page boundary. If the associated file has a LINAGE clause specified for it, this is done by spacing the appropriate number of lines. Otherwise this is done by physically advancing the device to the top of the next physical page.
    4. If the BEFORE phrase is specified, the page advancement specified occurs after record-name is added to the file.
    5. If the AFTER phrase is used, the page advancement specified occurs before record-name is added to the file.
    6. If no ADVANCING phrase is specified, and the file is a print file, AFTER ADVANCING 1 LINE is implied.
  7. The invalid key condition exists when any of the following occur:
    1. A relative file record is written in the random or dynamic access modes, and the record number indicated by the RELATIVE KEY data item is already used by another record.
    2. An indexed file record is written and the primary key value in record-name is used by another record already in the file.
    3. An alternate key value in record-name is already being used by a record in the file, and that alternate key does not allow for duplicates.
  8. When the invalid-key condition exists, the WRITE statement is unsuccessful and the following occurs:
    1. If the INVALID KEY phrase is specified, statement-1 executes; otherwise
    2. If an appropriate USE AFTER EXCEPTION procedure exists, that error procedure executes; otherwise
    3. A message is printed and the program halts.
  9. If the WRITE statement is successful and the NOT INVALID KEY phrase is specified, statement-2 is executed.
  10. The ordering of indexed file keys for alternate keys that allow duplicates is the order in which the records are written to the file for those duplicated values.
  11. The current file position is not modified by the WRITE statement.
  12. The logical size of the record written to the file is the size of record-name. The physical size may be different due to physical characteristics of the file.
  13. If the file associated with record-name has a LINAGE clause, the following rules apply:
    1. An automatic page overflow condition occurs when the WRITE statement cannot be fully accommodated in the page body. This occurs when the WRITE statement would cause the LINAGE-COUNTER to exceed the number of lines in the page body specified by the LINAGE clause. When this happens, the line is presented before or after (depending on the phrase used) the device is positioned to the first line of the next logical page.
    2. An end-of-page condition occurs when the WRITE statement causes printing or spacing in the footing area of the page body. This occurs when the WRITE statement causes the LINAGE-COUNTER to equal or exceed the value of the FOOTING phrase of the associated LINAGE clause. If no FOOTING phrase is present, then the end-of-page condition cannot occur. Note that the end-of-page condition does not imply any automatic device positioning.
    3. If the END-OF-PAGE phrase is used, then statement-1 executes if either an automatic page overflow or an end-of-page condition exists. Otherwise statement-2 executes (if specified).
  14. The WRITE statement removes trailing spaces from record-name if the file specifies trailing-space suppression. For related information, see:
  15. A Format 3 WRITE statement writes the data in record-name to its file without any additional carriage-control information. In addition, if the NO CONVERSION option is specified, no trailing spaces are removed from the record, even if they otherwise would be. Use this to send information to devices when carriage-control is inappropriate, for example, when sending a form to a laser printer.
  16. Depending on the host environment, it is possible that records written with a Format 3 WRITE statement cannot later be retrieved with a READ statement.

For configuration variables related to the WRITE statement, see:

Parent topic: Procedure Division Statements