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
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.
Note: The
only VSAM data sets greater than 4GB supported by CICS are KSDS, and then
only if they are accessed by key. CICS does not support ESDS or RRDS data
sets defined with the extended attribute.
Options
- FILE(filename)
- specifies
the 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 in the FCT. Otherwise, the FCT entry 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.
Generally, you should
not need this option because, for example, when re-writing a record to a base-only
data set, the active lock was acquired when the task issued the READ UPDATE.
However,
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.
- 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
- 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 the record has been
changed since the application program read it for for update. To successfully
update the record, repeat the read for update to get the latest version of
the record, re-apply the change, and try the rewrite again.
Default action:
terminate the task abnormally.
- 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.
- FILENOTFOUND
- RESP2
values:
- 1
- A file name referred to in the FILE option cannot be found in the FCT.
Default action: terminate the task abnormally.
- ILLOGIC
- RESP2
values: (VSAM)
- 110
- A VSAM error occurs that does not fall within one of the other CICS response
categories.
(See EIBRCODE in the EXEC interface block; refer to EXEC interface block for details.)
Default action: terminate the task abnormally.
- 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 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.
- 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 normally indicates a hardware error. (Further information is
available in the EXEC interface block; refer to EXEC interface block for
details.)
For a coupling facility data table, an IOERR indicates a
bad response returned from a coupling facility access.
Default action: terminate the task abnormally.
- ISCINVREQ
- RESP2
values:
- 70
- The remote system indicates a failure that does not correspond to a known
condition.
Default action: terminate the task abnormally.
- 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.
- 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.
- LOCKED
- RESP2
values:
- 106
- 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.
- 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.
- NOTAUTH
- RESP2
values:
- 101
- A resource security check has failed on FILE(filename).
Default action: terminate the task abnormally.
- 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 the note about active and retained locks below.)
Default action: abend the task with code AEX9.
- 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 the CICS System Definition Guide for
information about restarting a coupling facility data table server and reloading
a table.
Default action: terminate the task abnormally.
Note: 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
For example:
EXEC CICS REWRITE
FROM(RECORD)
FILE('MASTER')
TOKEN(APTOK)