IDCAMS Utility

What is IDCAMS?

IDCAMS (Integrated Data Conversion And Migration Services) is a powerful utility program that provides Access Method Services (AMS) for managing VSAM datasets and catalog operations in z/OS environments. It's one of the most versatile utilities in the mainframe environment, offering functionality to define, manipulate, and manage VSAM datasets and catalog structures.

IDCAMS is primarily used for:

• Creating (DEFINE), modifying (ALTER), and deleting (DELETE) VSAM datasets
• Copying and converting data between different dataset types (REPRO)
• Listing catalog entries (LISTCAT) and displaying dataset contents (PRINT)
• Verifying and diagnosing VSAM dataset issues (VERIFY, EXAMINE)
• Managing ICF catalogs and their structures

JCL Requirements

To use IDCAMS, you need to specify the following in your JCL:

• EXEC statement specifying PGM=IDCAMS
• SYSPRINT DD to capture output messages
• SYSIN DD containing the IDCAMS commands to execute
• Additional DD statements as needed for specific operations

Basic IDCAMS JCL template:

1
2
3
4
5
//IDCAMS   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  AMS commands go here
/*

IDCAMS Command Structure

IDCAMS commands follow a specific structure:

• Command verbs (like DEFINE, DELETE, REPRO) specify the operation
• Object types (like CLUSTER, PATH, ALIAS) specify what is being affected
• Parameters define the specific characteristics or options

Commands can be coded in a free-form format with conventional syntax rules:

• Commands can span multiple lines
• Each command must end with a semicolon (;)
• Parameters can be abbreviated to the minimum unique characters
• Comments can be included using /* comment */

DEFINE Command

The DEFINE command creates VSAM datasets and catalog structures.

Creating a KSDS (Key Sequenced Data Set)

1
2
3
4
5
6
7
8
9
10
11
12
//DEFKSDS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER (NAME(MY.KSDS.DATASET) -
                 VOLUMES(VOLSER) -
                 CYLINDERS(5 1) -
                 KEYS(8 0) -
                 RECORDSIZE(80 80) -
                 SHAREOPTIONS(2 3)) -
         DATA (NAME(MY.KSDS.DATASET.DATA)) -
         INDEX (NAME(MY.KSDS.DATASET.INDEX))
/*

Creating an ESDS (Entry Sequenced Data Set)

1
2
3
4
5
6
  DEFINE CLUSTER (NAME(MY.ESDS.DATASET) -
                           VOLUMES(VOLSER) -
                           CYLINDERS(2 1) -
                           RECORDSIZE(80 80) -
                           NONINDEXED)
 

Creating an RRDS (Relative Record Data Set)

1
2
3
4
5
6
  DEFINE CLUSTER (NAME(MY.RRDS.DATASET) -
                           VOLUMES(VOLSER) -
                           CYLINDERS(1 1) -
                           RECORDSIZE(80 80) -
                           NUMBERED)
 

DELETE Command

The DELETE command removes entries from catalogs and optionally deletes the associated datasets.

1
2
3
4
5
6
//DELETE   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DELETE MY.KSDS.DATASET CLUSTER PURGE;
  DELETE MY.GENERATION.DATASET GDG FORCE;
/*

Key parameters:

• PURGE: Bypasses retention period checks
• FORCE: Causes deletion even if errors are encountered
• CLUSTER/AIX/PATH: Specifies the type of entry to delete

ALTER Command

The ALTER command modifies attributes of existing datasets or catalog entries.

1
2
3
4
5
6
7
8
//ALTER    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  ALTER MY.KSDS.DATASET -
        NEWNAME(MY.NEW.DATASET.NAME) -
        OWNER(NEWUSER) -
        AUTHORIZATION(READ);
/*

Common ALTER parameters:

• NEWNAME: Changes the name of the entry
• OWNER: Changes the owner of the entry
• AUTHORIZATION: Modifies access permissions
• TO/FOR: Adjusts allocation sizes
• BUFFERSPACE: Modifies buffer allocation

REPRO Command

The REPRO command copies data between datasets, potentially converting between different formats.

1
2
3
4
5
6
7
//REPRO    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INDD     DD DSN=SOURCE.DATASET,DISP=SHR
//OUTDD    DD DSN=TARGET.DATASET,DISP=OLD
//SYSIN    DD *
  REPRO INFILE(INDD) OUTFILE(OUTDD)
/*

Alternative syntax using dataset names directly:

1
2
3
4
5
  REPRO INDATASET(SOURCE.DATASET) -
                          OUTDATASET(TARGET.DATASET) -
                          SKIP(10) -
                          COUNT(500)
 

Key REPRO parameters:

• INFILE/INDATASET: Specifies input source
• OUTFILE/OUTDATASET: Specifies output target
• SKIP(n): Skips n records before starting copy
• COUNT(n): Copies only n records
• REPLACE: Overwrites existing records (for KSDS)

PRINT Command

The PRINT command displays the contents of a dataset.

1
2
3
4
5
6
7
8
//PRINT    EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  PRINT INDATASET(MY.DATASET) -
        CHAR -
        SKIP(5) -
        COUNT(10)
/*

Print format options:

• CHAR: Character format (default)
• HEX: Hexadecimal format
• DUMP: Hex and character side by side

LISTCAT Command

The LISTCAT command displays information about catalog entries.

1
2
3
4
5
//LISTCAT  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD /*
  LISTCAT ENTRIES(MY.DATASET) ALL
/*

Common LISTCAT options:

• ENTRIES: Lists specific catalog entries
• LEVEL: Lists entries at a specific qualifier level
• ALL: Shows all information
• NAME: Shows entry names only
• VOLUMES: Shows volume information
• HISTORY: Shows creation/modification dates

Error Handling with IF-THEN-ELSE

IDCAMS provides conditional processing using IF-THEN-ELSE constructs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
//IFELSE   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD /*
  IF LASTCC = 0 THEN -
    REPRO INDATASET(SOURCE.DATA) -
          OUTDATASET(TARGET.DATA)
  ELSE -
    PRINT INDATASET(ERROR.LOG)
 
  IF MAXCC = 0 THEN -
    LISTCAT ENTRIES(TARGET.DATA) ALL
  ELSE -
    SET MAXCC = 0
/*

Condition codes:

• LASTCC: Return code from the last command
• MAXCC: Highest return code encountered so far
• SET MAXCC: Reset the maximum condition code

Practical Examples

Example 1: Define, Load, and List a KSDS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
//DEFLOAD  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INDATA   DD *
Record1Key Data for the first record
Record2Key Data for the second record
Record3Key Data for the third record
/*
//SYSIN    DD *
  /* Define the KSDS first */
  DELETE MY.EXAMPLE.KSDS CLUSTER PURGE
  IF LASTCC <= 8 THEN -
    DEFINE CLUSTER (NAME(MY.EXAMPLE.KSDS) -
                   VOLUMES(VOLSER) -
                   TRACKS(1 1) -
                   KEYS(10 0) -
                   RECORDSIZE(50 50))
 
  /* Load data into the KSDS */
  IF LASTCC = 0 THEN -
    REPRO INFILE(INDATA) -
          OUTDATASET(MY.EXAMPLE.KSDS)
 
  /* List the contents of the KSDS */
  IF LASTCC = 0 THEN -
    PRINT INDATASET(MY.EXAMPLE.KSDS) CHAR
/*

Example 2: Creating and Managing a GDG

1
2
3
4
5
6
7
8
9
10
11
12
//DEFGDG   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD /*
  /* Define a Generation Data Group Base */
  DEFINE GDG (NAME(MY.GDG.BASE) -
             LIMIT(5) -
             NOEMPTY -
             SCRATCH)
 
  /* List the GDG information */
  LISTCAT ENTRIES(MY.GDG.BASE) ALL
/*

Example 3: Backing up a VSAM Dataset

1
2
3
4
5
6
7
8
9
//BACKUP   EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//BACKUP   DD DSN=MY.VSAM.BACKUP,DISP=(NEW,CATLG),
//            SPACE=(CYL,(5,1)),DCB=(RECFM=VB,LRECL=32760,BLKSIZE=32760)
//SYSIN    DD /*
  REPRO INDATASET(MY.VSAM.DATASET) -
        OUTFILE(BACKUP) -
        ENVIRONMENT(BLOCKSIZE(32760))
/*

Exercises

Frequently Asked Questions

Test Your Knowledge