Update a record in a file.
REWRITE
>>-REWRITE--FILE(filename)--+------------------+---------------->
'-TOKEN(data-area)-'
>--FROM(data-area)--+---------------------------------------+--->
+-SYSID(systemname)--LENGTH(data-value)-+
'-LENGTH(data-value)--------------------'
>--+-----------+-----------------------------------------------><
'-NOSUSPEND-'
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.
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
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('MASTER')
TOKEN(APTOK)