DELETE

Delete a record from a file - VSAM KSDS, VSAM RRDS, and data tables only.

DELETE

Conditions: CHANGED, DISABLED, DUPKEY, FILENOTFOUND, ILLOGIC, INVREQ, IOERR, ISCINVREQ, LOADING, LOCKED, NOTAUTH, NOTFND, NOTOPEN, RECORDBUSY, SYSIDERR

This command is threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over an IPIC connection to a remote CICS® region.
Defined as either local VSAM or RLS.

This command is not threadsafe if the file to which it refers is:

Defined as remote and the command is function shipped over a non-IPIC connection.
Defined as NSR.
Defined as a shared data table, coupling facility data table, or BDAM file.

Description

The DELETE command deletes a record from a file on a KSDS, a path over a KSDS, a CICS or user-maintained data table, or an RRDS. You cannot delete from a VSAM ESDS or a BDAM file. All references to KSDS apply equally to CICS maintained data tables and, except where stated otherwise, to paths over a KSDS. The file can be on a local or a remote system. You identify, in the RIDFLD option, the specific record to be deleted.

You can delete a group of records with a single invocation of this command, identifying the group by the GENERIC option (not available for RRDS). The DELETE command with GENERIC option should be used with caution. If the generic key specified will match a very large number of records, then the CICS unit of work will be holding a very large number of record locks until syncpoint. This could cause storage issues within the CICS region, or if the file is an RLS file, it could cause excessive use of coupling facility resources and affect other systems. Instead, consider using a series of generic deletes (by using generic keys that will match less records) and syncpoint after each range of records has been deleted.

You can also use this command to delete a single record that has previously been retrieved for update (by a READ UPDATE command). In this case, you must not specify the RIDFLD option.

Note: If you are converting to RLS access mode and are using the system initialization parameter CILOCK=NO in CICS, see VSAM RLS for migration considerations and advice.

When this command is used to delete records from a CICS-maintained data table, the update is made to both the source VSAM KSDS data set and the in-memory data table.

When this command is used to delete records from a user-maintained data table, the update is made only to the in-memory data table.

When this command is used to delete records from a coupling facility data table, the update is made only to the data table in the coupling facility.

Options

FILE(filename)

Specifies the name 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 to CICS. Otherwise, the resource definition is used to find out whether the data set is on a local or a remote system.

GENERIC (VSAM KSDS only)

Specifies that the search key is a generic key with a length specified in the KEYLENGTH option. The search for a record is satisfied when a record is found with a key that has the same starting characters (generic key) as those specified.

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 it is not valid. This option must be specified if GENERIC is specified, and it can be specified whenever a key is specified. However, if the length specified is different from the length defined for the data set and the operation is not generic, the INVREQ condition occurs.

The INVREQ condition also occurs if you specify GENERIC, and the KEYLENGTH is not less than the length specified in the VSAM definition.

Do not specify a zero value for KEYLENGTH because the results are unpredictable.

For remote files, you can specify the KEYLENGTH in the FILE definition. If KEYLENGTH is not defined there, and is not specified in the application program, and the key is longer than 4 characters, the default value is 4.

NOSUSPEND (RLS only)

Specifies that the request is not to wait if VSAM is holding an active lock against the record, including records locked as the result of a DEADLOCK.

Note: Requests that specify NOSUSPEND wait for at least 1 second before CICS returns the RECORDBUSY response.

NUMREC(data-area) (VSAM KSDS only)

Specifies a halfword binary data area that CICS sets to the number of deleted records.

RBA

(VSAM KSDS base data sets only, not paths) Specifies that the record identification field specified in the RIDFLD option contains a relative byte address. Use this option only when deleting records using relative byte addresses instead of keys to identify the records.

You cannot use RBA for:

User-maintained data tables
Coupling facility data tables
Any files opened in RLS access mode
KSDS files that can hold more than 4 GB of data

RIDFLD(data-area)

Specifies the record identification field. The contents can be a key, a relative byte address (RBA), or a relative record number. For a relative byte address or a relative record number, the format of this field must be fullword binary. For a relative byte address, the RIDFLD can be greater than or equal to zero. For a relative record number, the RIDFLD can be greater than or equal to 1.

The contents must be a key for user-maintained data tables or coupling facility data tables.

You must specify this option if you have also specified GENERIC.

RRN (VSAM RRDS only)

Specifies that the record identification field specified in the RIDFLD option contains a relative record number. Use this option only with files referencing relative record data sets.

SYSID(systemname)

Specifies the name (1-4 characters) of the system the request is directed to.

If you specify SYSID, and omit both RBA and RRN, you must also specify KEYLENGTH; it cannot be found in the resource definition.

TOKEN(data-area)

Specifies, as a fullword binary value, a unique identifier for this DELETE request. Use this identifier to associate the delete request with a record returned on a previous READ UPDATE or BROWSE for UPDATE request. The value to use is the value returned in the TOKEN held by the earlier READ UPDATE or BROWSE for UPDATE request.

TOKEN can be function shipped. However, if a request specifying TOKEN is function shipped to a member of the CICS Family of products that does not recognize this option, the request fails.

Conditions

105 CHANGED

RESP2 values:

109: A DELETE command (without RIDFLD) is issued for a file that is a defined as a coupling facility data table using the contention update model and the record has been changed since the application program read it for update. To perform the DELETE successfully, repeat the read for update to get the latest version of the record, and try the DELETE command again.
Default action: terminate the task abnormally.

84 DISABLED

RESP2 values:

50

A file is disabled. A file can be disabled because:

It was initially defined as disabled and has not since been enabled.
It has been disabled by a SET FILE or a CEMT SET FILE command.

This condition cannot occur when the DELETE command follows any read with the UPDATE option.

Default action: terminate the task abnormally.

15 DUPKEY

RESP2 values:

140: A record is accessed by way of an alternate index with the NONUNIQUEKEY attribute, and another alternate index record with the same key follows.

Default action: terminate the task abnormally.

12 FILENOTFOUND

RESP2 values:

1: The file name referred to in the FILE option cannot be found in the file resource definition.

Default action: terminate the task abnormally.

21 ILLOGIC

RESP2 values:

110: A VSAM error occurs that is not in one of the other CICS response categories.
See EIBRCODE in the EXEC interface block; for details, see EIB fields.

Default action: terminate the task abnormally.

16 INVREQ

RESP2 values:

20: Delete operations are not allowed according to the resource definition.
21: A DELETE command is issued for a file referring to a VSAM ESDS.
22: A generic delete is issued for a file that is not a VSAM KSDS.
25: The KEYLENGTH and GENERIC options are specified, and the length specified in the KEYLENGTH option is greater than or equal to the length of a full key.
26: The KEYLENGTH option is specified (but the GENERIC option is not specified), and the specified length does not equal the length defined for the data set to which this file refers.
27: A DELETE command is issued for a file referring to a BDAM data set.
31: A DELETE command without the RIDFLD option is issued for a file for which no previous READ UPDATE command has been issued.
42: The KEYLENGTH and GENERIC options are specified, and the length specified in the KEYLENGTH option is less than zero.
44: The DELETE command does not conform to the correct format for a user-maintained or coupling facility data table; for example if RBA was specified.
47: A DELETE instruction includes a token whose value cannot be matched against any token in use for an existing read for UPDATE request.
51: A DELETE command specifying the RBA or XRBA keyword is issued against a KSDS file that is being accessed in RLS mode. RLS does not support relative byte address (RBA) access to KSDS files.
55: NOSUSPEND is specified for a non-RLS file.
56: An attempt to update a recoverable coupling facility data table has failed because the current unit of work has already updated 1024 recoverable coupling facility data tables. You cannot update more than 1024 recoverable coupling facility data tables within a unit of work
57: DELETE operations are not allowed because the associated VSAM data set has an AVAILABILITY state of RREPL, which disallows such operations except those from replication programs.
59: XRBA was specified, but the data set is not an extended ESDS.

Default action: terminate the task abnormally.

17 IOERR

RESP2 values:

120

There is an I/O error during the file control operation. 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. Further information is available in the EXEC interface block; for details, see EIB fields.

For a coupling facility data table, an IOERR indicates a bad response returned from a coupling facility access.

Default action: terminate the task abnormally.

54 ISCINVREQ

RESP2 values:

70: The remote system indicates a failure that does not correspond to a known condition.

Default action: terminate the task abnormally.

94 LOADING

RESP2 values:

104

A delete request is issued for a user-maintained data table that is currently being loaded. A user-maintained data table cannot be modified during loading.

LOADING is also returned for a coupling facility data table if the delete request is for a key that is not yet loaded. A coupling facility data table can be modified during loading, but only if the requested key is within the range of those records already loaded.

The LOADING response can also be returned for a coupling facility data table that has failed during loading. For more information about what happens if the load for a coupling facility data table fails, see the description of the XDTLC global user exit in the Data tables management exits XDTRD, XDTAD, and XDTLC.

If your application programs encounter the LOADING condition persistently or too frequently, check that this condition is not caused by conflicting file definitions that reference the same data set.

Default action: terminate the task abnormally.

100 LOCKED

RESP2 values:

106: An attempt is made to delete a record specifying the RIDFLD, but a retained lock exists against this key (see Retained and active locks). If the request specifies the GENERIC keyword, all possible records are deleted, but the locked records remain. The number of records deleted is returned by NUMREC.
The LOCKED condition can also occur for a DELETE request to a recoverable CFDT that uses the locking model, if the record being read is locked by a retained lock. See the Coupling facility data table retained locks for information about investigating retained locks on records in a coupling facility data table.

Default action: abend the task with code AEX8.

70 NOTAUTH

RESP2 values:

101: A resource security check has failed on FILE(filename).

Default action: terminate the task abnormally.

13 NOTFND

RESP2 values:

80

An attempt to delete a record based on the search argument provided is unsuccessful.

For user-maintained data and coupling facility data tables, this condition occurs if an attempt to delete a record is unsuccessful because there is no entry with the specified key in the data table. This can occur on an attempt to delete a record using a DELETE without RIDFLD, if the delete is associated with a READ UPDATE request for a record that this transaction has deleted (using DELETE with RIDFLD) after it was read for update.

This does not mean that there is no such record in the source data set (if the table was created from one); it might be that such a record is present but was either rejected during initial loading by the user exit XDTRD, or was later deleted from the data table.

For coupling facility data tables, this condition can also occur when a DELETE command (without a RIDFLD) is issued to a coupling facility data table using the contention model, and the record has been deleted since it was read for update.

Default action: terminate the task abnormally.

19 NOTOPEN

RESP2 values:

60

NOTOPEN (RESP2 60) is returned for one of the following reasons:

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. You can also make CLOSED, UNENABLED the initial state, by specifying STATUS(UNENABLED) and OPENTIME(FIRSTREF) on the FILE resource definition.
The requested file is OPEN and in use by other transactions, but a CLOSE request against the file has been received.
A DELETE command is issued against a data set that is quiesced, or is being quiesced, as a result of a SET DSNAME QUIESCED or IMMQUIESCED command.
The requested file is CLOSED and ENABLED, so CICS has tried to open the file as part of executing the request. This file open has failed for some reason. Examine the console for messages that explain why the file open has been unsuccessful.

This condition does not occur if the request is made to a CLOSED, DISABLED file. In this case, the DISABLED condition occurs.

This condition also cannot occur when deleting a record just read for update.

Default action: terminate the task abnormally.

101 RECORDBUSY

RESP2 values:

107

The NOSUSPEND keyword is specified for the deletion of a record that is locked by a VSAM active lock (see Retained and active locks).

If the request specifies the GENERIC keyword, all possible records are deleted except for the locked records which remain. The number of records deleted is returned by NUMREC.

Default action: abend the task with code AEX9.

53 SYSIDERR

RESP2 values:

130: The SYSID option specifies a name that is not the local system or a remote system (made known to CICS by defining a CONNECTION). SYSIDERR also occurs when the link to the remote system is closed.
131: For a coupling facility data table, the connection to the coupling facility data table server has failed. This failure could occur because the server itself has failed, or the server is available, but CICS has failed to connect to it.
132: The DELETE command is issued against a coupling facility data table that no longer exists, probably because of a coupling facility failure, in which case the coupling facility data table server also fails.

Default action: terminate the task abnormally.

Retained and active locks

RECORDBUSY refers to active locks and LOCKED refers to retained locks:

DELETE requests for records that have retained locks are always rejected with a LOCKED response.
DELETE requests for records that have active locks wait for the lock to be released, except when the NOSUSPEND keyword is specified, in which case CICS returns the RECORDBUSY response.

Examples

The following example shows you how to delete a group of records in a VSAM data set:

EXEC CICS DELETE
     FILE('MASTVSAM')
     RIDFLD(ACCTNO)
     KEYLENGTH(len)
     GENERIC
     NUMREC(NUMDEL)