Introduction (for Experienced)

What is IDCAMS?

  • IDCAMS (Integrated Data Cluster Access Method Services) is the utility program name for access method services (AMS) and used to create, modify and delete the VSAM datasets.
  • The functions of AMS are performed through the different functional commands of IDCAMS.

What is AMS?

  • An access method represents the process that is used to store and retrieve data from the datasets or files.
  • Access Method Services (AMS) is a utility mainly used to define and handle VSAM datasets and integrated catalogs.

IDCAMS Functions -

IDCAMS is mainly a mainframe-related utility used to process or manipulate VSAM datasets or non-VSAM datasets with the help of JCL or other utilities used to run IDCAMS in the background.

IDCAMS allows performing the following tasks -

  • Define, alter, copy, and delete datasets.
  • List catalogs, catalog entries, or datasets.
  • Define and build alternate indexes.
  • Back up and restore VSAM datasets.
  • Print the contents of datasets.
  • Collect information about datasets.
  • Examine the structural consistency of VSAM KSDS.
  • Set cache parameters for DASD devices.
  • Retrieve Direct Access Storage Device (DASD) information.
  • List tape volume (VOLCAT) catalog entries.
  • Detect and diagnose catalog errors.
  • Recover from catalog errors.
  • Define system-managed libraries and volumes.
  • Detect VSAM dataset problems.
  • Encrypt and decrypt datasets.
  • Turn VSAM Record Level Sharing (RLS) on and off.

Invoking IDCAMS Utility -

IDCAMS utility is invoked in the following three ways -

  • Batch mode (With the help of JCL).
  • With TSO commands.
  • Call from the program - A program requires PPI (Problem Program Interface) to invoke IDCAMS.

Batch mode (With the help of JCL) -

We can run IDCAMS as a batch job with the help of JCL as shown below -

Syntax -

//JOBNAME  JOB job-card-parameters
//SYSIN    DD *
  AMS commands and their parameters
  • SYSPRINT DD statement - contains the output of the specified command.
  • SYSIN DD statement - can be a file or instream procedure that contains IDCAMS commands. We can write them in-stream (denoted by the "*") or include the commands in a separate dataset and use the SYSIN DD statement to identify the dataset.

With TSO commands -

The ISPF Command Shell (option 6 from the ISPF main menu) is the best option to use the IDCAMS command interactively.

The command can be triggered like below -

Invoking IDCAMS from TSO

The output is -

Invoking IDCAMS from TSO Output
  • NONVSAM - used to specify sequential or non-vsam files.
  • VSAM - used to specify vsam files.
Note! The PREFIX/NOPREFIX option on the TSO command was introduced in z/OS Version 2.2. Before this release, there is no PREFIX option. So all the files should specify by ignoring userid prefix.

For example - to refer "MATEPK.IDCAMS.JCLLIB", it should specify as "IDCAMS.JCLLIB".

How to validate the IDCAMS return code?

The return code or condition code are used to specify the result of the command and used to decide what has to do next.

There are two return codes to validate the job completion status, and those are -

Return Code Description
Last Condition Code (LASTCC)
  • LASTCC provides the return code of the last executed command.
  • Each command executed has one dedicated LASTCC.
Maximum Condition Code (MAXCC)
  • MAXCC provides the maximum return code of the entire JOB execution, which may contain one or more commands.
  • One IDCAMS utility step may contain one or more commands.
  • MAXCC captures the highest return code of any number of commands.
  • MAXCC is the cumulative return code of the multiple LASTCC.

IDCAMS sets LASTCC at the command level and MAXCC at the step level. If JOB has one step with IDCAMS and IDCAMS contains only one command at the step, both LASTCC and MAXCC have the same return code.

Following are the return codes set by the IDCAMS -

  • 0 (Normal Completion) - Specifies that the functional command successfully finished its processing.
  • 4 (Minor Error) - Specifies processing can continue further. However, a minor error occurred that resulted in issuing a warning message.
  • 8 (Major Error) - Specifies processing can continue further. However, a more severe error resulted in major command specifications being bypassed.
  • 12 (Logical Error) - Specifies that inconsistent parameters are coded, which causes the entire command to be bypassed.
  • 16 (Severe Error) - Specifies a severe error that causes the entire AMS command stream to be flushed, not only the command causing the error.

Example -

Scenario - Let us take an example of creating ESDS and deleting the same in the same step to demonstrate the LASTCC and MAXCC.

Code -

***************************** Top of Data ******************************
//MATEPKE JOB (123),'MTH',CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),            
//             NOTIFY=&SYSUID                                           
//STEP01   EXEC PGM=IDCAMS                                              
//SYSPRINT DD SYSOUT=*                                                  
//SYSIN    DD  *                                                        
  DEFINE CLUSTER(NAME(MATEPK.TEST.ESDS)  -                              
     RECORDSIZE(47,47)    -                                             
     CYLINDERS(2,1)       -                                             
     CISZ(4096)           -                                             
     VOLUMES(DEVHD4)      -                                             
     NONINDEXED           -                                             
     REUSE     )          -                                             
  DELETE 'MATEPK.TEST.ESDS'                                             
**************************** Bottom of Data ****************************

Output -