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

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)