EXEC CICS WRITE FILE ( ) From()

RIdfld() [ Keylength() ] [ Sysid() ] [ Length() ] [ RBa | RRn ] END-EXEC

WRITE writes a new record to a file on a local or a remote system.

Example:

PROCEDURE DIVISION. MOVE 111 TO WS-KEY EXEC CICS WRITE

FILE (‘FL001’) FROM (WS-REC) RIDFLD (WS-KEY) END-EXEC

Notes:

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.

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.

REWRITE

EXEC CICS REWRITE