IDCAMS DELETE

The IDCAMS DELETE command removes VSAM objects from the catalog: clusters (and their data and index components), alternate indexes (AIX), and paths. DELETE does not remove application records one by one; it removes entire catalog entries and optionally the space on disk. You must often specify an object type (CLUSTER, ALTERNATEINDEX, PATH) and you can use options such as PURGE (to delete even if retention has not expired), ERASE (to overwrite data before removal), and SCRATCH (to release volume space). This page explains the DELETE syntax, when to delete clusters vs paths vs AIXs, the correct order for deleting a base cluster that has paths and an AIX, and what each option (PURGE, ERASE, FORCE, SCRATCH) does and when to use it.

What DELETE Does

DELETE removes catalog entries and optionally the associated data. For a cluster, DELETE CLUSTER removes the cluster entry and the entries for its data and index components; the space on the volume may be freed if you use SCRATCH, or left allocated if you use the default NOSCRATCH. For a path, DELETE PATH removes only the path catalog entry; the AIX and base cluster are unchanged. For an alternate index, DELETE ALTERNATEINDEX removes the AIX cluster and its components. So DELETE is the way you "tear down" VSAM objects you no longer need. It is the opposite of DEFINE: DEFINE creates the object, DELETE removes it.

General Syntax

The DELETE command takes one or more entry names and an optional object type and optional parameters. Basic form:

1
2
3
4
5
6
7
8
  DELETE (entryname [ entryname ... ]) -
    [ CLUSTER | ALTERNATEINDEX | PATH | ... ] -
    [ PURGE | NOPURGE ] -
    [ ERASE | NOERASE ] -
    [ SCRATCH | NOSCRATCH ] -
    [ FORCE | NOFORCE ] -
  [ CATALOG(catname) ]
 

entryname is the name of the cluster, AIX, or path. You can list multiple names in one DELETE. The object type (CLUSTER, ALTERNATEINDEX, PATH) tells IDCAMS what kind of entry to delete. If you omit it, the system may infer the type from the catalog, but it is safer to specify it. PURGE, ERASE, SCRATCH, and FORCE are optional; their defaults (NOPURGE, NOERASE, NOSCRATCH, NOFORCE) are often sufficient, but PURGE is commonly needed when the object has a retention date that has not yet passed.

Object Types: CLUSTER, ALTERNATEINDEX, PATH

For VSAM dataset management the three object types you use most are CLUSTER, ALTERNATEINDEX, and PATH. Each removes a different kind of catalog entry. Deleting a cluster removes the cluster and its data and index components; you do not delete the components separately. Deleting an AIX removes the alternate index cluster and its components. Deleting a path removes only the path entry; the AIX and base cluster remain. The following table summarizes.

PURGE and NOPURGE

When you define a cluster (or path, or AIX) you can specify a retention period with TO(date) or FOR(days). Until that date or until the number of days has passed, the object is protected from deletion. NOPURGE (the default) means: do not delete if the object is still within its retention period. If you try to DELETE without PURGE and the retention has not expired, IDCAMS will not delete the object. PURGE means: delete anyway, ignoring the retention period. So when you need to remove a VSAM object before its retention date—for example, to free space or to replace it—you must use DELETE ... PURGE. Without PURGE, the delete will fail (or be refused) if the retention has not expired.

ERASE and NOERASE

NOERASE (the default) means that when you delete a cluster (or AIX), only the catalog entries are removed. The space on the volume may still contain the old data until it is overwritten by another dataset. So the data could potentially be recovered with low-level tools. ERASE means that before removing the catalog entry, IDCAMS overwrites the data (and index) areas with binary zeroes. That makes the data unrecoverable. Use ERASE when the dataset contains sensitive information and you need to ensure it cannot be read after deletion. ERASE takes longer than NOERASE because it writes to the entire allocated space. For non-sensitive data, NOERASE is usually enough and is faster.

SCRATCH and NOSCRATCH

NOSCRATCH (the default) means that after deleting the catalog entry, the space on the volume (the extent in the VTOC) is not released. The catalog no longer points to it, but the volume still shows the space as allocated until something else uses it or an administrator reclaims it. SCRATCH means that in addition to removing the catalog entry, the space is released (the VTOC entry is removed or updated) so the space can be used by other datasets. Use SCRATCH when you want to free DASD. On some systems the exact behavior of SCRATCH depends on the catalog and volume type; consult your IDCAMS documentation.

FORCE and NOFORCE

NOFORCE (the default) means that DELETE will fail if the object is in use (e.g. open by another job or region) or if other conditions are not met. FORCE allows the delete to proceed in some situations where it would otherwise be refused. Use FORCE with care: deleting an object that is in use can cause errors in the program that has it open. Typically you use FORCE only when you are sure no one is using the object and the normal delete is failing for a reason you understand (e.g. a catalog quirk). Your site may have rules about when FORCE is allowed.

Order of Deletion: Path, AIX, Base Cluster

If you have a base cluster with an alternate index and one or more paths, you must delete in the right order. The path points to the AIX; the AIX points to the base cluster. If you delete the base cluster first, the catalog still has path and AIX entries that reference it, and the delete may fail or leave inconsistent catalog entries. The safe order is: (1) Delete all paths that use the AIX. (2) Delete the alternate index (AIX). (3) Delete the base cluster. That way you remove the path (the link), then the AIX (the alternate index), then the base (the main data). After that, the catalog has no entries for the path, AIX, or cluster.

Examples

Delete a path

1
2
  DELETE (MY.EMPL.BY.DEPT) PATH
 

Removes only the path MY.EMPL.BY.DEPT. The AIX and base cluster are not deleted. Use this when you no longer need alternate-key access by that path name but want to keep the AIX and base.

Delete an alternate index

1
2
  DELETE (MY.EMPL.AIX.DEPT) ALTERNATEINDEX PURGE
 

Deletes the AIX cluster MY.EMPL.AIX.DEPT. PURGE is used so that the delete succeeds even if the AIX has a retention period that has not expired. Delete any paths that use this AIX before running this command.

Delete a cluster

1
2
  DELETE (MY.EMPL.KSDS) CLUSTER PURGE SCRATCH
 

Deletes the cluster MY.EMPL.KSDS and its data and index components. PURGE ignores retention. SCRATCH releases the space on the volume. The cluster must not have any paths or AIXs that reference it (or delete those first), and it should not be in use by another job.

Delete with ERASE for security

1
2
  DELETE (SENSITIVE.DATA.KSDS) CLUSTER PURGE ERASE SCRATCH
 

Deletes the cluster, overwrites its data with zeroes (ERASE), and releases the space (SCRATCH). Use this when the data is sensitive and must not be recoverable after deletion.

Deleting Multiple Entries

You can delete more than one entry in a single DELETE command by listing multiple names. All must be of the same object type if you specify a type. For example:

1
2
  DELETE (PATH1 PATH2 PATH3) PATH PURGE
 

Deletes three path entries in one command. Each name is removed from the catalog. The same PURGE (and other options) apply to all.

FILE(ddname) and CATALOG

FILE(ddname) can be used with DELETE to specify a DD name that points to the catalog (e.g. when using a user catalog via STEPCAT). CATALOG(catname) specifies the catalog in which the entry is to be deleted. If you omit CATALOG, the step or job default catalog is used. When the cluster or AIX is in a user catalog, ensure the job has access to that catalog (JOBCAT/STEPCAT) and use CATALOG if you need to target a specific catalog.

Key Takeaways

• DELETE removes VSAM catalog entries (and optionally data and space). Use CLUSTER, ALTERNATEINDEX, or PATH to specify what to delete.
• PURGE deletes even if retention (TO/FOR) has not expired; NOPURGE (default) refuses to delete until retention expires.
• ERASE overwrites data with zeroes before removal; use for sensitive data. NOERASE (default) removes only the catalog entry.
• Delete in order: paths first, then AIX, then base cluster, when the base has paths and an AIX.
• SCRATCH releases volume space; NOSCRATCH (default) removes only the catalog entry.

Explain Like I'm Five

Imagine you have a folder (cluster), a small list that says "find by color" (AIX), and a sign on the door that says "use the color list here" (path). To put everything away, you take down the sign first (DELETE PATH), then throw away the small list (DELETE ALTERNATEINDEX), then throw away the folder (DELETE CLUSTER). If you throw away the folder first, the sign and the list still point to it and things get messy. PURGE is like saying "throw it away even if the rule says keep it until next week." ERASE is like scribbling over all the writing before throwing it away so nobody can read it later.

Test Your Knowledge