IDCAMS DELETE: Full Syntax Reference

This page is a complete syntax reference for the IDCAMS DELETE command. It covers the exact form of the command, every parameter and option, what each one does, and when to use it. DELETE removes VSAM objects from the catalog: clusters (and their data and index components), alternate indexes (AIX), and paths. Use this reference when you need the full picture—entry names, object types (CLUSTER, ALTERNATEINDEX, PATH), and the options PURGE, ERASE, SCRATCH, and FORCE—and the correct order for deleting a base cluster that has paths and an alternate index.

Why a Syntax Reference for DELETE?

DELETE has a simple structure but several options that change behavior. If you omit the object type, the system may infer it from the catalog, but specifying CLUSTER, ALTERNATEINDEX, or PATH avoids ambiguity. PURGE is needed whenever the object has a retention date that has not yet passed. ERASE is needed when you must overwrite data for security. SCRATCH is needed when you want to free the volume space. Getting the order wrong when deleting a base cluster with path and AIX causes catalog errors. A full syntax reference helps you write correct DELETE commands the first time and avoid accidental retention or security mistakes.

Complete Command Syntax

The DELETE command has this form. The entry name (or list of names) is required. Object type and all other parameters are optional but recommended where applicable. Continuation uses a hyphen at end of line.

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

entryname is the name of the cluster, alternate index, or path as it appears in the catalog. You can specify multiple names in one DELETE; all are processed with the same options. For VSAM dataset management the object types you use most are CLUSTER, ALTERNATEINDEX, and PATH. USERCATALOG and other types apply to catalog management. FILE(ddname) refers to a DD statement that points to the catalog (e.g. for STEPCAT); CATALOG(catalog-name) names the catalog in which the entry is to be deleted.

Syntax Elements and Options

The following table describes each part of the DELETE command. Required and optional elements are listed so you can see at a glance what you must specify and what each option does.

Object Types in Detail

CLUSTER

When you specify DELETE (name) CLUSTER, IDCAMS removes the cluster catalog entry and the catalog entries for its data and index components. You do not issue separate DELETEs for the data and index; one DELETE CLUSTER removes the whole cluster. The cluster must not be in use by another job or region (unless your system allows force delete). If the cluster has paths or an alternate index that references it, delete those first: path(s), then AIX, then cluster. For a KSDS, both the data and index components are removed; for ESDS, RRDS, or LDS, only the data component exists and it is removed with the cluster.

ALTERNATEINDEX

DELETE (name) ALTERNATEINDEX removes the alternate index cluster and its data and index components. The base cluster is not deleted. Any path that uses this AIX must be deleted first; otherwise the path would point to a deleted AIX and the catalog could be inconsistent or the path delete could fail depending on order. After deleting the AIX, the base cluster can still be used by its cluster name; only the alternate key access via the path is gone (you already deleted the path).

PATH

DELETE (name) PATH removes only the path catalog entry. The path is a name that applications use in DSN= to access the base cluster by the alternate key (through the AIX). Deleting the path does not delete the AIX or the base cluster; it only removes that logical name. So you can delete a path when you no longer need that alternate key access but want to keep the AIX and base. Or you delete the path first as step one before deleting the AIX and then the base cluster.

PURGE and NOPURGE

At define time you can set retention with FOR(days) or TO(date). Until that period has passed, the object is protected from deletion. NOPURGE (the default) means: if the object is still within its retention period, do not delete it; IDCAMS will report an error or refuse. PURGE means: delete regardless of retention. So whenever you need to remove a VSAM object before its retention date—for example to free space or replace it with a new version—you must add PURGE to the DELETE command. Without PURGE, the delete fails when retention has not expired. Many production datasets have FOR or TO set; in those cases PURGE is commonly used when the deletion is intentional and authorized.

ERASE and NOERASE

NOERASE (default) means that when the catalog entry is removed, the space on the volume is not overwritten. The data may still be present until another dataset overwrites it, and in theory it could 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 policy requires that the data be destroyed on delete. ERASE takes longer than NOERASE because it writes to every block of the allocated space. For non-sensitive data, NOERASE is usually sufficient and is faster.

SCRATCH and NOSCRATCH

NOSCRATCH (default) means that after the catalog entry is removed, the space on the volume (the extent in the VTOC) is left as-is. The catalog no longer points to it, but the volume still shows the space as allocated. SCRATCH means that in addition to removing the catalog entry, the space is released so it can be used by other datasets. Use SCRATCH when you want to free DASD. On some systems the exact behavior depends on the catalog and volume type; see your IDCAMS documentation. If you use ERASE and SCRATCH together, the data is overwritten and then the space is released.

FORCE and NOFORCE

NOFORCE (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 only when you are sure no one is using the object and you understand why the normal delete is failing. Deleting an object that is in use can cause abends or data issues in the program that has it open. Your installation may have standards or restrictions on FORCE.

Correct Delete Order: Path, Then AIX, Then Cluster

When a base cluster has an alternate index and one or more paths, the catalog has dependencies: the path points to the AIX, and the AIX points to the base cluster. If you delete the base cluster first, the path and AIX entries still reference it and the delete can fail or leave the catalog inconsistent. The correct order is: (1) Delete all paths that use the AIX. (2) Delete the alternate index. (3) Delete the base cluster. The following table summarizes the order and the reason for each step.

When to Use Each Option

Examples with Full Syntax

Delete a single path

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

Removes only the path catalog entry. No PURGE needed unless the path has retention. The AIX and base cluster are unchanged.

Delete an AIX (after paths are deleted)

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

Deletes the AIX. PURGE is used so that retention (if any) does not block the delete. Ensure all paths that use this AIX have been deleted first.

Delete a cluster and free space

1
2
  DELETE (MY.APPL.PROD.KSDS) CLUSTER PURGE SCRATCH
 

Deletes the cluster and its components and releases the volume space (SCRATCH). PURGE overrides retention. Use when the cluster has no path or AIX, or after you have deleted them.

Delete with secure overwrite

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

Deletes the cluster, overwrites the data with zeroes (ERASE), and releases the space (SCRATCH). Use for sensitive data that must not be recoverable.

Delete multiple paths in one command

1
2
  DELETE (PATH.BY.NAME PATH.BY.ID) PATH
 

Two path names are deleted in one DELETE. Both must be paths; the same options apply to both.

CATALOG and FILE

CATALOG(catalog-name) specifies the catalog that contains the entry. Omit when using the step or job default catalog. When the cluster or AIX is in a user catalog, ensure the job has access (e.g. JOBCAT or STEPCAT) and specify CATALOG if the delete must target that catalog explicitly. FILE(ddname) refers to a DD statement that points to the catalog; it is used when the catalog is allocated via a DD name (e.g. for a user catalog). See your IDCAMS documentation for the exact behavior on your system.

Key Takeaways

• DELETE (entryname [...]) removes catalog entries; specify CLUSTER, ALTERNATEINDEX, or PATH for clarity.
• PURGE overrides retention (FOR/TO); use it when you must delete before the retention date.
• ERASE overwrites data with zeroes before removal; use for sensitive data. NOERASE (default) removes only the catalog entry.
• SCRATCH releases volume space; NOSCRATCH (default) leaves space allocated.
• Delete order when base has path and AIX: path(s) first, then AIX, then cluster.

Explain Like I'm Five

DELETE is like throwing away a folder (cluster), or just the label that says "find by color" (path), or the little list that does the finding (AIX). You have to throw away in order: first the label (path), then the little list (AIX), then the folder (cluster). PURGE means "throw it away even if the rule says keep it until next week." ERASE means "scribble over everything inside before throwing it away so nobody can read it." SCRATCH means "make the space on the shelf available for something else." The syntax reference is the full list of buttons you can press when you run DELETE.

Test Your Knowledge