Defining and nullifying JCL symbols

When you code JCL symbols, you must define or nullify them in your JCL each time a job runs; otherwise, the system does not substitute text for JCL symbols.

The maximum length of any substitution text that you can assign to a JCL symbol is 255 characters.

To define or nullify a JCL symbol, code the substitution text on one or more of the following:

The EXEC statement that calls procedures: Use the EXEC statement to define substitution texts on statements in the called procedures. The substitution texts you assign override the default substitution texts assigned on the PROC statement. For example:
```
   //STEP1   EXEC   PROC=SEARCH,PARM1='MYDS1.PGM'
```
The system uses a JCL symbol defined on the EXEC statement for any procedures that it invokes. A JCL symbol defined on an EXEC statement is not in effect for subsequent job steps in the same level of procedure nesting. See Using symbols in nested procedures for more information.

If you specify duplicate JCL symbols on an EXEC statement, the system uses the first substitution text as the default.
The PROC statement that begins a procedure: The PROC statement must begin in-stream procedures and can begin cataloged procedures. Use the PROC statement to define default substitution texts for JCL symbols in the procedure (you can override the defaults on the EXEC statement). If you do not define or nullify the substitution text for a JCL symbol on the EXEC statement, the system uses the default substitution text. For example:
```
   //PROC1   PROC   PARM2=OLD,PARM3=111222
```
If you specify duplicate JCL symbols on a PROC statement, the system uses the first substitution text as the default.

Assign only one substitution text to each JCL symbol used in a procedure.
The SET statement that defines and nullifies: JCL symbols Code the SET statement in the JCL before the first use of the JCL symbol. Use the SET statement to define JCL symbols that are used on:
- JCL statements in the JCL stream
- Statements in a procedure (when the EXEC statement that calls the procedure and the PROC statement for the procedure do not also define JCL symbols).
For example:
```
   //LEVEL1   SET   PARM2=NEW,PARM3=DELETE
```
If you define duplicate JCL symbols on a SET statement, the system assigns the last substitution text to the JCL symbol.

Note: The substitution text specified on the SET statement is assigned to the JCL symbol regardless of the logic of the construct. This is because the SET statement is not executed conditionally (such as in the THEN and ELSE clauses of an IF/THEN/ELSE/ENDIF statement construct).

If the SET statement defines a value for a JCL symbol but that symbol is not coded in the JCL, there is no JCL error. Otherwise:

All JCL symbols for which values are defined must be coded in the JCL.
All JCL symbols coded in the JCL must have defined values.

Syntax of JCL symbol definitions: To define a substitution text to a JCL symbol, code:

JCL_symbol_name=substitution_text

Rules for defining JCL symbols:

Define a substitution text that is 1-255 characters long.
Enclose within apostrophes substitution texts that do not fit on a single line. Continue values that do not fit on a single line as described in Continuing JCL statements that contain symbols.
Do not specify the ampersand that identifies the JCL symbol in the procedure.
Define JCL symbols on EXEC, PROC, or SET statements, as described in Defining and nullifying JCL symbols. For example, if the JCL symbol &NUMBER appears on one or more DD statements in a procedure, and you want to substitute the text 3390 for &NUMBER, code one or more of the following:
```
   //SET1   SET   NUMBER=3390

   //STEP1  EXEC   PROC=PROC1,NUMBER=3390

   //PROC1  PROC   NUMBER=3390
```
Do not specify JCL symbols within other JCL symbols. The results can be unpredictable, especially if the imbedded JCL symbol is not previously defined.

Defining names for JCL symbols: IBM recommends that your installation define standard names for frequently used JCL symbols and enforce the use of those names. For example, if your installation frequently assigns department numbers in procedures, define the &DEPT JCL symbol and use it consistently. If your installation plans to provide a standard set of JCL symbols, ensure that all system and application programmers know about those JCL symbols.

You can define names for JCL symbols that are the same as system symbol names. When a JCL symbol has the same name as a system symbol, the substitution text for the JCL symbol overrides the substitution text for the system symbol. For example, if JCL defines a symbol with the name &SYSNAME, which is also the name of a system symbol, the system uses the substitution text that is defined in the JCL.

Defining default substitution texts to JCL symbols: The substitution texts that you define to JCL symbols on the PROC statement serve as defaults. You should assign default values to all JCL symbols in a procedure. The system uses the default values on the PROC statement when no calling EXEC statement or SET statement overrides them.

Using special characters in substitution texts: If a substitution text contains certain special characters, enclose the substitution text in apostrophes (for example, LOC='O''HARE'). The enclosing apostrophes are not considered to be part of the substitution text. See Table 2 for a list of special characters.

If the substitution text contains multiple ampersands and is not enclosed in apostrophes, the system treats each pair of ampersands as a single character.

If the special characters include apostrophes, code each apostrophe as two consecutive apostrophes. You must code four consecutive apostrophes in substitution texts that are to be substituted into a parameter that is enclosed in apostrophes. For example:

   //    SET LOC='O''''HARE'
   //S1  EXEC PGM=IEFBR14,PARM='&LOC'

produces the following equivalent JCL, which is processed correctly:

   //S1  EXEC PGM=IEFBR14,PARM='O''HARE'

However, if you code the following:

   //    SET LOC='O''HARE'
   //S1  EXEC PGM=IEFBR14,PARM='&LOC'

The equivalent JCL is:

   //S1  EXEC PGM=IEFBR14,PARM='O'HARE'

The system fails this statement because the apostrophes resulting from the substitution are unbalanced.

When you want to code a JCL symbolic that consists of two parameters separated by a comma, you may have to enclose the JCL symbolic in triple apostrophes. For example:

   //JOB1   EXEC   PROC1
   //PROC1  PROC   WORK='''1000,500'''
   //STEP1  EXEC   PROC2,WORK=&WORK

The substitution JCL would be:

   //STEP1  EXEC   PROC2,WORK='1000,500'

If the substitution text begins and ends with matched parentheses, do not enclose the value in apostrophes. The parentheses are considered part of the substitution text. For example:

   //TPROC PROC DISP=(NEW,PASS)

If the substitution text within the parentheses contains apostrophes, the apostrophes are considered part of the substitution text. The system does not remove them.

Syntax for nullifying JCL symbols: To nullify a JCL symbol, code:

   JCL_symbol_name=

Do not code the ampersand that identifies the JCL symbol in the procedure.
Do not code a substitution text after the equal sign.
Do not code literal blanks (for example, VALUE=' ').

For example, if the JCL symbol &NUMBER appears in one or more DD statements in a procedure, code one or more of the following to nullify UNIT=&NUMBER:

   //SET2     SET   NUMBER=

   //CALLER   EXEC   PROC=ABC,NUMBER=,ACCT=DID58

   //ABC      PROC  NUMBER=,LOC=POK

When nullifying JCL symbols, keep the following in mind:

When you nullify a JCL symbol, delimiters, such as leading or trailing commas, are not nullified. In some cases, the remaining comma is required; in others it causes a syntax error.
Do not nullify JCL symbols that appear on JCL keywords that do not accept NULL values. The syntax descriptions of the individual keywords specify whether the keywords allow NULL values.
If you use an EXEC statement to nullify a JCL symbol, and a PROC statement specifies a default substitution text for the JCL symbol, the JCL symbol is nullified.

The following sections explain special considerations to make when JCL symbols are positional and not positional.

When a JCL Symbol is Positional: When a JCL symbol is a positional parameter, and another parameter follows it, code a comma to omit the positional parameter. Code commas both before and after the JCL symbol; the required commas remain after the JCL symbol is nullified. For example, &NUMBER for the unit count:

   UNIT=(3390,&NUMBER,DEFER)

When &NUMBER is nullified, the parameter correctly becomes:

   UNIT=(3390,,DEFER)

When a JCL Symbol is Not Positional: When a JCL symbol is not a positional parameter, do not code a comma to omit the parameter. Do not code a comma before the JCL symbol; no commas remain after the JCL symbol is nullified. For example, serial numbers in the VOLUME=SER parameter:

   VOLUME=SER=(&FIRST&SECOND)

If either of the JCL symbols is nullified, a leading or trailing comma does not remain. If you nullify &FIRST and assign 222222 for &SECOND, the parameter correctly becomes:

   VOLUME=SER=(222222)

If you nullify &SECOND and define 111111 to &FIRST, the parameter correctly becomes:

   VOLUME=SER=(111111)

Code a comma when it is required in a substitution text. Enclose the comma in apostrophes (because it is a special character). For example:

   //CALLER  EXEC  PROC=ABC,FIRST=111111,SECOND=',222222'