WRITE

Write a record.

Read syntax diagramSkip visual syntax diagram
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.
Start of change55End of change
Start of changeNOSUSPEND is not allowed because the file is not a VSAM file that is accessed in RLS mode.End of change
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:
  • The WRITE specifies a record key that has out of range of the records so far loaded into a coupling facility data table. Records can be added while a CFDT is loading only if the specified key is within the range of those records already loaded.

    The LOADING response can also be returned for a coupling facility data table that has failed during loading. For more information about what happens if the load for a coupling facility data table fails, see the description of the XDTLC global user exit in the CICS Customization Guide.

  • A WRITE is issued to a user-maintained data table that is currently being loaded. A user-maintained data table cannot be modified during loading.

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)