IDCAMS JCL Structure

Running IDCAMS in a batch job means coding a job step with EXEC PGM=IDCAMS and the right DD statements. The two you always need are SYSPRINT (for output) and SYSIN (for commands). Depending on what you do—for example REPRO or PRINT—you may also need additional DDs that your commands reference by name. This page explains the IDCAMS JCL structure: required and optional DDs, how to supply commands, and how to wire up data when copying or printing.

Basic Job Step Structure

A typical IDCAMS step has three parts: the JOB statement (with accounting and other job parameters), the EXEC statement that invokes IDCAMS, and the DD statements that define the inputs and outputs. The EXEC statement is //stepname EXEC PGM=IDCAMS. There is no PARM for passing commands; commands always come from SYSIN. The step name is any valid JCL step name (e.g. STEP1, DEFVSAM, IDCAMS1).

1
2
3
4
5
6
7
8
//MYJOB    JOB (ACCT),'IDCAMS EXAMPLE',CLASS=A,MSGCLASS=X
//*
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  LISTCAT ENTRIES(MY.VSAM.CLUSTER) ALL
/*
 

Here, STEP1 runs IDCAMS. SYSPRINT is allocated to SYSOUT=* so the listing goes to the job log (or the class default). SYSIN is instream data: the lines between //SYSIN DD * and /* are the command input. IDCAMS reads that stream and executes the LISTCAT command. This is the minimal useful structure: EXEC PGM=IDCAMS, SYSPRINT, and SYSIN with at least one command.

Required DD Statements

SYSPRINT is required. IDCAMS uses it for all messages, confirmations, error text, and listing output. If SYSPRINT is missing or not properly allocated, the step can fail or you lose the only record of what IDCAMS did. Allocate it to SYSOUT=* (or another output class) or to a dataset (e.g. a sequential file or PDS member) if you want to keep the listing. A common choice is //SYSPRINT DD SYSOUT=*.

SYSIN is required if you want IDCAMS to execute any commands. SYSIN is the source of the AMS command stream. You can allocate SYSIN to DUMMY or an empty dataset; IDCAMS will then run and do nothing. For normal use you always point SYSIN to instream data (DD *) or a dataset that contains your DEFINE, DELETE, LISTCAT, REPRO, ALTER, or other commands. So in practice both SYSPRINT and SYSIN are required for a useful IDCAMS step.

SYSIN: Instream vs Dataset

You can supply commands in two ways. First, instream: after //SYSIN DD *, you list the commands line by line until a line that contains only /* in the appropriate columns. The system treats everything between DD * and /* as the SYSIN stream. Second, dataset: use //SYSIN DD DSN=your.command.dataset,DISP=SHR (or another disposition). The dataset can be a sequential file or a PDS member (e.g. DSN=MY.PDS(CMD1),DISP=SHR). Instream is convenient for one-off jobs; a dataset is better when you reuse the same commands or when the command list is long.

1
2
3
4
5
6
//SYSIN    DD   *
  DEFINE CLUSTER (NAME(MY.FILE.KSDS) INDEXED RECORDSIZE(80 80) -
    KEYS(10 0) CYLINDERS(2 1))
  LISTCAT ENTRIES(MY.FILE.KSDS) ALL
/*
 

This SYSIN contains two commands: DEFINE CLUSTER and LISTCAT. IDCAMS runs them in order. The hyphen after RECORDSIZE(80 80) continues the DEFINE CLUSTER to the next line, as described in the IDCAMS syntax page.

Optional DDs: REPRO and PRINT

Commands such as REPRO and PRINT refer to input or output by DD name. In the command you specify something like INFILE(INPUT) or OUTFILE(OUTPUT). Those names (INPUT, OUTPUT) are DD names. You must define those DDs in the same step. For example, to copy from a sequential file to a VSAM cluster:

1
2
3
4
5
6
7
8
//STEP1    EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  REPRO INFILE(SEQIN) OUTFILE(MY.VSAM.CLUSTER)
/*
//SEQIN    DD   DSN=MY.SEQ.DATA,DISP=SHR
//*
 

Here, INFILE(SEQIN) tells REPRO to read from the DD named SEQIN. The //SEQIN DD ... statement allocates that dataset. OUTFILE(MY.VSAM.CLUSTER) is the VSAM cluster name; no separate DD is needed for the cluster because REPRO can target a cataloged VSAM dataset by name. If you were copying from one VSAM to another, you might use INDATASET and OUTDATASET with dataset names and no extra DDs, or use INFILE/OUTFILE with DDs. For PRINT, PRINT INFILE(ddname) requires a DD with that name pointing to the dataset you want to print.

Multiple Steps and Condition Codes

You can run IDCAMS in one step and other programs in later steps. IDCAMS sets a condition code (and MAXCC) based on the result of the run. Later steps can check that code with IF/THEN/ELSE or other JCL constructs. Keeping SYSPRINT in each IDCAMS step lets you see what happened in that step even when the job has many steps.

JOBCAT and STEPCAT

When IDCAMS defines, deletes, or lists catalog entries, it uses the catalog available to the job. If your VSAM datasets are in a user catalog, you may need to allocate JOBCAT or STEPCAT to that catalog so IDCAMS (and your application) can find the objects. The IDCAMS step runs in the same job catalog environment as the rest of the job; no special DD name is required for the catalog when using the default or JOBCAT/STEPCAT.

Complete Example: Define and Load in One Job

A common pattern is to define a new VSAM cluster and then load it with REPRO in the same step. You need SYSPRINT, SYSIN with DEFINE and REPRO, and a DD for the input data. The DEFINE creates the cluster; REPRO writes records into it. The cluster name in OUTFILE must match the name you used in DEFINE CLUSTER.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//LOADVSAM EXEC PGM=IDCAMS
//SYSPRINT DD   SYSOUT=*
//SYSIN    DD   *
  DEFINE CLUSTER ( -
    NAME(MY.NEW.KSDS) -
    INDEXED -
    RECORDSIZE(100 100) -
    KEYS(12 0) -
    FREESPACE(10 5) -
    CYLINDERS(5 2)) -
  DATA (NAME(MY.NEW.KSDS.DATA)) -
  INDEX (NAME(MY.NEW.KSDS.INDEX))
  REPRO INFILE(LOADIN) OUTFILE(MY.NEW.KSDS)
/*
//LOADIN   DD   DSN=MY.SEQUENTIAL.INPUT,DISP=SHR
 

Here LOADIN is the DD name used in REPRO INFILE(LOADIN). The sequential dataset MY.SEQUENTIAL.INPUT is the source; MY.NEW.KSDS is the newly defined cluster. Both DEFINE and REPRO run in one SYSIN stream; IDCAMS executes them in order.

DISP and Dataset Allocation

For DDs that point to datasets (e.g. SYSIN as a dataset, or INFILE/OUTFILE datasets), use normal JCL disposition. SYSIN input is usually DISP=SHR (read only). For REPRO output to a VSAM cluster you are creating in the same step, the cluster is created by DEFINE so you do not allocate it as a DD. For REPRO input from a sequential file, DISP=SHR is typical. If you are creating a new sequential file as REPRO output, you would allocate that DD with DISP=(NEW,CATLG), space, etc., and reference it in OUTFILE(ddname).

Common JCL Mistakes

• Forgetting SYSPRINT: The step can fail or abend. Always include SYSPRINT.
• Wrong SYSIN delimiter: Instream data must end with /* on a line by itself (in the correct columns). Missing or misplaced /* can cause the next JCL line to be read as data.
• DD name mismatch: If REPRO says INFILE(INPUT), the JCL must have //INPUT DD ... . The name in the command and the DD name must match.
• Catalog not available: If the cluster is in a user catalog, ensure JOBCAT or STEPCAT is set so IDCAMS can find it for DELETE or LISTCAT, and so DEFINE catalogs it where you expect.

Key Takeaways

• IDCAMS batch step: EXEC PGM=IDCAMS, plus SYSPRINT and SYSIN.
• SYSPRINT is required; it receives all messages and listing output.
• SYSIN is required for commands; use instream (DD *) or a dataset.
• For REPRO or PRINT, allocate any DD names referenced in INFILE/OUTFILE (or equivalent).
• Use JOBCAT/STEPCAT when the cluster or catalog is in a user catalog.

Explain Like I'm Five

Think of IDCAMS as a worker. You give the worker a list of tasks (SYSIN) and the worker needs a place to write the report (SYSPRINT). If one of the tasks is "copy from this box to that box," you have to point out which box is which—those are the extra DD names. The JCL structure is just: run IDCAMS, give it the list of tasks, and give it a place to write the report.

Test Your Knowledge