Symbolic Parameters in JCL

What are Symbolic Parameters?

Symbolic parameters are variables in JCL that allow you to create flexible, reusable job streams. They act as placeholders that are replaced with actual values when the JCL is processed, making it possible to write generic procedures that can be customized for different runs.

Symbolic parameters provide several key benefits:

• Make JCL more flexible and adaptable to different requirements
• Reduce duplication by creating reusable JCL templates
• Simplify maintenance by centralizing common values
• Standardize job submission across an organization
• Support conditional processing based on parameter values

Symbolic Parameter Syntax

Defining Symbolic Parameters

Symbolic parameters are identified by an ampersand (&) prefix followed by a valid JCL name (1-8 characters). For example: &SYSID, &DATE, &FILENAME.

Parameter Naming Rules

• Must begin with an alphabetic character (A-Z) or national character (@, #, $)
• Can contain alphanumeric characters (A-Z, 0-9) and national characters
• Maximum length is 8 characters (not including the & prefix)
• Must follow standard JCL naming conventions

Using Symbolic Parameters in JCL

Defining Parameters with Default Values

You can provide default values for parameters in procedure definitions. If no value is specified when the procedure is called, the default value is used:

1
2
3
4
5
6
7
8
//MYPROC  PROC DSN='SYS1.DATASET',
//             UNIT=SYSDA,
//             SPACE=(CYL,(10,5))
//STEP1   EXEC PGM=MYPROG
//INPUT   DD  DSN=&DSN,
//            UNIT=&UNIT,
//            SPACE=&SPACE,
//            DISP=SHR

Assigning Values with SET Statements

The SET statement explicitly assigns values to symbolic parameters. It must precede the statements that use the parameters:

1
2
3
4
5
6
7
//MYJOB   JOB (ACCT),'MY JOB',CLASS=A
// SET DATE='2023/05/15'
// SET REGION=EAST
//STEP1   EXEC PGM=DATEPROG
//SYSIN   DD  *
PROCESS_DATE=&DATE REGION=®ION
/*

Parameter Substitution in JCL

Parameters are substituted before JCL execution. The substitution follows these rules:

• Parameters are resolved before job execution begins
• Quotes are handled specially during substitution (see examples below)
• A null value is used if no value is provided and no default exists
• Parameter names must be terminated by a delimiter (space, comma, etc.) or period

Parameter Substitution Examples

Basic Substitution

1
2
3
4
// SET SYSID=PROD
//STEP1 EXEC PGM=REPORT
//SYSOUT DD SYSOUT=*
//INPUT DD DSN=&SYSID..DATA,DISP=SHR

1
2
3
//STEP1 EXEC PGM=REPORT
//SYSOUT DD SYSOUT=*
//INPUT DD DSN=PROD.DATA,DISP=SHR

Parameter Concatenation

Notice the double period in &SYSID..DATA. The first period ends the parameter name, and the second is kept as a literal period in the substitution.

Handling Quotes in Parameters

1
2
3
4
5
// SET MSG='HELLO WORLD'
//STEP1 EXEC PGM=MSGPROG
//SYSIN DD *
MESSAGE=&MSG
/*

1
2
3
4
//STEP1 EXEC PGM=MSGPROG
//SYSIN DD *
MESSAGE=HELLO WORLD
/*

Note that quotes used in the SET statement are not included in the substituted value. They only serve to delimit the value, especially when it contains spaces.

Using Symbolic Parameters in Procedures

Procedure Definition with Parameters

1
2
3
4
5
6
7
8
//MYPROC  PROC ENV='TEST',REGION=4M,CLASS=A
//STEP1   EXEC PGM=MYPROG,REGION=®ION
//SYSOUT  DD SYSOUT=&CLASS
//INPUT   DD DSN=&ENV..MASTER.FILE,DISP=SHR
//OUTPUT  DD DSN=&ENV..OUTPUT.FILE,
//           DISP=(NEW,CATLG,DELETE),
//           SPACE=(CYL,(10,5))
// PEND

Overriding Parameters When Calling a Procedure

1
2
3
//RUNJOB  JOB (ACCT),'PRODUCTION RUN',CLASS=A
//RUNPROC EXEC MYPROC,ENV='PROD',CLASS=X
/*

In this example, the job overrides the ENV parameter with 'PROD' and the CLASS parameter with 'X', but uses the default REGION value.

System Symbols vs. Symbolic Parameters

JCL supports both symbolic parameters and system symbols. While they use similar syntax, they serve different purposes:

Common system symbols include:

• &SYSUID - User ID
• &SYSDATE - Current date
• &SYSTIME - Current time
• &SYSNAME - System name
• &SYSPLEX - Sysplex name

Using System Symbols in JCL

1
2
3
4
//MYJOB   JOB (ACCT),'&SYSUID JOB',CLASS=A
//STEP1   EXEC PGM=REPORT
//OUTPUT  DD DSN=&SYSUID..REPORT.&SYSDATE,
//           DISP=(NEW,CATLG,DELETE)

This example creates a dataset name that includes the user ID and current date, providing unique dataset names for each run.

Advanced Parameter Techniques

Conditional Processing Based on Parameters

1
2
3
4
5
6
7
8
9
10
11
12
13
//MYPROC  PROC TYPE='FULL'
//********************************************
//* IF TYPE=FULL, RUN ALL STEPS
//* IF TYPE=INCR, SKIP STEP2
//********************************************
//STEP1   EXEC PGM=PROG1
//...
//STEP2   EXEC PGM=PROG2,
// COND=(0,NE,STEP1,(&TYPE='INCR'))
//...
//STEP3   EXEC PGM=PROG3
//...
// PEND

In this example, STEP2 will be skipped if the TYPE parameter is set to 'INCR' and STEP1 completes successfully.

Concatenating Parameters with Text

For complex concatenation, ensure proper parameter termination:

1
2
3
// SET PREFIX=MY
// SET SUFFIX=DATA
//INPUT DD DSN=&PREFIX..&SUFFIX..FILE,DISP=SHR

After substitution: DSN=MY.DATA.FILE

Nested Parameter Substitution

1
2
3
// SET VER=2
// SET PGMNAME=PROGRAM&VER
//STEP1 EXEC PGM=&PGMNAME

After substitution: PGM=PROGRAM2

Best Practices for Symbolic Parameters

Common Challenges with Symbolic Parameters

Practical Exercise

Frequently Asked Questions