Rewrite

The ReWrite (REW) statement updates an existing record in an internal or external file.

Comments and Examples

Before ReWrite can be used, an internal or external file must already be opened and assigned a file number. ReWrite can be used with internal files opened for either SEQUENTIAL,RELATIVE or KEYED processing. ReWrite can be used with external files opened for SEQUENTIAL or RELATIVE processing. ReWrite operates only when files are opened OUTIN. ReWrite must follow a successful READ or REREAD when used with a SEQUENTIAL file, when used without a REC= clause or POS= clause for RELATIVE files, and when used without a KEY clause for KEYED files. In each of these three cases, the record updated will be the last record read.

The following example is an excerpt from a program which rewrites the changed values of a GRID. REWRITE functions like WRITE, except the record already exists:

00300  RECFORM: form C 30,C 30,C 30,C 15,C 2,C 7,C 1,N 1,N 1,N 1
    ...
00880    for Index=1 to Udim(Mat Firstname$)
00890           let Thesubscriptnumber=Subscr(Index)
00900           let Therecordnumber=Recordnum(Thesubscriptnumber)
00910           rewrite #1, using RECFORM, rec=Therecordnumber: Firstname$(Index), Lastname$(Index), Address$(Index), City$(Index), State$(Index), Zipcodes$(Index), Shipmethod$(Index), Item1(Index), Item2(Index), Item3(Index)
00920     next Index
    ...

Syntax

REWRITE #<file number> [, USING {<string expression>|<line ref>}] {[, POS=<numeric expression>]|[, REC=<numeric expression>]|[, KEY=<string expression>]} [, {RESERVE|RELEASE}] : [{Mat <array name>|}][,...]  [<error condition> <line ref>][,...]

Defaults

1. Unformatted.
2. Write over the last record read.
3. Rewrite the current record and unlock all locked records for this file.
4. Interrupt the program if an error occurs and "ON error" is not active.

Parameters

"File-num" is an integer or numeric expression; it matches a REWRITE statement to a file of the same number that has already been identified in an OPEN statement.

The "USING" keyword is part of a clause that specifies either the "line-ref" of a FORM statement or a "string-expr" containing a FORM statement.

The "POS = num-expr" clause is used only with external files opened for RELATIVE processing; its purpose is to position to a specified byte before rewriting. After the numeric expression is evaluated and rounded to an integer, the system reads a complete record beginning at the specified byte number.

The "REC = num-expr" parameter is used with internal files opened for RELATIVE or KEYED processing, or with external files opened for RELATIVE access; its purpose is to specify a record by record number. After the numeric expression (usually a simple numeric variable or constant) is evaluated and rounded to an integer, the system reads and then rewrites that record number.

The "KEY = string-expr" clause is used with files opened for KEYED processing; its purpose is to specify a record by the value of its key field. After the string expression is evaluated, the system reads and then rewrites the first record that matches the key field. For complete information about the KEY clause, see the Index Facility chapter.

The "RESERVE" and "RELEASE" parameters specify record locking rules for multi-user systems. "RESERVE" instructs the system to reserve all previous record locks. "RELEASE" releases all record locks on this file as soon as the REWRITE is complete.

The "MAT array-name" and "data-item" parameters represent a list of items to be written to the old record. If more than one is specified, they must be separated by commas.

REWRITE allows error processing with the optional "error-cond line-ref" parameter. See Error Conditions for more information.

Technical Considerations

1. Relevant error conditions are: CONV, ERROR, EXIT, IOERR, LOCKED, NOKEY, NOREC, and SOFLOW.
2. On multi-user systems, the record being rewritten must be locked or an error 0062 (record not locked) will result.
3. If a "string-expr" is used with a USING clause, it must begin with "FORM ". This technique executes relatively slowly because the string is compiled on each execution of the REWRITE statement.
4. Omitting the USING clause allows unformatted file I/O. See File I/O for more information.
5. Unspecified positions in the record (e.g., skipped over by POS n or X n) remain unchanged.
6. With RELATIVE processing, the REWRITE is not affected by the previous I/O statement when a REC= clause or POS= clause is used. An implied READ REC= is performed before the REWRITE.
7. In a file opened for KEYED processing, it is possible to rewrite records by record number without disturbing the key position in the file. Using the record number for access is much faster than using a key. One caution is that you should not use REWRITE REC= if you have changed one or more key fields in a record. Since REWRITE REC= has no effect on the key files, a changed key field would prevent the key file from matching the master file.
8. With KEYED processing, the REWRITE is not affected by the previous I/O statement when a KEY clause is used. An implied READ KEY= is performed before the REWRITE.
9. "KEY=" is the only form allowed when REWRITE is used with a KEY clause. "KEY>=", "SEARCH=", and "SEARCH>=" matches are not allowed because their results (partial and "next greater" matches) are unpredictable.
10. No error results when a REWRITE statement tries to change the key field. The fields used for other keys can also be changed when multiple index files are being maintained, and the index files will be updated automatically. For more information about multiple index files, see the Index Facility chapter.
11. When OPTION INVP is in effect, the normal output of commas and periods is interchanged in PIC, N, NZ, G and GZ format specifications to produce European-style numbers. See the OPTION statement for details.
12. When REWRITING REC=, or just REWRITE after a READ REC=, to a file with indexes open, the indexes will be maintained. Previously REC= processing ignored indexes on a rewrite. A consequence of this is the undetectability of multiple opens input noshr. However, this poses no jeopardy to data. Any open requesting write permissions will not be allowed while the file is opened input noshr, and no input noshr will be allowed while the file is opened for writing, but two opens input noshr MAY be allowed on the same file at the same time. In other words in this case sharing is not blocked.