Coding variables in JCL

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.

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:

//STEPLIB DD DSN=MY.&DATA%SET,DISP=OLD

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:

//DDNAME1 DD DSN=MY.%VAR1%VAR2%VAR3....DATA,DISP=OLD

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.

//DDNAME1 DD DSN=MY.%VAR1%VAR2%VAR3(MEMBER),DISP=OLD

?VAR1.

?nnVAR1.

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:

 //SYSIN DD *
 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7..
          ?20VAR1.?9VAR2.

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:

 //SYSIN DD *
 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7..
         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:

 //SYSIN DD *
 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7..
          ?20VAR1.?21VAR2.
 /*

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:

 //SYSIN DD *
 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7..
 THIS IS?40VAR1. THE STANDARD DATA.           IS A WET MONTH.

VAR1 is APRIL. After substitution, the line becomes:

 //SYSIN DD *
 ....+....1....+....2....+....3....+....4....+....5....+....6....+....7..
 THIS IS         THE STANDARD DATA.     APRIL IS A WET MONTH.