Micro Focus Studio Enterprise Edition for Windows > General Reference > COBOL Language Reference > Part 2. Program Definition > Procedure Division > Statements > The REWRITE Statement

The REWRITE Statement

The REWRITE statement logically replaces a record existing in a disk file.

General Formats for Format 1 (Line Sequential Files)

General Formats for Format 2 (Record Sequential Files)

General Formats for Format 2 (Relative and Indexed Files)

Directives and RTS switches

In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
- WRITE-LOCK - acquires a record lock for a REWRITE statement when multiple recording locking is used.
The following RTS switches may impact the semantics described in this section.
- N - controls the insertion of null characters before control characters when writing line sequential records.
- T - controls the insertion of tab characters when writing line sequential records.

Syntax Rules for All Formats (All Files)

If identifier is a function-identifier, it must reference an alphanumeric function. When identifier is not a function-identifier,
record-name and identifier must not reference the same storage area.
Record-name is the name of a logical record in the File Section of the Data Division and can be qualified.
Record-name can define a floating point or DBCS item.
Identifier can be a USAGE DISPLAY-1 (DBCS) item or a floating- point item.

Syntax Rules for Format 3 (Relative and Indexed Files)

The INVALID KEY phrase must not be specified for a REWRITE statement which references a file in sequential access mode.
However, it can be specified for an indexed file in sequential access mode.
The INVALID KEY phrase must be specified in the REWRITE statement for files in the random or dynamic access mode for which an appropriate USE procedure is not specified.

General Rules for All Formats (All Files)

The file associated with record-name must be a disk file and must be open in the I-O mode at the time of execution of this statement. (See the section The OPEN Statement.)
For files in the sequential access mode the last input-output statement executed for the associated file prior to the execution of the REWRITE statement must have been a successfully executed READ statement. The operating system logically replaces the record that was accessed by the READ statement.
The execution of a REWRITE statement with the FROM phrase is equivalent to the execution of:
```
 MOVE identifier TO record-name
```
followed by the execution of the same REWRITE statement without the FROM phrase. The contents of the record area prior to the execution of the implicit MOVE statement have no effect on the execution of the REWRITE statement.
The file position indicator is not affected by the execution of a REWRITE statement.
The execution of the REWRITE statement causes the value of the FILE STATUS data item, if any, associated with the file to be updated. (See the topic I-O Status in the chapter Procedure Division.)
The END-REWRITE phrase delimits the scope of the REWRITE statement.
A REWRITE is unsuccessful if any other run unit holds a lock on the record to be rewritten.

General Rules for Formats 1 and 2 (Sequential Files)

The number of character positions in the record referenced by record-name must be equal to the number of character positions in the record being replaced.
Note: We recommend that you do not use the REWRITE statement on compressed sequential files because a REWRITE operation will only succeed if the length of the compressed new record is the same as the length of the compressed old record.
The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause. In this case, the record is still available in the record area, not only as a record of this file, but also as a record of other files named in the SAME RECORD AREA clause.

General Rules for Format 1 (Line SequentialFiles)

The REWRITE statement can be used and is considered successful whenever the record being written (after compacting by removing trailing spaces, tab compression and null insertion) is less than or equal to the length of the original compacted record. When a record is read, nulls and tab characters in the record can be expanded and this makes the record longer.

General Rules for Format 3 (Relative and IndexedFiles)

The logical record released by a successful execution of the REWRITE statement is no longer available in the record area unless the associated file is named in a SAME RECORD AREA clause, in which case the logical record is available both as a record of other files appearing in the same SAME RECORD AREA clause as the associated I/O file, as well as the file associated with record-name.

General Rules for Format 3 (Relative Files)

For a file accessed in either random or dynamic access mode, the operating system logically replaces the record specified by the contents of the RELATIVE KEY data item associated with the file. If the file does not contain the record specified by the key, the INVALID KEY condition exists (see the topic The INVALID KEY Condition in the chapter Procedure Division), the updating operation does not take place and the data in the record area is unaffected.

General Rules for Format 3 (Indexed Files)

For a file in sequential access mode, the record to be replaced is specified by the value contained in the prime record key. When the REWRITE statement is executed, the value contained in the prime record data item of the record to be replaced must be equal to the value of the prime record key of the last record read from this file.
For a file in random or dynamic access mode, the record to be replaced is specified by the prime record key data item.
The contents of alternate record key data items of the record being rewritten can differ from those in the record being replaced. The operating system uses the contents of the record key data items during execution of the REWRITE statement so that the record can subsequently be accessed via any of those specified record keys.
The INVALID KEY condition exists when any of the following is true:
1. Access mode is sequential and the value contained in the prime record key data item of the record to be replaced is not equal to the value of the prime record key of the last record read from this file:
2. The value contained in the prime record key data item does not equal that of any record stored in the file:
3. The value contained in an alternate record key data item for which a DUPLICATES clause has not been specified is equal to that of a record already stored in the file.
The updating operation does not take place and the data in the record area is unaffected. (See the topic The INVALID KEY Condition in the chapter Procedure Division.)