Using CICS commands to add records
Add new records to a file in a VSAM data set using the WRITE command. New records must always be written from an area provided by the application program.
About this task
These instructions cover general principles for writing records, and specific information for the different types of VSAM data set. For specific information about adding records to BDAM data sets, see Adding records to BDAM data sets.
When you use the WRITE command:
Procedure
- To add a record to a KSDS, use the RIDFLD (record identification field) option to specify the base key of the record. The base key of the record identifies the position in the data set where the record is to be inserted. Although the key is part of the record, CICS® also requires the application program to specify the key separately.
- To add a record to an ESDS base data set, the record must be added to the end of the file. You cannot insert a record in an ESDS between existing records. After the operation is completed, the relative byte address in the file where the record was placed is returned to the application program.
- To add a record to a KSDS or
standard
ESDS by
way of an alternate index path, use the RIDFLD option to specify the
alternate key.
For a KSDS, the record is inserted into
the data set in the position determined by the base key. For an ESDS,
the record is placed at the end of the data set.
Note: Extended ESDS data sets do not support alternate indexes.
- To add a record to an RRDS, use the RIDFLD option to specify the relative record number. The record is stored in the file in the position corresponding to the RRN.
- Specify the KEYLENGTH option if required, to state the
length of the key which you specified in the RIDFLD option.
- If you specify an RBA, XRBA, or RRN for the record identification field, and specify the RBA, XRBA, or RRN option, the KEYLENGTH option is not required.
- In all other situations, the KEYLENGTH option is required. If you specify a KEYLENGTH which is different from the length defined for the data set, the INVREQ condition occurs.
- Use the FROM option to specify the main storage area that contains the record to be written. In general, this area is part of the storage owned by your application program.
- Specify the LENGTH option if required.
- When writing to a file with fixed-length records, the LENGTH option is not required. CICS uses the length specified in the cluster definition as the length of the record to be written. If you do specify the LENGTH option, its value is checked against the defined value, and you get a LENGERR condition if the values do not match.
- When writing to a file with variable-length records, always include the LENGTH option. If the value specified exceeds the maximum allowed in the cluster definition, LENGERR is raised when the command is executed. LENGERR is also raised if the LENGTH option is omitted when accessing a file with variable-length records.
- If the file is open in RLS mode, and there is a possibility that the record might already be locked, you can specify the NOSUSPEND option. The NOSUSPEND option ensures that the request does not wait if the record is locked by VSAM with an active lock. Active and retained states for locks explains active locks.
- If you have more than one record to add to a KSDS, ESDS,
or path, and the keys in successive requests are in ascending order,
using the MASSINSERT option improves performance. (The
performance improvement is only obtained if the keys are in ascending
order.)
- Specify the MASSINSERT option on each WRITE command in the sequence.
- When the MASSINSERT operation is complete and all records
have been written, issue an UNLOCK command to ensure that all the
records are written to the file and the position is released. Always issue an UNLOCK command before performing an update
operation
on the same data set (read update, delete with RIDFLD, or write).
If you do not, you might get unpredictable results, possibly
including
a deadlock. If you do not issue the UNLOCK command, the
MASSINSERT operation is completed when a sync point is issued, or
at task termination.
Note: A READ command does not necessarily retrieve a record that has been added by an incomplete MASSINSERT operation.
- CICS locking for writing to ESDS
CICS write operations to ESDS are single threaded, for both RLS and non-RLS mode access. However, the lock held for serialization can be held for slightly longer for RLS-mode access compared with non-RLS mode. You can compensate for the possible increase in overhead by increasing the task priority of those transactions that add new records to ESDS files. - Adding records to BDAM data sets
Records added to a BDAM data set can be undefined or variable-length (keyed or nonkeyed), keyed fixed-length, nonkeyed fixed-length, or variable-length blocked.
dfhp3mp.html |
Last updated: Monday, 5 June 2017