WRITE
Summary
WRITE writes a new record to a file. The file may be on a local or a remote system. The record is always added at the end of the data set for a VSAM ESDS or VSAM extended format or extended addressing ESDS.
CICS does not use the RIDFLD field information when calculating the relative byte address (RBA) or the extended relative byte address (XRBA) for an extended addressing ESDS of the new record.
However, the new RBA or XRBA is returned to the application program in the RIDFLD option. The new record is added anywhere in the data set based the associated key for a VSAM KSDS.
The key in the record and the key in the RIDFLD identification field must be the same for VSAM data sets. Records can be either fixed-length or variable-length for a VSAM ESDS or KSDS. MASSINSERT operations should be performed with ascending keys and the request must be terminated by an UNLOCK.
Syntax -
Parameters -
FILE(filename) -
Specifies the file name to be accessed. If SYSID is specified, the data set is on a remote system irrespective of the name is defined to CICS. If SYSID is not specified, the data set assumed to be on the local system. 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 data record that is to be written to the data set referred by the filename.
KEYLENGTH(length-value) -
length-value is a halfword binary value. Specifies the key length. The value specified in KEYLENGTH is same as the value specified in the RIDFLD option except when RBA or RRN is specified. KEYLENGTH is not valid when RBA or RRN is specified. KEYLENGTH must be specified if using SYSID.
The KEYLENGTH clause is required when the WRITE FILE is writing to remote file, otherwise an INVREQ with RESP2=23 might occur. If the length specified is different from the length defined for the data set, the INVREQ condition occurs.
LENGTH(length-value) -
length-value is a halfword binary value. Specifies the data area (record) length that is to be written. This option is mandatory if SYSID is specified. If the file is on a remote system and SYSID is not specified, the LENGTH parameter should 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. However, it is advisable to specify the length of fixed-length records.
If an incorrect length is specified for fixed-length records, a record of the fixed length is written and the LENGERR condition is raised. If record length is bigger than specified, the record is truncated. If record length is smaller than specified, the record is padded with binary zeros.
MASSINSERT -
This option applies for only VSAM datasets. Specifies the series of WRITEs performing on the dataset and each specifying MASSINSERT.
NOSUSPEND -
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 -
This option is for VSAM ESDS base data sets only. Specifies the RIDFLD option field contains a relative byte address.
RIDFLD(data-area) -
Specifies the record identification field. The contents can be a key or 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).
The field is full word binary for a relative byte address or a relative record number. 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 -
This option is valid for VSAM RRDS. Specifies the RIDFLD option contains a relative record number.
SYSID(systemname) -
Specifies the system name to which the request is directed. If SYSID specified and omit RBA, XRBA and RRN, LENGTH and KEYLENGTH must be specified.
XRBA -
Specifies the RIDFLD option field contains an extended relative byte address.
Error Conditions -
Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.
| Error Condition | RESP2, Description & Solution | System Action |
|---|---|---|
| 84 DISABLED | 50 - A file was initially defined as disabled or was disabled by a SET FILE or a CEMT SET FILE command. Solution -Enable the file using SET FILE or a CEMT SET FILE command. If no access, contact support team to enable the file. | Task abnormally terminated |
| 14 DUPREC | 150 - An attempt is to add a record to a file in which the same key already exists. Solution -The attempt is to add a record with a duplicate key. If required update the data in the record, rewrite the record. Change the program logic accordingly. | Task abnormally terminated |
| 12 FILENOTFOUND | 1 - A file name in the FILE option is not defined to CICS. Solution -Contact support team to define the FILE in CICS region. | Task abnormally terminated |
| 21 ILLOGIC | Any browse that is currently in progress is terminated when this condition is raised.
110 - VSAM error occurs that is not in one of the other CICS response categories. Solution -This might be due to the non-sequence of file operations. Debug the program to correct the logic. | Task abnormally terminated |
| 16 INVREQ | 20 - Write operations are not allowed according to the resource definition. Solution -Change the resource definitions if the deletion is valid or do not perform delete if the file definitions are correct. 23 - The key in the record area (FROM option) and the key in RIDFLD do not match. Solution -This the logic error. The record area key and RIDFID key should be same while performing WRITE operation. Debug the program logic to resolve the issue. 26 - The KEYLENGTH option specified length does not equal the length defined for the data set. Solution -The value specified in KEYLENGTH option should be same as the length specified while file definition. 38 - WRITE with the MASSINSERT option is issued against a BDAM file. Solution -MASSINSERT option should not be issued on BDAM file. Correct the program logic to resolve the issue. 51 - WRITE command specifying the RBA keyword was issued against a KSDS file accessed in RLS mode. Solution -RBA option is not valid for KSDS file accessing in RLS mode. Modify the program to remove RBA option for files which are accessing in RLS mode. 55 - NOSUSPEND is not allowed because the file is not a VSAM file accessed in RLS mode. Solution -NOSUSPEND option is valid for only VSAM files accessed in RLS mode. Modify the program to remove NOSUSPEND option for files which are not accessing in RLS mode. 59 - XRBA was specified but the data set is not an extended addressing ESDS. Solution -XBRA only for extended addressing ESDS. Modify the program to remove XBRA option for writing the files other than extended ESDS. | Task abnormally terminated |
| 17 IOERR | 120 - There is an I/O error during the file control operation. Solution -An I/O error is any unusual event that is not covered by a CICS condition. For VSAM files, IOERR usually indicates a hardware error. For BDAM files, IOERR could means you are trying to write to a BDAM track address that is not defined for the data set. | Task abnormally terminated |
| 54 ISCINVREQ | The remote system indicates a failure that does not correspond to a known condition.
Solution -Contact remote system support team to resolve the issue. | Task abnormally terminated |
| 22 LENGERR | 12 - The length specified for the write operation exceeds the maximum record size and the record is truncated. Solution -The length of the record should not exceed maximum length. Use best possible solution to write the record without truncating. 10 - The LENGTH option is not specified. Solution -Modify the program to specify the LENGTH option. 14 - An incorrect length is specified for a fixed-length records. Solution -Modify the program to specify the correct length to resolve the issue. | Task abnormally terminated |
| 100 LOCKED | An attempt has been made to write a record, but lock exists against the same key of the record. Solution -The record might get locked for some other reason. Wait for some time and try again. | Task abnormally terminated |
| 18 NOSPACE | 100 - No space is available on the direct access device for adding records to a data set. Solution -Contact Storage support team to resolve the issue. | Task abnormally terminated |
| 70 NOTAUTH | 101 - A resource security check has failed on FILE(filename). Solution -Contact system administrator team to check whether the appropriate access added for the user or group. It will resolve the problem. | Task abnormally terminated |
| 19 NOTOPEN | 60 – Below are the reasons for NOTOPEN
| Task abnormally terminated |
| 101 RECORDBUSY | 107 - NOSUSPEND is specified on the request but VSAM holds an active lock against the record, which would cause the request to wait. Solution -This might occur very rarely. Wait for some time and try again.If this occurring on regular basis, modify the application program to remove NOSUSPEND. | Abend the task with code AEX9 |
| 53 SYSIDERR | 130 - The SYSID name specified is neither the local region nor a remote system or the link to the remote system is closed. Solution -The specified SYSID name is not related to any system. Correct it.If the link to the remote system is closed, that might be due to the remote system is not up and running. Contact remote system support team. | Task abnormally terminated |