Write a record.

WRITE
>>-WRITE--FILE(filename)--+------------+--FROM(data-area)------->
'-MASSINSERT-'
>--RIDFLD(data-area)--+-----------------------+----------------->
'-KEYLENGTH(data-value)-'
>--+---------------------------------------+--+-----+----------->
+-SYSID(systemname)--LENGTH(data-value)-+ +-RBA-+
'-LENGTH(data-value)--------------------' '-RRN-'
>--+-----------+-----------------------------------------------><
'-NOSUSPEND-'
Conditions: DISABLED, DUPREC, FILENOTFOUND, ILLOGIC, INVREQ, IOERR,
ISCINVREQ, LENGERR, LOADING, LOCKED, NOSPACE, NOTAUTH, NOTOPEN, RECORDBUSY,
SUPPRESSED, SYSIDERR
Description
WRITE writes a new record to a file
on a local or a remote system.
When this command is used to write a
record to a CICS®-maintained
data table, the update is made to both the source VSAM KSDS and the in-memory
data table, unless the XDTAD user exit rejects the record from the 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 write a record to a user-maintained
data table, the update is made to the in-memory data table (unless rejected
by the XDTAD user exit).
When this command is used to write a record
to a coupling facility data table, the update is made to the data table in
the coupling facility (unless it is rejected by the XDTAD user exit).
For
a VSAM ESDS, the record is always added at the end of the data set. CICS does
not use the identification field specified in RIDFLD when calculating the
RBA of the new record, but the new RBA is returned to the application in the
record identification field specified in the RIDFLD option.
For a VSAM
KSDS, the record is added in the location specified by the associated key;
this location may be anywhere in the data set. For VSAM data sets, the key
in the record and the key in the RIDFLD identification field must be the same.
For
a VSAM ESDS or KSDS, records can be either fixed-length or variable-length.
MASSINSERT operations must proceed with ascending keys, and must be terminated
by an UNLOCK before any other request to the same data set.
Note: The
only VSAM data sets greater than 4GB (that is, defined with the extended format
/ extended addressability attribute) 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.
- KEYLENGTH(data-value)
- specifies
the length (halfword binary) of the key that has been specified in the RIDFLD
option, except when RBA or RRN is specified, in which case KEYLENGTH is not
valid. You must code KEYLENGTH if you are also using SYSID (unless you are
also using RBA or RRN). If the length specified is different from the length
defined for the data set, the INVREQ condition occurs.
- 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.
- MASSINSERT
- (VSAM)
specifies that the WRITE command is part of a mass-insert operation, that
is, a series of WRITEs each specifying MASSINSERT.
You cannot use MASSINSERT
for user-maintained or coupling facility data tables.
- 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.
A task could wait
when it issues a WRITE request if the key is for a record that is being modified,
created, or deleted by another task, because VSAM always acquires the lock
first.
- RBA
- (VSAM
ESDS base data sets only) specifies that the record identification field specified
in the RIDFLD option contains a relative byte address. Use this option only
when writing to an ESDS base. You cannot use RBA for data sets that are greater
than 4GB in size.
- RIDFLD(data-area)
- specifies
the record identification field. The contents can be a key, a relative byte
address, or relative record number (for VSAM data sets), or a block reference,
a physical key, and a deblocking argument (for BDAM data sets). For a relative
byte address or a relative record number, the format of this field must be
fullword binary. If RBA is specified, RIDFLD contains the relative byte address
(greater than or equal to zero) of the record to be written. If RRN is specified,
RIDFLD contains the relative record number (greater than or equal to 1) of
the record to be written.
See 'Identifying
BDAM records' and 'VSAM
record identification' in the CICS Application Programming Guide for
more information about defining the record identification field.
When
adding records to a keyed data set, the field must contain the complete key.
- RRN
- (VSAM
RRDS) specifies that the record identification field specified in the RIDFLD
option contains a relative record number.
- SYSID(systemname)
- specifies
the name of the system to which the request is directed.
If you specify
SYSID, and omit both RBA and RRN, you must also specify LENGTH and KEYLENGTH;
they cannot be found in the FCT.
LENGTH must either be specified explicitly
or must be capable of being defaulted from the FROM option using the length
attribute reference in assembler language, or STG and CSTG in PL/I. LENGTH
must be specified explicitly in C.
Conditions
- DISABLED
- RESP2
values:
- 50
- A file was initially defined as disabled and has not since been enabled,
or was disabled by a SET FILE or a CEMT SET FILE command.
Default action: terminate the task abnormally.
- DUPREC
- RESP2
values:
- 150
- An attempt is made to add a record to a data set by referring to a file,
or a path over a file (with the UNIQUEKEY attribute), in which the same key
already exists.
This condition is also raised for a coupling facility
data table that uses the contention model, even if another task has read the
record with the same key for update. (For a coupling facility data table that
uses the locking model, and for all other kinds of files, if another task
has read the record for update, it is locked, and the WRITE request waits
for the lock to be released, rather than returning a DUPREC response immediately.)
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:
- 20
- Add operations are not allowed according to the file entry specification
in the FCT.
- 23
- When writing records containing embedded keys, the key in the record area
(FROM option) and the key in RIDFLD do not match.
- 26
- The KEYLENGTH option is specified, and the specified length does not equal
the length defined for the data set that this file refers to.
- 38
- A WRITE with the MASSINSERT option is issued against a BDAM file.
- 40
- A BDAM key conversion error occurred.
- 44
- The WRITE command does not conform to the format of WRITE for a user-maintained
or coupling facility data table (for example, MASSINSERT or RBA is specified).
- 51
- A WRITE command specifying the RBA keyword was issued against a KSDS file
that is being accessed in RLS mode. RLS mode does not support relative byte
address access to KSDS files.
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
- There is an I/O error during the file control operation. An I/O error
is any unusual event that is not covered by a CICS condition. (Further information
is available in the EXEC interface block; refer to EXEC interface block for
details.)
For VSAM files, IOERR normally indicates a hardware error.
For
BDAM files, IOERR could mean that you are trying to write to a BDAM track
address that is not defined for the data set.
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:
- 12
- The length specified for the write operation exceeds the maximum record
size; the record is truncated.
- 10
- LENGTH is omitted for a WRITE to a file with variable-length records or
to a BDAM file with undefined format records.
- 14
- An incorrect length is specified for a write operation involving fixed-length
records.
- LOADING
- RESP2
values:
- 104
- The request cannot be satisfied because it is issued against a data table
that is still being loaded. The condition can be raised for one of the following
reasons:
If your application programs encounter the LOADING condition persistently
or too frequently, check that this is not caused by conflicting file definitions
that reference the same data set.
Default action: terminate the task abnormally.
- LOCKED
- RESP2
values:
- 106
- An attempt has been made to write a record, but a retained lock exists
against the key of this record.
Default action: abend the task with code AEX8.
- NOSPACE
- RESP2
values:
- 100
- No space is available on the direct access device for adding records to
a data set.
- 102
- The maximum number of table entries specified for the user-maintained
table or coupling facility data table has already been reached.
This condition
can also occur for a recoverable coupling facility data table when the table
apparently contains fewer than the maximum number of records allowed if there
are uncommitted updates outstanding.
- 103
- CICS is unable to get sufficient storage in the CICS address space to
create an in-memory table entry for the record being written.
- 108
- There is insufficient space in the coupling facility data table pool to
store the 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.
- NOTOPEN
- RESP2
values:
- 60
- NOTOPEN (RESP2 60) is returned for one of the following reasons:
- The requested file is CLOSED and UNENABLED. The CLOSED, UNENABLED state
is reached after a CLOSE request has been received against an OPEN ENABLED
file and the file is no longer in use. You can also make CLOSED, UNENABLED
the initial state, by specifying STATUS(UNENABLED) and OPENTIME(FIRSTREF)
on the FILE resource definition. (For BDAM files, you use the FILSTAT parameter
of the DFHFCT TYPE=FILE macro.)
- The requested file is OPEN and in use by other transactions, but a CLOSE
request against the file has been received.
- A WRITE request is issued against a data set is quiesced, or is being
quiesced, as a result of a SET DSNAME QUIESCED or IMMQUIESCED command.
- The requested file is CLOSED and ENABLED, so CICS has tried to open the
file as part of executing the request. This file open has failed for some
reason. You should examine the console for messages that explain why the file
open has been unsuccessful.
This condition does not occur if the request is made to
a CLOSED, DISABLED file. In this case, the DISABLED condition occurs.
Default
action: terminate the task abnormally.
- RECORDBUSY
- RESP2
values:
- 107
- NOSUSPEND is specified on the request but VSAM holds an active lock against
the record, which would cause the request to wait (see "Retained and active
locks" below).
Default action: abend the task with code AEX9.
- SUPPRESSED
- RESP2
values:
- 105
- A user exit program that is invoked at the XDTAD exit point decides not
to add the record to the user-maintained or coupling facility data table.
Default action: terminate the task abnormally.
- SYSIDERR
- RESP2
values:
- 130
- The SYSID option specifies a name that is neither the local CICS region
nor a remote system defined to CICS by a CONNECTION definition. 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 WRITE 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.
Retained and active locks: RECORDBUSY
refers to active locks, and LOCKED refers to retained locks:
- READNEXT requests for records that have retained locks are always
rejected with a LOCKED response.
- READNEXT 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 WRITE
FROM(RECORD)
LENGTH(DATLEN)
FILE('MASTER')
RIDFLD(KEYFLD)