WRITE

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 or VSAM extended format, extended addressing 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 relative byte address (RBA), or, for an extended addressing ESDS, the extended relative byte address (XRBA), of the new record. However, the new RBA or XRBA 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.

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.

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. The KEYLENGTH clause is required when the WRITE FILE is being function shipped, otherwise an INVREQ with RESP2=23 might occur.

LENGTH(data-value)

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

This option must be specified if SYSID is specified.

If the file is on a remote system and SYSID is not specified, 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 option must be specified for variable-length records, but is optional for fixed-length records. It is, however, advisable to specify the length of fixed-length records because this causes CICS to check that the record being written is not longer than that defined for the data set.

If an incorrect length is specified for a WRITE to a file with fixed-length records, a record of the fixed length is written and the LENGERR condition is raised. If you supply too much data, the record is truncated. If you supply too little data, the record is padded with binary zeros.

MASSINSERT

(VSAM) specifies that the WRITE command is part of a mass-insert operation, that is, a series of WRITEs each specifying MASSINSERT.

See RLS Record level locking for information about using MASSINSERT on files opened in RLS access mode.

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.

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

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.

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 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 RBA, XRBA, and RRN, you must also specify LENGTH and KEYLENGTH; they cannot be found in the resource definition.

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.

XRBA

specifies that the record identification field specified in the RIDFLD option contains an extended relative byte address. Use this option when writing to an extended addressing ESDS data set.

Conditions

84 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.

14 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.

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

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:

20

Add operations are not allowed according to the resource definition.

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

59

XRBA was specified, but the data set is not an extended addressing ESDS.

Default action: terminate the task abnormally.

17 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; for details, see EIB fields.

For VSAM files, IOERR usually 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.

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:

12

The length specified for the write operation exceeds the maximum record size; the record is truncated.

10

The LENGTH option is not specified. LENGTH must be specified for a WRITE to a file with variable-length records or to a BDAM file with records of undefined format.

14

An incorrect length is specified for a WRITE to a file with fixed-length records. A record of the fixed length has been written. If you supplied too much data, the record is truncated. If you supplied too little data, the record is padded with binary zeros.

94 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 Data tables management exits .

• 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.

100 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.

18 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.

70 NOTAUTH

RESP2 values:

101

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

Default action: terminate the task abnormally.

19 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.

101 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 for more information.

Default action: abend the task with code AEX9.

72 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.

53 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 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.