VSAM IDCAMS Commands: DEFINE, REPRO, LISTCAT, DELETE

A VSAM cluster usually enters a batch job through IDCAMS. One job step can define the cluster, load sorted records with REPRO, print catalog details with LISTCAT, or delete a test cluster before the next run.

Check before change.

What is IDCAMS?

IDCAMS is the z/OS program name for Access Method Services. It is commonly used to define and manage VSAM data sets and integrated catalog facility catalog entries. IBM lists tasks such as defining VSAM data sets, building alternate indexes, copying data sets, printing content, deleting data sets, listing catalog information, diagnosing catalog errors, and recovering from catalog problems.

For a developer, the most common use is simple: run EXEC PGM=IDCAMS, place commands in SYSIN, and review messages in SYSPRINT.

Where IDCAMS fits with VSAM

VSAM stores records on DASD and organizes them as KSDS, ESDS, RRDS, or LDS data sets. IBM describes VSAM records as being arranged by key, relative byte address, or relative record number, depending on the data set type. IDCAMS is the usual batch utility used to create and maintain those cataloged VSAM objects.

Basic IDCAMS JCL

//STEPIDC  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  LISTCAT ENTRIES(PROD.CUST.KSDS) ALL
/*

SYSPRINT is where you read IDCAMS messages, command echo, return codes, and catalog details. Do not skip it when a VSAM job fails. The message text usually tells you whether the issue is catalog, allocation, duplicate key, security, or record format.

IDCAMS command quick reference

Command	Use it for	Common check
DEFINE CLUSTER	Create a VSAM cluster and catalog entry.	Name, space, record size, key length, key offset, volume or SMS class.
REPRO	Load or copy data between VSAM and non-VSAM data sets.	Input sorted by key for a KSDS initial load.
LISTCAT	List catalog information for a cluster, data component, index, path, or AIX.	High-used RBA, allocation, component names, index details.
DELETE	Delete a cataloged VSAM object.	Correct cluster name and environment.
ALTER	Change selected catalog attributes.	Whether the target attribute can be changed for that object.
BLDINDEX	Build an alternate index after defining it.	Base cluster, alternate key definition, path, and upgrade behavior.
EXPORT and IMPORT	Move VSAM data and related catalog information through a portable data set.	Target catalog and naming rules.
VERIFY	Correct catalog high-used information after a VSAM data set was not closed normally.	Whether an abended update job left the cluster in an uncertain state.
DIAGNOSE	Check catalog structures such as BCS and VVDS entries.	Catalog consistency errors.

DEFINE CLUSTER example for KSDS

A KSDS uses a key field inside the record. For a customer file, the key might be a ten-byte customer number starting at byte 1. IDCAMS uses zero-based key offset on KEYS(length offset), so a key that starts at the first byte uses offset 0.

//DEFKSDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER (NAME(PROD.CUST.KSDS) -
          INDEXED -
          KEYS(10 0) -
          RECORDSIZE(100 200) -
          CYLINDERS(5 2) -
          FREESPACE(10 10) -
          CISZ(4096)) -
     DATA  (NAME(PROD.CUST.KSDS.DATA)) -
     INDEX (NAME(PROD.CUST.KSDS.INDEX))
/*

IBM notes that DEFINE CLUSTER creates the catalog entry without moving data. The load happens later, often through REPRO.

REPRO example to load a KSDS

REPRO copies records into the new VSAM cluster. For a first load into a KSDS, make sure the input records are already sorted in key order and do not contain duplicate keys.

//LOADKSDS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INFILE   DD DSN=PROD.CUST.SORTED,DISP=SHR
//SYSIN    DD *
  REPRO INFILE(INFILE) OUTDATASET(PROD.CUST.KSDS)
/*

If the load stops, read SYSPRINT. Duplicate keys, wrong record length, security failure, or a missing catalog entry all leave different message trails.

LISTCAT example for a cluster

LISTCAT is the safest first command when you are unsure what exists. It shows catalog information and can confirm the cluster name before a delete, copy, or application test.

//CATINFO  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  LISTCAT ENTRIES(PROD.CUST.KSDS) ALL
/*

Use it before changing a production object. The output can show whether you are looking at the cluster, data component, index component, alternate index, or path.

DELETE example for a test cluster

DELETE removes a VSAM object from the catalog. In test jobs, it is common to delete a cluster and create it again before loading fresh data. In production, use site change controls and confirm the data set name before running it.

//DELKSDS  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE TEST.CUST.KSDS CLUSTER
  IF LASTCC > 8 THEN SET MAXCC = 8
/*

The IF LASTCC pattern is sometimes used in test setup so a missing old test cluster does not fail the whole job. Do not copy that pattern into production deletes without review.

VSAM data set types

Type	Access pattern	Typical use
KSDS	By key and sequential key order.	Customer, account, employee, policy, and part-master files.
ESDS	By relative byte address or entry sequence.	Append-style logs and files read in arrival order.
RRDS	By relative record number.	Fixed slot lookup by numeric record number.
LDS	Byte-addressable linear storage.	Specialized system and application use where records are not the normal unit.

Alternate index commands

When a base KSDS needs another lookup path, define an alternate index and path, then build the index with BLDINDEX. IBM notes that alternate indexes can support access by another fixed-position key, such as employee name or department code, when the base key is employee number.

//BLDAIX   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  BLDINDEX INDATASET(PROD.CUST.KSDS) -
           OUTDATASET(PROD.CUST.NAME.AIX)
/*

Check whether the alternate index is in the upgrade set. If it is not, updates made through the base cluster may not maintain the alternate index the way the application expects.

Return-code checks

IDCAMS supports conditional processing with values such as LASTCC and MAXCC. A common test job deletes an old cluster, tolerates the missing-cluster condition, then defines a new one.

  DELETE TEST.CUST.KSDS CLUSTER
  IF LASTCC = 8 THEN SET MAXCC = 0

  DEFINE CLUSTER (NAME(TEST.CUST.KSDS) -
          INDEXED KEYS(10 0) RECORDSIZE(100 200) -
          CYLINDERS(1 1))

Use return-code handling to make setup jobs repeatable, but keep the logic narrow. A delete failure caused by security or catalog damage should not be treated the same as a harmless missing test cluster.

Common mistakes

Using the wrong key offset

KEYS(10 0) means a ten-byte key beginning at offset 0, which is the first byte of the record. Many file layouts count fields from position 1, so convert carefully.

Loading an unsorted KSDS

A KSDS initial load expects records in key order. Sort the input first and check duplicate keys before running REPRO.

Deleting by memory instead of LISTCAT

Run LISTCAT before a risky change. Similar names such as TEST.CUST.KSDS and PROD.CUST.KSDS are not mistakes you want to find after DELETE.

Forgetting the data and index components

A KSDS cluster has a data component and an index component. When you inspect catalog output, make sure you understand which entry you are reading.

Related VSAM and JCL guides

For nearby topics, read VSAM concepts, when to use KSDS, ESDS, RRDS, and LDS, DEFINE CLUSTER examples, VSAM control interval, COBOL indexed file organization, and JCL utilities.

External references

Technical notes in this refresh were checked against IBM IDCAMS catalog utility guidance, IBM Access Method Services command list, IBM defining VSAM files with DEFINE CLUSTER, and IBM VSAM data set organization notes.

FAQ

What is IDCAMS used for in VSAM?

IDCAMS is used to define, load, copy, list, alter, delete, and check VSAM data sets and catalog entries.

Which IDCAMS command creates a VSAM cluster?

DEFINE CLUSTER creates the VSAM cluster and catalog entry. For a KSDS, include key length and key offset with KEYS.

Which IDCAMS command loads records into a VSAM file?

REPRO loads or copies records. For a KSDS first load, the input should be sorted in key order.

How do I check a VSAM cluster before changing it?

Run LISTCAT ENTRIES(cluster-name) ALL and review SYSPRINT before running commands such as DELETE, ALTER, or REPRO.