Symbolic Substitution Delimiters (&)

Purpose

Symbolic substitution delimiters, primarily the ampersand (&) character, are used in JCL to identify variables and parameters that will be replaced with actual values during job processing. This mechanism enables dynamic content in JCL, making jobs more flexible and reusable.

Basic Concepts

The ampersand (&) symbol in JCL serves several important roles:

• Symbolic Parameter Delimiter: It marks the beginning of a symbolic parameter in JCL procedures
• System Symbol Delimiter: It identifies system-defined variables
• JCL Variable Delimiter: It indicates JCL variables defined with SET statements
• Substitution Marker: It signals to the JCL interpreter that substitution should occur

Symbolic Parameter Syntax

Symbolic parameters in JCL procedures follow this basic pattern:

1
2
3
4
//PROC1   PROC PARAM1=DEFAULT1,PARAM2=DEFAULT2
//STEP1   EXEC PGM=PROGRAM1,PARM='&PARAM1'
//DDNAME  DD DSN=PREFIX.&PARAM2.SUFFIX,
//           DISP=SHR

Symbolic Parameter Rules

• Naming: A symbolic parameter:
  • Must begin with an ampersand (&)
  • Can be 1-7 characters after the ampersand
  • Must contain only alphanumeric characters and @, #, $
  • Must begin with an alphabetic character or @, #, $
• Position: Can appear anywhere in a JCL statement where substitution is allowed
• Termination: Can be terminated by a special character, blank space, or a period
  • When a period is used to terminate a symbolic parameter that is followed by other text, the period is not part of the replacement
  • When a period is used to terminate a symbolic parameter at the end of a string, the period becomes part of the final text

Substitution Timing

Substitution occurs at different times depending on the type of symbolic reference:

Common Usage Patterns

Procedure Parameters

1
2
3
4
5
6
7
8
9
10
//MYPROC  PROC DSN=PROD.MASTER,
//             VOL=PROD01,
//             SPACE=(CYL,(10,5))
//STEP1   EXEC PGM=MYPGM
//INPUT   DD DSN=&DSN,
//           DISP=SHR,
//           VOL=SER=&VOL
//OUTPUT  DD DSN=&DSN..BACKUP,
//           DISP=(NEW,CATLG,DELETE),
//           SPACE=&SPACE

This procedure defines parameters with default values that can be overridden when the procedure is called:

1
//STEP1   EXEC MYPROC,DSN=TEST.MASTER,VOL=TEST01

System Symbols

1
2
3
4
5
//STEP1   EXEC PGM=MYPGM
//SYSOUT  DD SYSOUT=*
//OUTPUT  DD DSN=&SYSUID..REPORT.&SYSDATE,
//           DISP=(NEW,CATLG,DELETE),
//           SPACE=(CYL,(1,1))

This example uses system symbols for the user ID and current date to create a unique dataset name.

JCL Variables with SET

1
2
3
4
5
6
7
8
9
10
11
12
13
//STEP1   EXEC PGM=MYPGM
//         SET  PREFIX=PROD
//         SET  SUFFIX=DATA
//INPUT   DD DSN=&PREFIX..&SUFFIX,
//           DISP=SHR
//*
// IF (STEP1.RC = 0) THEN
//         SET  STATUS=SUCCESS
// ELSE
//         SET  STATUS=FAILURE
// ENDIF
//*
//STEP2   EXEC PGM=REPORTER,PARM='&STATUS'

This example uses SET statements to create variables for dataset names and for dynamic decision-making based on a return code.

Nested Symbolic Substitution

1
2
3
4
5
6
//STEP1   EXEC PGM=MYPGM
//         SET  ENV=PROD
//         SET  PRODDSN=PRODUCTION.MASTER
//         SET  TESTDSN=TEST.MASTER
//INPUT   DD DSN=&&&ENV.DSN,
//           DISP=SHR

This example demonstrates nested substitution. If ENV=PROD, &&PRODDSN becomes &PRODDSN which becomes PRODUCTION.MASTER.

Special Considerations

Period (.) and Delimiter Usage

The period is used to terminate a symbolic parameter name when it would otherwise be ambiguous:

1
//DD1     DD DSN=PREFIX.&PARAM.SUFFIX

Without the period after &PARAM, the system would look for a symbol named PARAMSUFFIX.

If the period itself should be part of the value, you can use different approaches:

1
2
//         SET MYVAL=ABC.DEF
//DD1      DD DSN=&MYVAL

Escaping the Ampersand

To include a literal ampersand in JCL (not for substitution), double the ampersand:

1
//STEP1   EXEC PGM=MYPGM,PARM='A&&B'

This passes the literal string 'A&B' to the program.

Null Values

If a symbolic parameter resolves to a null value, different behaviors can occur:

1
2
3
//PROC1   PROC PARAM1=
//STEP1   EXEC PGM=PROGRAM1
//DD1     DD DSN=PREFIX.&PARAM1.SUFFIX,DISP=SHR

In the example, the dataset name becomes PREFIX.SUFFIX when PARAM1 is null.

Common System Symbols

Controlling Symbol Resolution

SYMLIST Parameter

The SYMLIST parameter controls which symbols are eligible for substitution:

1
2
3
4
//STEP1   EXEC PGM=IEBUPDTE
//SYSIN   DD *,SYMLIST=(SYS)
&SYSUID..DATA
/*

This example allows only system symbols to be substituted in the SYSIN data. Options include:

• SYMLIST=NO: No substitution allowed
• SYMLIST=YES: All symbols allowed (default)
• SYMLIST=(SYS): Only system symbols allowed
• SYMLIST=(VAR): Only JCL variables allowed
• SYMLIST=(symbolname,symbolname,...): Only listed symbols allowed

SYMBOLS Parameter

The SYMBOLS parameter on the JOB statement controls substitution for the entire job:

1
2
//MYJOB   JOB (ACCT),'NAME',SYMBOLS=JCLONLY
//STEP1   EXEC PGM=MYPGM

Options include:

• SYMBOLS=JCLONLY: Substitution only in JCL, not in input data
• SYMBOLS=CNVTSYS: System symbols substituted at conversion time
• SYMBOLS=EXECSYS: System symbols substituted at execution time

Common Issues and Troubleshooting

Best Practices

1. Use Meaningful Symbol Names: Choose descriptive names that indicate the purpose or content of the symbol
2. Set Default Values: Always provide reasonable defaults for procedure parameters
3. Document Symbols: Include comments explaining expected values and formats
4. Be Consistent with Periods: Develop a consistent style for using periods with symbols
5. Keep Substitution Logic Simple: Avoid overly complex nested substitution when possible
6. Use SET for Clarity: For complex substitutions, break down into multiple SET statements
7. Test Symbolic JCL: Verify substitution works as expected in all environments
8. Control Symbol Visibility: Use SYMLIST appropriately to prevent unintended substitution
9. Validate Input: For critical parameters, add validation steps before using them

JES2 vs JES3 Considerations

Symbolic substitution behavior is generally the same in both JES2 and JES3 environments, but there are some considerations:

Related Concepts

• SET Statement - Defines JCL variables
• PROC Statement - Defines procedure parameters
• Symbolic Parameters - Parameters in JCL procedures
• JCL Variables - Variables defined with SET statements
• EXPORT Statement - Makes symbols available to subsequent jobs
• SYMLIST Parameter - Controls symbol substitution