JCL Tutorial

The IDCAMS Utility in JCL

Progress0 of 0 lessons

Introduction to IDCAMS

IDCAMS (Integrated Data Catalog Management System) is a versatile utility program for IBM z/OS environments. It serves as the primary tool for working with Virtual Storage Access Method (VSAM) datasets, catalogs, and other dataset types. IDCAMS provides a comprehensive set of commands for dataset management and maintenance.

Key Capabilities

Create and delete VSAM datasets
Copy data between datasets
Modify dataset attributes
Display dataset contents
Manage catalogs
Perform dataset maintenance
Analyze and repair errors

When to Use IDCAMS

VSAM dataset management
Migrating data between files
Troubleshooting dataset issues
Catalog maintenance
Dataset backup and recovery
Creating test data
Examining file contents

Basic IDCAMS JCL Structure

Here's the basic JCL structure for running IDCAMS commands:

jcl

1
2
3
4
5
6
7
8
//IDCJOB   JOB (ACCT),'IDCAMS EXAMPLE',CLASS=A,MSGCLASS=X
//*
//STEP010  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  IDCAMS commands go here
/*
//

The required DD statements for IDCAMS are:

SYSPRINT - Collects output messages and command results
SYSIN - Contains the IDCAMS commands to be executed
Additional DD statements may be required depending on the specific commands used

Common IDCAMS Commands

DEFINE Command

The DEFINE command creates VSAM datasets, alternate indexes, and catalogs.

jcl

1
2
3
4
5
6
7
DEFINE CLUSTER(NAME(MY.VSAM.KSDS) -
       INDEXED -
       RECORDSIZE(80 80) -
       KEYS(10 0) -
       CYLINDERS(5 1) -
       FREESPACE(20 10) -
       SHAREOPTIONS(2 3))

This example creates a Key Sequenced Data Set (KSDS) with fixed 80-byte records, a 10-byte key starting at position 0, primary allocation of 5 cylinders, secondary allocation of 1 cylinder, 20% free space per control interval, and 10% free space per control area.

DELETE Command

The DELETE command removes datasets, catalogs, or catalog entries.

jcl

1
DELETE MY.VSAM.KSDS CLUSTER PURGE ERASE

This example deletes a VSAM cluster. The PURGE option forces deletion even if the retention period hasn't expired. The ERASE option overrides the dataset before deletion for security.

REPRO Command

The REPRO command copies data between datasets.

jcl

1
REPRO INFILE(INPUT) OUTFILE(OUTPUT) COUNT(1000)

This example copies 1000 records from INPUT to OUTPUT. The DD statements INPUT and OUTPUT must be defined in the JCL.

PRINT Command

The PRINT command displays dataset contents.

jcl

1
PRINT INFILE(MYFILE) CHAR

This example prints the contents of MYFILE in character format. Other options include HEX (hexadecimal) and DUMP (both character and hex).

LISTCAT Command

The LISTCAT command displays information about datasets in the catalog.

jcl

1
LISTCAT ENTRIES(MY.VSAM.KSDS) ALL

This example displays detailed information about MY.VSAM.KSDS, including space allocation, record format, and other attributes.

VSAM Dataset Types

IDCAMS is primarily used to manage VSAM datasets, which come in several types:

Type	Description	Use Cases
KSDS	Key Sequenced Data Set Organized by key value	Customer databases, lookup tables, any dataset requiring direct access by key
ESDS	Entry Sequenced Data Set Organized sequentially by entry order	Log files, transaction histories, any dataset accessed primarily sequentially
RRDS	Relative Record Data Set Organized by relative record number	Arrays, fixed-slot datasets, any dataset accessed by numeric position
LDS	Linear Data Set Byte-addressable with no record structure	DB2 tablespaces, memory-mapped datasets, specialized applications

Advanced IDCAMS Examples

Creating a KSDS with Complete Parameters

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
//STEP010  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE CLUSTER (NAME(MY.CUSTOMER.FILE) -
         INDEXED -
         RECORDSIZE(200 200) -
         KEYS(10 0) -
         CYLINDERS(10 5) -
         FREESPACE(20 10) -
         SHAREOPTIONS(2 3) -
         SPEED -
         REUSE -
         RECOVERY -
         CONTROLINTERVALSIZE(4096) -
         VOLUMES(VOLSER1)) -
    DATA (NAME(MY.CUSTOMER.FILE.DATA)) -
    INDEX (NAME(MY.CUSTOMER.FILE.INDEX))
/*

Key parameters explained:

RECORDSIZE(avg max) - 200 byte fixed-length records
KEYS(length offset) - 10-byte key starting at position 0
FREESPACE(CI CA) - Reserved space for future inserts
SHAREOPTIONS(cross-region cross-system) - Controls concurrent access
SPEED - Optimizes initial load performance
REUSE - Allows the cluster to be reused without deletion

Creating an Alternate Index

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//STEP010  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
  DEFINE ALTERNATEINDEX (NAME(MY.CUSTOMER.AIX) -
         RELATE(MY.CUSTOMER.FILE) -
         KEYS(20 50) -
         RECORDSIZE(40 100) -
         CYLINDERS(5 2) -
         NONUNIQUEKEY -
         UPGRADE)
  
  BLDINDEX INFILE(BASE) OUTFILE(AIX) -
          INDATASET(MY.CUSTOMER.FILE) -
          OUTDATASET(MY.CUSTOMER.AIX)
/*
//BASE     DD DSN=MY.CUSTOMER.FILE,DISP=SHR
//AIX      DD DSN=MY.CUSTOMER.AIX,DISP=OLD

This example creates an alternate index for MY.CUSTOMER.FILE with a 20-byte key starting at position 50. The NONUNIQUEKEY option allows duplicate key values. The UPGRADE option ensures the alternate index is updated whenever the base cluster is modified. The BLDINDEX command populates the alternate index.

Conditional Processing with IF-THEN-ELSE

jcl

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
//STEP010  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSOUT   DD SYSOUT=*
//INFILE   DD DSN=MY.INPUT.FILE,DISP=SHR
//OUTFILE  DD DSN=MY.OUTPUT.FILE,DISP=OLD
//SYSIN    DD *
  IF MAXCC = 0 THEN -
    DO
      REPRO INFILE(INFILE) -
            OUTFILE(OUTFILE)
    END -
  ELSE -
    DO
      SET LASTCC = 0
      SET MAXCC = 0
      LISTCAT ENTRIES(MY.INPUT.FILE) ALL
      PRINT INFILE(INFILE) CHAR COUNT(10)
    END
 
  IF LASTCC > 0 THEN -
    CANCEL
/*

This example demonstrates conditional processing in IDCAMS. If the maximum condition code is 0, it copies data from INFILE to OUTFILE. Otherwise, it resets the condition codes, displays catalog information, and prints the first 10 records. If the last operation fails, it cancels further processing.

Complex Data Manipulation with REPRO

jcl

1
2
3
4
5
6
7
8
9
10
11
12
//STEP010  EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//INPUT    DD DSN=MY.INPUT.FILE,DISP=SHR 
//OUTPUT   DD DSN=MY.OUTPUT.FILE,DISP=OLD
//SYSIN    DD *
  REPRO INFILE(INPUT) -
        OUTFILE(OUTPUT) -
        SKIP(100) -
        COUNT(5000) -
        REPLACE -
        REUSE
/*

This example uses REPRO with advanced options: SKIP(100) skips the first 100 records, COUNT(5000) processes only 5000 records, REPLACE overwrites the existing output file, and REUSE reuses the output dataset without reallocating it.

IDCAMS Best Practices

Error Handling

Use IF-THEN-ELSE structures to handle errors
Check condition codes (LASTCC, MAXCC) after operations
Use SET MAXCC=0 to reset error conditions
Include diagnostic commands like LISTCAT after failures
Add VERIFY commands before operations on damaged datasets
Use CANCEL to abort processing after critical errors

Performance Tips

Use SPEED during initial loads
Set appropriate FREESPACE for expected update patterns
Specify BUFFERSPACE for intensive operations
Consider RECOVERY vs. SPEED trade-offs
Optimize RECORDSIZE for data characteristics
Use appropriate CONTROLINTERVALSIZE for your workload

Maintenance Tips

Regularly VERIFY dataset integrity
Use EXAMINE to detect and report structural errors
Monitor space utilization with LISTCAT
Reorganize datasets periodically with REPRO
Back up critical datasets regularly
Document dataset definitions for recovery purposes

Troubleshooting

Check SYSPRINT for detailed error messages
Use PARM='SYNCHK' to syntax check without execution
Add PARM='DEBUG' for additional diagnostic information
Use TEST option for trial runs of destructive commands
Check volume availability and free space
Verify security permissions for datasets and catalogs

Frequently Asked Questions

What is IDCAMS in JCL?

IDCAMS (Integrated Data Catalog Management System) is a multi-purpose utility program provided by IBM for z/OS environments. It is primarily used for creating, modifying, and maintaining catalogs and datasets, especially VSAM datasets. IDCAMS provides functions for dataset management, catalog maintenance, data conversion, and dataset copying through commands like DEFINE, DELETE, REPRO, PRINT, and VERIFY.

What are the main IDCAMS commands?

The main IDCAMS commands include:

DEFINE - Creates VSAM datasets and catalogs
DELETE - Removes datasets or catalogs
REPRO - Copies data between datasets
PRINT - Displays dataset contents
VERIFY - Validates VSAM structures
ALTER - Modifies dataset attributes
LISTCAT - Displays catalog information
EXAMINE - Analyzes dataset errors
EXPORT/IMPORT - Moves VSAM files between systems

How do I create a VSAM file using IDCAMS?

To create a VSAM file using IDCAMS, use the DEFINE command with the appropriate parameters. For example, to create a KSDS (Key Sequenced Data Set):

jcl

1
2
3
4
5
6
7
8
9
//STEP1 EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
  DEFINE CLUSTER(NAME(MY.VSAM.FILE) -
    INDEXED -
    RECORDSIZE(80 80) -
    KEYS(10 0) -
    CYLINDERS(2 1))
/*

This defines a KSDS with 80-byte records, a 10-byte key starting at position 0, with primary allocation of 2 cylinders and secondary of 1 cylinder.

What is the difference between KSDS, ESDS, and RRDS VSAM files?

KSDS (Key Sequenced Data Set) stores records in key sequence, allowing direct access by key and sequential access. Records can be added, modified, or deleted.
ESDS (Entry Sequenced Data Set) stores records in the order they are entered, with access by RBA (Relative Byte Address). Records cannot be deleted but can be modified.
RRDS (Relative Record Data Set) stores records in fixed slots identified by RRN (Relative Record Number), allowing direct access by record number and sequential access. Records can be added, modified, or deleted, but their size cannot change.

How do I copy data between datasets using IDCAMS?

To copy data between datasets using IDCAMS, use the REPRO command. For example:

plaintext

1
REPRO INFILE(INPUT) OUTFILE(OUTPUT)

The INFILE parameter specifies the input dataset, and OUTFILE specifies the output dataset. You can use additional parameters like COUNT(n) to limit the number of records copied, SKIP(n) to skip records from the beginning, or REPLACE to overwrite an existing output dataset.

How do I delete a VSAM file using IDCAMS?

To delete a VSAM file using IDCAMS, use the DELETE command. For example:

plaintext

1
DELETE MY.VSAM.FILE CLUSTER PURGE

This command deletes the VSAM cluster specified. The CLUSTER keyword indicates that all components (data and index) should be deleted. The PURGE option forces deletion even if the retention period has not expired. You can also use options like ERASE to securely overwrite the data before deletion.

How can I view VSAM file information with IDCAMS?

To view VSAM file information, use the LISTCAT command.

For basic information:

plaintext

1
LISTCAT ENTRIES(MY.VSAM.FILE)

For more detailed information:

plaintext

1
LISTCAT ENTRIES(MY.VSAM.FILE) ALL

To list all entries in a catalog:

plaintext

1
LISTCAT CATALOG(CATALOG.NAME) ALL

The ALL parameter shows complete information including space allocation, record sizes, and other attributes. To print the actual contents of a VSAM file, use the PRINT command:

plaintext

1
PRINT INFILE(DDNAME) CHAR

SORT Utility JCL Debugging