IDCAMS Syntax

IDCAMS (Access Method Services) reads commands from the SYSIN stream and executes them in order. To write correct IDCAMS commands you need to know the syntax rules: how commands and parameters are formatted, how to continue a long line, how to comment, and how parameters are separated. This page explains IDCAMS syntax in depth so you can read and write DEFINE, DELETE, ALTER, REPRO, LISTCAT, and other AMS commands correctly. The rules apply whether you run IDCAMS in batch (JCL) or from TSO.

Where IDCAMS Gets Its Commands

In a batch job, you run EXEC PGM=IDCAMS and allocate a SYSIN DD. The SYSIN DD can point to instream data (e.g. //SYSIN DD *) or to a dataset. IDCAMS reads from SYSIN until it hits end-of-file or the instream delimiter /*. Each line (or continued group of lines) is parsed as a command. Output and messages go to SYSPRINT. So the basic flow is: SYSIN = command input, SYSPRINT = message and listing output. Getting the syntax right in SYSIN is what this page is about.

General Command Format

An IDCAMS command has this general shape: the command name first, then parameters. Parameters are usually keyword-value pairs. For example:

1
2
3
4
  DEFINE CLUSTER (NAME(MY.FILE.KSDS) INDEXED RECORDSIZE(80 80) KEYS(10 0))
  DELETE MY.OLD.FILE CLUSTER PURGE
  LISTCAT ENTRIES(MY.FILE.KSDS) ALL
 

The command name (DEFINE, DELETE, LISTCAT) is followed by parameters. Some parameters take a single value in parentheses, e.g. NAME(MY.FILE.KSDS). Some are keywords without values, e.g. INDEXED, PURGE, ALL. Multiple parameters are separated by spaces. The following table summarizes the main syntax rules.

Continuation Character

IDCAMS commands can be long. To continue a command onto the next line, put a space and then a hyphen - at the end of the line. IDCAMS treats the next line as part of the same command. The hyphen is the continuation character. For example:

1
2
3
4
5
6
7
8
9
10
  DEFINE CLUSTER ( -
    NAME(USERID.CUSTOMER.KSDS) -
    INDEXED -
    RECORDSIZE(200 300) -
    KEYS(10 0) -
    FREESPACE(10 5) -
    CYLINDERS(10 5)) -
  DATA (NAME(USERID.CUSTOMER.KSDS.DATA)) -
  INDEX (NAME(USERID.CUSTOMER.KSDS.INDEX))
 

Here, each line that is part of the DEFINE CLUSTER ends with - except the last line of the command. The hyphen must be preceded by at least one space. If you omit the hyphen, IDCAMS assumes the command (or the current parameter) ends at that line. One important restriction: you cannot put a hyphen between a parameter keyword and its value in a way that breaks the pairing. For example, NAME(- on one line and MY.FILE) on the next can cause problems. Keep keyword(value) together on one line, or use the plus sign (+) for continuation within a parameter in implementations that support it. In practice, continue after a complete parameter and you will avoid issues.

Some installations or IBM documentation mention using the plus sign (+) to continue within a parameter (e.g. between a keyword and its subparameters). When in doubt, keep each keyword(value) on a single line and use the hyphen only between parameters.

Parameter Formats

Parameters follow a few common patterns. Understanding these helps you read existing JCL and write new commands.

NAME(...) almost always takes a single dataset or object name. KEYS(10 0) means key length 10, key offset 0. RECORDSIZE(200 300) typically means minimum record length 200, maximum 300. The exact meaning of each parameter is defined per command (see DEFINE CLUSTER, DELETE, etc.). The important thing syntactically is: keyword, then parentheses around the value(s), and spaces separating parameters.

Comments

You can insert comments in SYSIN by enclosing them between /* and */. The /* must start in column 2 or later (column 1 is often reserved for JCL or control characters in some environments). Everything from /* to */ is ignored by IDCAMS. For example:

1
2
3
4
5
6
7
  /* Define KSDS for customer file */
  DEFINE CLUSTER (NAME(MY.CUSTOMER.KSDS) INDEXED RECORDSIZE(100 100) KEYS(8 0))
  /* Delete old test cluster
  DELETE MY.TEST.CLUSTER CLUSTER PURGE
  */
  LISTCAT ENTRIES(MY.CUSTOMER.KSDS) ALL
 

The first comment documents the DEFINE. The second comment spans two lines and effectively comments out the DELETE command. So you can use comments both for documentation and to temporarily disable a command.

Multiple Commands in One SYSIN

You can place multiple IDCAMS commands in the same SYSIN stream. IDCAMS executes them in the order they appear. Each new command starts when the previous one has ended (i.e. when a line does not end with a continuation hyphen, or when a new command name is read). For example:

1
2
3
4
  DEFINE CLUSTER (NAME(MY.FILE) NONINDEXED RECORDSIZE(80 80) CYLINDERS(1))
  LISTCAT ENTRIES(MY.FILE) ALL
  REPRO INFILE(INPUT) OUTFILE(MY.FILE)
 

Here, DEFINE CLUSTER runs first and creates the cluster. LISTCAT runs next and lists the new entry. REPRO then copies data from the dataset pointed to by the INPUT DD to the cluster MY.FILE. If any command fails with a high condition code, later commands may still run depending on how your installation configures IDCAMS; often the step continues and MAXCC reflects the highest return code.

Case and Blanks

IDCAMS command names and keywords are not case-sensitive. DEFINE, define, and Define are equivalent. INDEXED and indexed are the same. Dataset names and catalog names follow normal z/OS naming rules; case may matter for the catalog depending on the catalog type. Blanks (spaces) are used to separate the command from parameters and parameters from each other. Leading and trailing blanks on a line are usually ignored. Multiple blanks between tokens are typically treated as one separator.

Dataset Names in Commands

When you specify a dataset name in a parameter (e.g. NAME(MY.VSAM.FILE) or DELETE MY.FILE CLUSTER), you can often omit quotes. If the name contains special characters or you want to be explicit, some environments allow single quotes around the name (e.g. 'MY.VSAM.FILE'). Check your installation standards. In LISTCAT and similar commands, ENTRIES(name) specifies which catalog entry to list; the name can be the cluster name, component name, or a pattern depending on the command.

Common Syntax Errors

• Missing space before hyphen: The continuation hyphen must be preceded by at least one space. Without it, IDCAMS may treat the hyphen as part of a parameter value or flag a syntax error.
• Unclosed parentheses: Every ( must have a matching ). If you continue across lines, ensure you did not leave a parenthesis open.
• Wrong parameter order: Some parameters have a fixed order (e.g. KEYS(length offset)). Swapping values can cause unexpected behavior or errors.
• Comment in column 1: If /* is in column 1, some systems may not recognize it as a comment. Start /* in column 2 or later.

Key Takeaways

• Commands are read from SYSIN; each command starts with a command name (DEFINE, DELETE, ALTER, REPRO, LISTCAT, etc.) followed by parameters.
• Use a space and hyphen (-) at the end of a line to continue the command on the next line.
• Parameters are usually keyword(value) or keyword(value1 value2). Separate parameters with spaces.
• Comments are enclosed in /* and */; /* should start in column 2 or later.
• Multiple commands can appear in one SYSIN stream; IDCAMS executes them in order.

Explain Like I'm Five

Imagine you are giving the computer a list of instructions. Each instruction has a verb (like DEFINE or DELETE) and then the details in parentheses. If an instruction is too long to fit on one line, you put a little dash at the end and keep writing on the next line. The computer reads everything until the line without a dash. Comments are like sticky notes: you write /* note */ and the computer skips over them. IDCAMS syntax is the set of rules for how to write those instructions so the computer understands you.

Test Your Knowledge