IBM Workload Automation, Version 9.3

Coding variables in JCL

Coding variables in JCL follows certain rules.

Variable names, either user-defined or supplied with the product, can be of up to 8 alphanumeric characters, the first of which must be alphabetic. Variable values can be of up to 44 alphanumeric characters.

When using a variable in a job, precede it with an ampersand (&), a percent sign (%), or a question mark (?). The symbol preceding the variable determines how the variable is resolved:
Ampersand (&)

These variables are substituted from left to right within the line. Ampersand variables correspond to the standard variables in z/OS® JCL procedures and behave accordingly. Refer to JCL Reference.

If an &-variable is immediately followed by a % variable (that is, there is no intervening termination character), a compound variable is formed. See Compound variables. A compound variable is also formed if an &-variable immediately follows a ?-variable.

Any string that begins with && is not substituted. This is because the double ampersand within JCL is usually used to denote a temporary data set. Any such strings are unaffected by the variable substitution.

Percent sign (%)
These variables can be used to form simple variables and compound variables.
Simple variables
If the variable is preceded by a % and ended by a period or any termination character other than %, a value is assigned to the variable, and substitution, for this variable, completes.
Compound variables
Using JCL substitution, you can form compound variables. A compound variable is made up of a concatenation of:
  • A variable (of any type) followed by a percent variable with no intervening periods or other termination symbols
  • A question mark variable followed by an ampersand variable with no intervening periods or other termination symbols

The values of the percent variables making up a compound variable are not substituted directly. Instead, these values are used to form new variables, which have their own values assigned. These variables are resolved in a series of passes. The individual variables making up the compound variable are resolved, moving from right to left.

For example, consider the following line of JCL from a job:

Assume that SET has been given a value of LIB. After the first pass, the variable DATA%SET becomes variable DATALIB because the right-most percent variable is resolved on the first pass. This first pass has now formed a new variable, DATALIB, which the agent will try to resolve on its next pass across this line of JCL.

Compound variables can be made up of a sequence of many %-variables. Consider the following:
Assume that VAR3 has value SIX and VAR2SIX has value JUNE. On the first pass over this line of JCL, the variable %VAR1%VAR2%VAR3....DATA becomes %VAR1%VAR2SIX...DATA. On the second pass, the variable %VAR1%VAR2SIX. becomes %VAR1JUNE..DATA. The value assigned to %VAR1JUNE. determines the final value that is substituted.

At every substitution, a period was discarded when the variable was substituted. You must specify the correct number of periods to ensure that the substitution is performed correctly. In the preceding example, an extra period was required to denote the beginning of the second-level data set qualifier.

In the next example, you need only one parenthesis to complete the compound variable. This is because the parenthesis is not discarded at substitution.
Question mark (?)
Question mark variables are positional; that is, you can specify in which column on the line the variable value should begin when the variable is substituted. The position at which the value is placed is specified in the job where the variable is used. For example:
will cause the value of VAR1 to be placed on the line and column that the variable appears on.
will cause the value of VAR1 to be placed on the line that the variable appears on, starting at the column number specified by nn.

More than one ?-variable can appear on a JCL line. The positions of the variables themselves have no influence on the positions of the variable values. These positions are decided by the column number specified for the variable. For example:


where VAR1 is APRIL and VAR2 is MAY (the scale line has been included only for example purposes), the result after variable substitution would be:

         MAY        APRIL

The value of ?-variables is evaluated in the same way as for &- and %-variables, and in the same sequence. However, ?-variables are substituted only after all percent and ampersand variables have been substituted. This is because the value of the ?-variable can be placed only in areas of the line that are blank. The agent can only know which areas of a line will be blank after ampersand and percent substitution has occurred.

Tabular variables cannot overlap. That is, the values of two different variables cannot be defined to occupy the same space on a line. The space that the variables themselves originally take up is ignored when substitution occurs. For example:


where VAR1 is APRIL and VAR2 is MAY, the substitution would be invalid because the two variables are attempting to use columns 21, 22, and 23.

The agent changes the space occupied by the variable to spaces, if it is not covered by the substituted value. For example:


VAR1 is APRIL. After substitution, the line becomes:

The agent has changed the space occupied by the variable to spaces. The other data in the line does not move.
Note: Predefined variables do not have an implied position. When these variables are specified as tabular variables, you must include the column number. For example, ?OADID will not be accepted; however, ?20OADID is valid: the application ID is substituted at column 20.

You can use a variable repeatedly within the job using different prefix symbols.

An ampersand or percent variable can be assigned a value that is itself a variable.

A period denotes the end of a variable name. To maintain compatibility with variable substitution within z/OS JCL procedures, the agent for z/OS will assume that a variable has ended (even if the completing period is missing) if the variable is followed by one of the symbols listed in the following table.
Table 1. Symbols that mark the end of variables.
Symbol Description
, Comma
/ Forward slash
' Single quote
( Left parenthesis
) Right parenthesis
* Asterisk
+ Plus sign
- Dash
= Equals sign
  Blank (␢)

For example, if LIBRARY is given the value LINKLIB for the following statement:


or the following statement (without the completing period):


The JCL line becomes as follows:


The product assumes that the variable LIBRARY ends when it detects the left parenthesis '('.

The completing period is discarded when a variable is substituted. Other termination symbols are left in place.