HP 3000 Manuals

HP COBOL II/XL Reference Manual

REWRITE Statement 

The REWRITE statement logically replaces an existing record in a
sequential, relative, random, or indexed mass storage file.  The file
position indicator is unaffected by the execution of a REWRITE statement.
Variable length records are not allowed when using the REWRITE statement.

Syntax 

There are two formats of the REWRITE statement:


            

Parameters 

record-name-1     name of a logical record in the FILE SECTION of the
                  DATA DIVISION. Record-name-1 can be qualified.  It
                  cannot refer to the same storage area as that referred
                  to by identifier-1.

identifier-1      name of a data item in the program[REV BEG] or a
                  function-identifier.  When identifier-1 is not a
                  function, it[REV END] may be described in any section
                  of the DATA DIVISION, but must not refer to the same
                  storage area as record-name-1.[REV BEG] If identifier-1 
                  is a function, it must be an alphanumeric function.[REV
                  END]

imperative-       one or more imperative statements.
statement-1 

Description 

The file associated with record-name-1 must be a mass storage file, and
must be opened in I-O mode when the REWRITE statement is executed.

The number of character positions in the record referenced by
record-name-1 must be equal to the number of character positions in the
record being replaced.

For sequential files, and for relative or indexed files open in
sequential access mode (see the SELECT statement), the last input-output
statement executed for the associated file prior to the execution of the
REWRITE statement must have been a READ statement.  The record replaced
by the REWRITE statement is the record accessed by the READ.

For indexed files, this is accomplished by using the primary key.  Thus,
the value contained in the primary record key data item of the record to
be replaced must be equal to the value of the primary record key of the
last record read from the file.  If an indexed file has the DUPLICATES
phrase specified for its primary record key, the REWRITE statement should
be used only when the indexed file is in sequential access mode.  This is
because a REWRITE statement issued for such a file whose access mode is
dynamic or random will only rewrite the first record having the duplicate
primary key.

If the primary record key data item of the record to be replaced is not
equal to the value of the primary record key of the last record read from
the file, an INVALID KEY condition exists.  In such a case, the REWRITE
operation fails and the record that was to be replaced is unaffected.
Also, if the INVALID KEY phrase is specified, control is passed to
imperative-statement-1 of that phrase, whether a USE procedure s
specified for the file or not.  If a USE procedure is not specified for
the file, the INVALID KEY phrase must be specified.  However, if a USE
procedure is specified and an INVALID KEY phrase is not, the USE
procedure is executed when an INVALID KEY condition exists for the file.

If a relative file is open in sequential access mode, the INVALID KEY
phrase must not be used.

If a random file is open, or a relative file is open in random or dynamic
access mode, the record to be logically replaced is specified by the
contents of the RELATIVE KEY or ACTUAL KEY data item associated with the
file.  If the file does not contain the record specified by the key, an
INVALID KEY condition exists.  Thus, the operation does not succeed and
the data in the record area is unaffected.  Also, if no USE procedure has
been defined for the file, the INVALID KEY phrase must be specified, and
when an INVALID KEY condition exists, control is transferred to
imperative-statement-1 of that phrase.  If a USE procedure has been
defined and the INVALID KEY phrase is not specified, the USE procedure is
executed when an INVALID KEY condition exists.  However, if both a USE
procedure and an INVALID KEY phrase are specified, the USE procedure is
ignored and control is transferred to imperative-statement-1 of the
INVALID KEY phrase. 

For indexed files open in dynamic or random access mode, the record to be
replaced is specified by the primary record key data item.  An INVALID
KEY condition exists for this type of REWRITE if the value of the primary
record key in the record to be rewritten does not equal that of any
record stored in the file.  An INVALID KEY condition also exists for this
type of REWRITE when the value contained in an alternate record key data
item equals the value of an alternate record key of another record and
the DUPLICATES clause has not been specified for that key in the SELECT
statement for that file.  The action taken for the occurrence of an
INVALID KEY condition when an indexed file is open in random or dynamic
access is the same as for when the indexed file is open for sequential
access.
[REV BEG]

For more information on handling I/O errors, see "Input-Output Error
Handling Procedures" .[REV END]

When an indexed file is the object of a REWRITE statement, the contents
of alternate record key data items of the record being rewritten may
differ from those of the record being replaced.  These alternate keys are
used during the execution of the REWRITE statement in such a way that
subsequent access of the record may be made based upon any of the
specified record keys.

The logical record written by a successful REWRITE statement is no longer
available in the record area (memory) unless the associated file (whether
indexed, relative or sequential) is named in the SAME RECORD AREA clause.

If the file is named in the SAME RECORD AREA clause, the written logical
record is available to your program as a record of other files named in
the clause, as well as to the file associated with the record to be
replaced (that is, it remains in memory).

When a REWRITE statement completes execution, whether successfully or
not, the value of the FILE STATUS data item, if any, associated with the
file being accessed in the REWRITE statement is updated.  If no exception
exists, control is transferred to the end of the REWRITE statement,  or
to the imperative statement of the  NOT INVALID KEY phrase, if specified. 
Refer to Chapter 6 , "FILE STATUS Clause", for valid combinations of
status keys 1 and 2.

FROM Phrase 

If the FROM phrase is used in a REWRITE statement, execution of the
statement is equivalent to the execution of the following MOVE statement,
followed by the execution of the same REWRITE statement without the FROM
phrase:

     MOVE identifier-1 TO record-name-1 

The contents of the record area prior to the execution of the implicit
MOVE have no effect upon the execution of the REWRITE statement.  The
REWRITE statement executed following the implicit MOVE follows the rules
and restrictions listed above.

MPE/iX 5.0 Documentation