REWRITE

Update a record in a file.

REWRITE

Conditions: CHANGED, DUPREC, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LENGERR, LOCKED, NOSPACE, NOTAUTH, NOTFND, RECORDBUSY, SYSIDERR

This command is threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over an IPIC connection to a remote CICS® region.
Defined as either local VSAM or RLS.

This command is not threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over a non-IPIC connection.
Defined as a shared data table, coupling facility data table, or BDAM file.

Description

REWRITE updates a record in a file on a local or a remote system. You must always precede this command with a read with the UPDATE option.

For VSAM data sets, you must not change the key field in the record.

When this command is used to update a record in a CICS-maintained data table, the update is made to both the source VSAM KSDS and the in-memory data table. The details of the command for a CICS-maintained table are the same as for a VSAM KSDS.

When this command is used to update a record in a user-maintained data table, the update is made to the in-memory data table.

When this command is used to update records in a coupling facility data table, the update is made only to the data table in the coupling facility.

If an update to a user-maintained table or coupling facility data table does not succeed because there is insufficient space, a NOSPACE response is returned to the command. CICS also issues message DFHFC0432 to alert system administrators to the situation.

Options

FILE(filename)

specifies the name of the file to be accessed.

If SYSID is specified, the data set to which this file refers is assumed to be on a remote system irrespective of whether the name is defined to CICS. Otherwise, the resource definition is used to find out whether the data set is on a local or a remote system.

FROM(data-area)

specifies the record that is to be written to the data set referred to by this file.

LENGTH(data-value)

specifies the length, as a halfword binary value, of the data area where the record is written from.

This option must be specified if SYSID is specified.

If the file is on a remote system, the LENGTH parameter need not be set here but must be set in the file resource definition.

If the file is on a local system, the LENGTH parameter must be set for variable-length records, using the INTO option, but not for fixed-length records. It is, however, advisable to specify the length for fixed-length records because it causes a check to be made that the record being written is not longer than that defined for the data set.

NOSUSPEND (RLS only)

The request does not wait if VSAM is holding an active lock against the record, including records locked as the result of a DEADLOCK.

Lock contention can occur if the update involves changes made in RLS mode to records in a VSAM data set that has one or more alternate indexes, and an alternate index is defined with unique keys.

In most other cases, you should not need this option because the active lock is acquired when the task issues the READ UPDATE command.

Note: Requests that specify NOSUSPEND wait for at least 1 second before CICS returns the RECORDBUSY response.

SYSID(systemname)

specifies the name of the system to which the request is directed.

TOKEN(data-area)

specifies as a fullword binary value a unique request identifier for a REWRITE, used to associate it with a previous READ, READNEXT, or READPREV command that specified UPDATE.

TOKEN can be function shipped. However, if a request specifying TOKEN is function shipped to a member of the CICS family of products that does not support the TOKEN option, the request fails:

Conditions

105 CHANGED

RESP2 values:

109: A REWRITE command is issued for a file that is a defined as a coupling facility data table using the contention update model, and for which the record has been changed since the application program read it for update. To successfully update the record, repeat the READ for UPDATE to get the latest version of the record, reapply the change, and try the rewrite again.
Default action: terminate the task abnormally.

14 DUPREC

RESP2 values:

150: An attempt is made to rewrite a record to a data set whose upgrade set has an alternate index with the UNIQUEKEY attribute, if the corresponding alternate key already exists in the alternate index.

Default action: terminate the task abnormally.

12 FILENOTFOUND

RESP2 values:

1: A file name referred to in the FILE option is not defined to CICS.

Default action: terminate the task abnormally.

21 ILLOGIC

Any browse that is currently in progress is terminated when this condition is raised.

RESP2 values: (VSAM)

110: A VSAM error occurs that is not in one of the other CICS response categories.
See EIBRCODE in the EXEC interface block; for details, see EIB fields.

Default action: terminate the task abnormally.

16 INVREQ

RESP2 values:

30: A REWRITE command is issued without a token and no previous READ for UPDATE (also without a token) can be found.
A possible reason for the previous READ for UPDATE not being found is that it failed for some reason, and the failure has not been correctly handled or has been ignored.
46: A REWRITE command has attempted to change the length of a BDAM variable length record or block.
47: A REWRITE instruction includes a token whose value cannot be matched against any token that is in use for an existing READ for UPDATE request.
55: NOSUSPEND is not allowed because the file is not a VSAM file that is accessed in RLS mode.
56: An attempt to update a recoverable coupling facility data table has failed because the current unit of work has already updated 1024 recoverable coupling facility data tables. You cannot update more than 1024 recoverable coupling facility data tables within a unit of work
57: REWRITE operations are not allowed because the associated VSAM data set has an AVAILABILITY state of RREPL, which disallows such operations except those from replication programs.

Default action: terminate the task abnormally.

17 IOERR

RESP2 values:

120

An I/O error occurred during the file control operation. An I/O error is any unusual event that is not covered by a CICS condition.

For VSAM files, IOERR usually indicates a hardware error. Further information is available in the EXEC interface block; for details, see EIB fields.

For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.

Default action: terminate the task abnormally.

54 ISCINVREQ

RESP2 values:

70: The remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

22 LENGERR

RESP2 values:

10: The LENGTH option is not specified for a file with variable-length records, or for a BDAM file with undefined format records.
12: The length specified exceeds the maximum record size (of the source data set for a data-table); the record is truncated.
14: An incorrect length is specified for a file with fixed-length records.

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

80: For user-maintained data tables, this condition occurs when an attempt to REWRITE a record has failed because the REWRITE is associated with a READ UPDATE request for a record that this transaction has deleted (using DELETE with RIDFLD) after it was read for update. This may be caused by a logic error in the application program.
This condition can also occur when a REWRITE command is issued to a coupling facility data table using the contention model and the record has been deleted since it was read for update.

Default action: terminate the task abnormally.

100 LOCKED

RESP2 values:

106: An attempt has been made to update a record, but a retained lock exists against a unique alternate key that is involved in the request.

Default action: abend the task with code AEX8.

18 NOSPACE

RESP2 values:

100: No space is available on the direct access device for adding the updated record to the data set.
102: The maximum number of records specified for a recoverable coupling facility data table has been exceeded. This can occur on a rewrite operation because an extra record is required in the coupling facility data table for recovery purposes until the update has been committed.
103: For user-maintained data tables, this condition occurs if CICS is unable to get sufficient storage in the CICS address space to store the updated data table entry.
108: For coupling facility data tables, this condition occurs if there is insufficient space in the coupling facility data table pool to store the updated record.

Default action: terminate the task abnormally.

70 NOTAUTH

RESP2 values:

101: A resource security check has failed on FILE(filename).

Default action: terminate the task abnormally.

101 RECORDBUSY

RESP2 values:

107: NOSUSPEND is specified but VSAM holds an active lock against a unique alternate index key that is involved in the request, which would cause the request to wait. See Retained and active locks for more information.

Default action: abend the task with code AEX9.

53 SYSIDERR

RESP2 values:

130: The SYSID option specifies a name that is neither the local system nor a remote system (made known to CICS by defining a CONNECTION). SYSIDERR also occurs when the link to the remote system is closed.
131: For a coupling facility data table, the connection to the coupling facility data table server has failed. This could be because the server itself has failed, or the server is available, but CICS has failed to connect to it.
132: The REWRITE is issued against a coupling facility data table that no longer exists, probably because of a coupling facility failure, in which case the coupling facility data table server also fails. See Setting up and running a coupling facility data table server for information about restarting a coupling facility data table server and reloading a table.

Default action: terminate the task abnormally.

Retained and active locks: RECORDBUSY refers to active locks and LOCKED refers to retained locks:

REWRITE requests for records that have retained locks are always rejected with a LOCKED response.
REWRITE requests for records that have active locks wait for the lock to be released, except when the NOSUSPEND keyword is specified, in which case CICS returns the RECORDBUSY response.

Examples

Here is an example of a simple REWRITE command:

EXEC CICS REWRITE
     FROM(RECORD)
     FILE('MAIN')
     TOKEN(APTOK)