WRITE

EXEC CICS WRITE
          FROM(RECORD)
          LENGTH(DATLEN)
          FILE('MASTER')
          RIDFLD(KEYFLD)

FILE(name)

Specifies the name of the CICS® file thht is to be accessed. The name must be alphanumeric, up to eight characters long, and the file must be currently ADDABLE (see INQUIRE FILE.)

If a remote SYSID is specified, the underlying file is assumed to reside on a remote system irrespective of whether the name exists in the local File Definitions (FD). Otherwise, the FD entry is used to determine whether the underlying file is on a local or a remote system.

FROM(data-area)

Specifies the record that is to be written to the file.

KEYLENGTH(data-value)

Specifies, as a 16-bit binary value, the length of the key that supplied in the RIDFLD option. If KEYLENGTH is omitted, and SYSID is also omitted, CICS obtains the length of the key if the file is local, or gets it from the KeyLen attribute in the FD entry if the file is remote. If SYSID is specified, KEYLENGTH is required; the length cannot be taken from the FD entry. For more information about using this option, see KEYLENGTH and RIDFLD.

KEYLENGTH should not be present if the record identification field that is supplied in the RIDFLD option contains either a relative byte address (use the RBA option) or a relative record number (use the RRN option).

If a specified KEYLENGTH value differs from the length defined for the underlying file, the INVREQ condition occurs.

LENGTH(data-value)

Specifies, as a 16-bit binary value, the length of the record that is to be written.

If SYSID is specified, LENGTH must be coded. You must also specify this option for a file that is defined as containing variable-length records. It need not be specified if the file contains fixed-length records, although its inclusion is recommended because this causes a check to be made that the length of the record that is being written is equal to that which is defined for the underlying file. If the lengths are not equal, the LENGERR condition occurs. For more information about using this option, see LENGTH.

MASSINSERT

This option is not supported by CICS and should not be used in applications that are developed to run under CICS. However, if this option is present (for example, in a migrated program), the translator issues a warning message and ignores the option. The matching UNLOCK command that terminates a MASSINSERT operation has no effect.

RBA

Specifies that the record identification field that is supplied in the RIDFLD option contains a relative byte address. Use this option only when writing to an ESDS.

The RBA option should not be present if the record identification field that is supplied in the RIDFLD option contains either a key (use the KEYLENGTH option) or a relative record number (use the RRN option).

RIDFLD(data-area)

Specifies the record identification field. On completion of the WRITE command, the contents can be a key, a relative byte address, or a relative record number.

For a relative byte address or a relative record number, the format of this field must be 32-bit binary; and either the RBA or the RRN option must be specified as appropriate. A relative byte address can be greater than, or equal to, zero; a relative record number can be greater than, or equal to, 1.

When adding records to a KSDS, the field must contain the complete key. For more information about using this option, see KEYLENGTH and RIDFLD .

RRN

Specifies that the record identification field that is supplied in the RIDFLD option contains a relative record number. Use this option only when writing to an RRDS.

The RRN option should not be present if the record identification field that is supplied in the RIDFLD option contains either a key (use the KEYLENGTH option) or a relative byte address (use the RBA option).

SYSID(name)

Specifies on which CICS region the WRITE is to run. The SYSID name has one through four characters. For a full description of the SYSID option, see SYSID.

If the SYSID option is not specified, it defaults to the value that is in the RemoteSysId attribute of the FD entry for the file that is requested in the FILE option.

If the SYSID option requests a remote SYSID:

• KEYLENGTH must be specified for a KSDS file because the length of the key cannot be determined from the FD entry.
• LENGTH must be specified.

DISABLED

Occurs if a file is disabled. A file might be disabled because:

• It was initially defined as disabled and has not since been enabled.
• It has been disabled by an EXEC CICS SET FILE command or by the CEMT transaction.

Default action: Terminates the task abnormally.

DUPREC

Occurs in the following conditions:

• When the application attempts to write a record with a key that matches a record that is already in the file.
• When the underlying file has an active alternate index that accepts only unique keys, and the record that is to be added for this index has a key that duplicates an existing value.

Default action: Terminates the task abnormally.

FILENOTFOUND

Occurs if the name that is specified in the FILE option cannot be found in the FD.

Default action: Terminates the task abnormally.

ILLOGIC

Occurs if an error occurs that does not fall within one of the other CICS response categories. (Further information is available in the EIBRCODE field; for details, see EXEC interface block (EIB) fields.)

Default action: Terminates the task abnormally.

INVREQ

Occurs for the following conditions, depending on the options that are specified on the WRITE command:

• Add operations are not currently allowed for the file.
• The KEYLENGTH option is specified, and the specified length differs from the length that is defined for the underlying file.
• An application attempts to write to a KSDS file from a buffer that is shorter than the key length for the underlying file.
• Following a READ UPDATE command for a file, a WRITE command is issued for a file that is referencing the same underlying file, before exclusive control is released by a REWRITE, UNLOCK, or DELETE command.
• When writing records containing embedded keys, the key that is in the record area (FROM option) and the key that is in RIDFLD do not match.
• An invalid combination of RIDFLD, RBA, and RRN is specified for the file type.

  Default action: Terminates the task abnormally.

IOERR

Occurs if an I/O error occurs 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 EIBRCODE field; for details, see EXEC interface block (EIB) fields.)

For information about handling the IOERR condition, see IOERR condition processing.

Default action: Terminates the task abnormally.

ISCINVREQ

Occurs if the remote system indicates a failure that does not correspond to a known condition.

Default action: Terminates the task abnormally.

LENGERR

Occurs for the following conditions:

• The specified length exceeds the maximum record size; the data was truncated when written.
• The specified length is smaller than the record size for a file that has fixed-length records, the data is written to the start of the record, and the remainder of the record is padded with null bytes.

Default action: Terminates the task abnormally.

NOSPACE

Occurs if no space is available on the direct access device for adding the record to the underlying file.

Default action: Terminates the task abnormally.

NOTAUTH

Occurs for the following conditions:

• When a resource security check is unsuccessful on FILE(name).
• When SYSID is specified by a transaction that is defined with the RSLCheck attribute set to either internal or external.

Default action: Terminates the task abnormally.

NOTOPEN

Occurs for the following conditions:

• 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.
• The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received. Current activity is allowed to complete, but no new activity is allowed to start.

  This condition does not occur if the request is made to either a CLOSED, ENABLED file or a CLOSED, DISABLED file. In the first case, the file is opened as part of executing the request. In the second case, the DISABLED condition occurs.

  Default action: Terminates the task abnormally.

SYSIDERR

Occurs if a problem with the communications configuration prevents the WRITE from proceeding. For example:

• The connection that is named in the SYSID option is not the name of a Communications Definition (CD) entry.
• The SYSID option references a CD entry that is incorrectly configured.
• The SYSID option references a CD entry that is marked as out of service.

It can also occur if the connection to the remote system is closed. This could be because the remote system is not available.

Default action: Terminates the task abnormally.