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.
- 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://STEPLIB DD DSN=MY.&DATA%SET,DISP=OLD
Assume that
SET
has been given a value of LIB. After the first pass, the variableDATA%SET
becomes variableDATALIB
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//DDNAME1 DD DSN=MY.%VAR1%VAR2%VAR3....DATA,DISP=OLD
VAR3
has value SIX andVAR2SIX
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
- 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.
VAR1
to be placed on the line and column that the variable appears on.
will cause the value of?nnVAR1.
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 andVAR2
is MAY (the scale line has been included only for example purposes), the result after variable substitution would be: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 andVAR2
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.
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:
//STEPLIB DD DSN=MY.&LIBRARY.(HDEAQ03),DISP=SHR
or the following statement (without the completing period):
//STEPLIB DD DSN=MY.&LIBRARY(HDEAQ03),DISP=SHR
The JCL line becomes as follows:
//STEPLIB DD DSN=MY.LINKLIB(HDEAQ03),DISP=SHR
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.