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