Function
The REWRITE statement replaces a logical record on a disk storage file.
Format 1 for sequential file organization
REWRITE record-name [FROM identifier] [END-REWRITE]
Format 2 for relative and indexed file organization
REWRITE record-name [FROM identifier]
[INVALID KEY imperative-statement-1]
[NOT INVALID KEY imperative-statement-2]
[END-REWRITE]
Syntax rules
record-name and identifier 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.
The INVALID KEY phrase must be specified for files with relative and indexed file organization unless an appropriate USE procedure has been declared. INVALID KEY may not be specified for relative files with sequential access.
The REWRITE statement is not permitted for line sequential files.
General rules
The following applies for sequential, relative and indexed file organization:
record-name identifies the record to be replaced.
The file associated with record-name must be a disk file and be open in the I-O mode at the time the REWRITE statement is executed.
Execution of a REWRITE statement with the FROM phrase is equivalent to execution of the following statements:
The content of the storage area described by record-name before the implicit MOVE statement is performed has no effect on the execution of the REWRITE statement.MOVE identifier TO record-name
REWRITE record-name.
Thus, when the FROM phrase is used, data is transferred from identifier to record-name and then released to the appropriate file.
The identifier may be used to reference any data outside the current file description entry. Transfer of data through the implicit MOVE statement takes place in accordance with the rules for a MOVE statement without the CORRESPONDING phrase. After the REWRITE statement is executed, the content of the record is still available in the area specified by identifier, although it is no longer available in the area specified by record-name.The following rules apply to all files whose access mode is sequential:
A REWRITE statement must be preceded by a successful READ statement as the last input/output statement for the associated file.
Execution of the REWRITE statement causes the record accessed by the preceding READ statement to be replaced on that file.
The contents of the data item specified by the RELATIVE KEY phrase (RELATIVE KEY for relative files; RECORD KEY for indexed files) or the RECORD KEY clause must not be modified between the READ and REWRITE statements.
A REWRITE statement must be preceded by a successful READ statement as the last input/output statement for the associated file.
Execution of the REWRITE statement causes the record accessed by the preceding READ statement to be replaced on that file.
The record rewritten by a successful REWRITE statement is no longer accessible in the record area; an exception to this rule is the use of the SAME RECORD AREA clause. In this case, the record is available to all other files specified in the SAME RECORD AREA clause as well as to the current file.
Execution of a REWRITE 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").
For relative and indexed file organization, the following also applies:
- The length of the record to be replaced on the file may be modified.
- In the case of files whose access mode is random or dynamic, the replaced record is the one accessed by the contents of the RELATIVE KEY data item associated with the file (for relative files) or by the contents of the data item specified by the RECORD KEY (for indexed files).
- The number of character positions in the record indicated by record-name must not be greater than the largest number of character positions or less than the smallest number of character positions permitted by the associated RECORD IS VARYING clause. Otherwise, the REWRITE statement will be unsuccessful, the update operation will not take place, the content of the record area remains unchanged and the I-O status of the file associated with record-name is set to a value indicating a record length conflict (see chapter "General concepts").
For sequential file organization, the following also applies: - The record addressed by the record name must be of the same length as the record to be replaced on the file.
- If the number of character positions specified in the record referenced by record-name is not equal to the number of character positions in the record being replaced, execution of the REWRITE statement is unsuccessful, the updating operation does not take place, the content of the record area is unaffected and the I-O status of the file is set to a value indicating that the record limits have been exceeded.
- Rewriting a record does not cause the record contents on the associated disk storage file to be changed until the next block of the file is read or that file is closed.
For relative file organization, the following also applies: - If the file does not contain a record corresponding to the contents of the RELATIVE KEY item, the invalid key condition occurs (see "Invalid key condition"). In this case, execution of the REWRITE statement is unsuccessful, no updating is executed, the contents of the record area remain unchanged, and the I-O status is set to a value which indicates an invalid key condition.
- The continuation of processing of the REWRITE statement depends on whether INVALID KEY or NOT INVALID KEY is specified (see "Invalid key condition").
When rewriting a record, the user should ensure that its first byte does not contain the value X’FF’, since this will cause logical deletion of the record.
For indexed file organization, the following also applies:
- The invalid key condition occurs in one of the following situations:
- in sequential access mode: if the primary key value of the record to be rewritten does not match the primary key value of the last record read from the file;
in dynamic or random access mode: if the primary key value of the record to be rewritten does not match the primary key value of any record in the file;
if the alternate record key value of the record to be rewritten is the same as the alternate record key value of a record which already exists in the file and duplicate keys are not permitted.
- For a record with an alternate key, the REWRITE statement is executed as follows:
If the value of a specific alternate key is not changed, the order in which records are retrieved remains unchanged when that key is the key of reference.
If the value of a specific alternate key is changed, the order in which records are retrieved may be changed when that key is the key of reference. If duplicates are permitted, the record becomes the last of the set of records which have the same alternate key value as the record to be rewritten.