DELETE

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

Read syntax diagramSkip visual syntax diagram
DELETE

>>-DELETE--FILE(filename)--------------------------------------->

>--+----------------------------------------------------------------------------------+-->
   +-TOKEN(data-area)-----------------------------------------------------------------+   
   '-RIDFLD(data-area)--+-----------------------------------------------------------+-'   
                        '-KEYLENGTH(data-value)--+--------------------------------+-'     
                                                 '-GENERIC--+-------------------+-'       
                                                            '-NUMREC(data-area)-'         

>--+-------------------+--+-----------+--+---------+-----------><
   '-SYSID(systemname)-'  '-NOSUSPEND-'  +-+-----+-+   
                                         | '-RBA-' |   
                                         '-RRN-----'   

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

 

Description

DELETE 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 may 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 in a similar way with a single invocation of this command, identifying the group by the GENERIC option (not available for RRDS).

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.

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 in the FCT. Otherwise, the FCT entry 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 may 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 that specified in the VSAM definition.

You should not specify a zero value of KEYLENGTH because the results of this are unpredictable.

For remote files, the KEYLENGTH can be specified 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.
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. This option should be used 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 are capable of holding more than 4GB of data
RIDFLD(data-area)
specifies the record identification field. 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 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. This option should be used 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 FCT.

TOKEN(data-area)
Specifies, as a fullword binary value, a unique identifier for this DELETE request. Use this 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

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 again.

Default action: terminate the task abnormally.

DISABLED
RESP2 values:
50
A file is disabled. A file may 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 follows any read with the UPDATE option.

Default action: terminate the task abnormally.

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.

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.

ILLOGIC
RESP2 values:
110
A VSAM error occurs that does not fall within one of the other CICS response categories.

(See EIBRCODE in the EXEC interface block; refer to EXEC interface block for details.)

Default action: terminate the task abnormally.

INVREQ
RESP2 values:
20
Delete operations are not allowed according to the file entry specification in the FCT.
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 format of DELETE 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 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

Default action: terminate the task abnormally.

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 normally indicates a hardware error.

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

(Further information is available in the EXEC interface block; refer to EXEC interface block for details.)

Default action: terminate the task abnormally.

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

Default action: terminate the task abnormally.

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 CICS Customization Guide.

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

Default action: terminate the task abnormally.

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 CICS Recovery and Restart Guide for information about investigating retained locks on records in a coupling facility data table.

Default action: abend the task with code AEX8.

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

Default action: terminate the task abnormally.

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 may be that such a record is present but was either rejected during initial loading by the user exit XDTRD, or was subsequently 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.

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. You should 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.

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.

SYSIDERR
RESP2 values:
130
The SYSID option specifies a name that is neither the local system nor 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 could be because the server itself has failed, or the server is available, but CICS has failed to connect to it.
132
The DELETE 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. See the CICS System Definition Guide for information about restarting a coupling facility data table server and reloading a table.

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)