FILE WRITE

FILE WRITE

The CICS FILE WRITE statement is used to insert (write) a new record into a VSAM dataset or a CICS-maintained file. It is commonly used to store new customer records, transactions, or logs in a VSAM file. Records can be either fixed-length or variable-length for a VSAM ESDS or KSDS.

Key Features -

  • Writes a new record to a file in VSAM KSDS (Key-Sequenced Dataset), ESDS (Entry-Sequenced Dataset), or RRDS (Relative Record Dataset).
  • To ensure efficient file handling within a CICS environment.

Syntax -

EXEC CICS WRITE
     FILE('file-name')
     FROM(data-area)
     [LENGTH(length)]
     [RIDFLD(record-id)]
     [KEYLENGTH(key-length)]
	 [MASSINSERT]
	 [SYSID(system-name)]
	 [RBA|RRN|XRBA]
     [RESP(response-field)]
     [RESP2(response-field2)]
     END-EXEC.
  • FILE('file-name') - Specifies the name of the VSAM file or dataset to which data is written.
  • FROM(data-area) - Defines the data area that holds the new record.
  • LENGTH(length) - Specifies the length of the record being written. (Required for variable-length records)
  • RIDFLD(record-id) - Specifies the record identification field, which can contain a key, a relative byte address, a relative record number (for VSAM data sets), a block reference, a physical key, or a deblocking argument (for BDAM data sets).
  • KEYLENGTH(key-length) - Defines the key length. KEYLENGTH is not valid when RBA or RRN is coded. KEYLENGTH must be coded if using SYSID.
  • MASSINSERT - Specifies the series of WRITEs performing on the dataset.
  • SYSID(system-name) - Specifies the system name to which the request is directed. If SYSID coded and omit RBA, XRBA and RRN, LENGTH and KEYLENGTH must be coded.
  • RBA|RRN|XRBA - Specifies the type of the file and data in the RIDFLD.
  • RESP(response-variable) - Optional. It captures the response code of the WRITE operation and used to check if the command executed successfully or encountered an error.
  • RESP2(response2-variable) - Optional. It captures the response2 code of the WRITE operation when the error occured.

Short Examples -

Scenario1 - Writing a New Record to a KSDS File.

...
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-CUSTOMER-RECORD.
   05 WS-CUST-ID        PIC X(10).
   05 WS-CUST-NAME      PIC X(30).
   05 WS-CUST-ADDRESS   PIC X(50).
   05 WS-CUST-PHONE     PIC X(15).
   
...
PROCEDURE DIVISION.

    MOVE "12345" TO WS-CUST-ID.
    MOVE "John Doe" TO WS-CUST-NAME.
    MOVE "123 Main Street, NY" TO WS-CUST-ADDRESS.
    MOVE "9876543210" TO WS-CUST-PHONE.
		 

    EXEC CICS WRITE
         FILE('CUSTFILE')
         FROM(WS-CUSTOMER-RECORD)
         RESP(WS-RESP)
         END-EXEC.

    IF WS-RESP NOT = 0 THEN
       ...
	END-IF.
	
    ...

The data is placed in WS-CUSTOMER-RECORD before writing. The WRITE command is executed with the FILE name CUSTFILE.

Error Conditions -

Eror Condition RESP RESP2 Reason
FILENOTFOUND 12 1 A file name in the FILE option is not defined to CICS.
DUPREC 14 150 An attempt is to add a record to a file in which the same key already exists.
INVREQ 16 20 Write operations are not allowed according to the resource definition.
16 23 The key in the record area (FROM option) and the key in RIDFLD do not match.
16 26 The KEYLENGTH option specified length does not equal the length defined for the data set.
16 38 WRITE with the MASSINSERT option is issued against a BDAM file.
16 51 WRITE command specifying the RBA keyword was issued against a KSDS file accessed in RLS mode.
16 55 NOSUSPEND is not allowed because the file is not a VSAM file accessed in RLS mode.
16 59 XRBA was specified but the data set is not an extended addressing ESDS.
IOERR 17 120 There is an I/O error during the file control operation.
NOSPACE 18 100 No space is available on the direct access device for adding records to a data set.
NOTOPEN 19 60 Below are the reasons for NOTOPEN
  • The requested file is CLOSED and UNENABLED.
  • The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.
  • The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request.
ILLOGIC 21 110 Any browse that is currently in progress is terminated when this condition is raised. VSAM error occurs that is not in one of the other CICS response categories.
LENGERR 22 10 The LENGTH option is not specified.
22 12 The length specified for the write operation exceeds the maximum record size and the record is truncated.
22 14 An incorrect length is specified for a fixed-length records.
SYSIDERR 53 130 The SYSID name specified is neither the local region nor a remote system or the link to the remote system is closed.
ISCINVREQ 54 The remote system indicates a failure that does not correspond to a known condition.
NOTAUTH 70 101 A resource security check has failed on FILE(filename).
DISABLED 84 50 A file was initially defined as disabled or was disabled by a SET FILE or a CEMT SET FILE command.
LOCKED 100 An attempt has been made to write a record, but lock exists against the same key of the record.
RECORDBUSY 101 107 NOSUSPEND is specified on the request but VSAM holds an active lock against the record, which would cause the request to wait. (AEX9)