Symbolic Parameters

Purpose

Symbolic parameters in JCL allow for variable substitution, making JCL more flexible and reusable. They enable you to create general-purpose JCL that can be customized at execution time with different values. This is particularly useful for procedures (PROCs) where the same process needs to be executed with different datasets, program names, or other parameters.

Syntax

Defining Symbolic Parameters

1
//procstep PROC PARAM1=default1,PARAM2=default2,...

Using Symbolic Parameters

1
//step DD DSN=prefix.&PARAM1..SUFFIX

Overriding Symbolic Parameters

1
//step EXEC procname,PARAM1=value1,PARAM2=value2

Parameter Rules

Naming Conventions

• Names must be 1-8 characters long
• Valid characters include A-Z, 0-9, @, #, and $
• The first character must be alphabetic (A-Z) or one of @, #, or $
• Names are not case-sensitive (converted to uppercase)
• Avoid using reserved words or system parameter names

Value Formats

• Values can be up to 255 characters long
• Special characters need to be enclosed in apostrophes (')
• To include an apostrophe in a value, use two consecutive apostrophes ('')
• Values with more than one substring should be enclosed in parentheses
• Values with no characters (null values) are represented by ()

Concatenation Rules

When concatenating symbolic parameters with other text:

• Use a period (.) to separate the symbolic parameter from the following text
• The period does not appear in the substituted text
• Two consecutive periods are needed if a period should appear in the output
• If the parameter is at the end of the string, no period is required

Usage Examples

Basic Procedure with Symbolic Parameters

1
2
3
4
5
//PAYPROC  PROC SYSID='PROD',DAY=TODAY
//STEP1    EXEC PGM=PAYROLL
//INPUT    DD   DSN=&SYSID..PAYROLL.&DAY,DISP=SHR
//OUTPUT   DD   DSN=&SYSID..PAYROLL.OUTPUT,DISP=(NEW,CATLG)
//         PEND

This procedure defines two symbolic parameters (SYSID and DAY) with default values that are used in dataset names.

Calling Procedure with Parameter Override

1
2
//PAYRUN   JOB (ACCT#),'JOHN DOE',CLASS=A
//STEP1    EXEC PAYPROC,SYSID=TEST,DAY=MONDAY

This job executes the PAYPROC procedure, overriding the SYSID parameter with 'TEST' and the DAY parameter with 'MONDAY'.

Using Symbolic Parameters in In-stream Procedures

1
2
3
4
5
6
7
//PAYJOB   JOB (ACCT#),'JOHN DOE',CLASS=A
//PAYPROC  PROC ENV='PROD',DATE=CURRENT
//STEP1    EXEC PGM=PAYROLL
//INPUT    DD   DSN=&ENV..PAYROLL.&DATE,DISP=SHR
//         PEND
//*
//RUN      EXEC PAYPROC,ENV=TEST,DATE=20230401

This example defines an in-stream procedure with symbolic parameters and then executes it with overridden values.

Complex Symbolic Parameter Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
//DBPROC   PROC DBG=N,
//             REGION=4M,
//             DBNAME='TESTDB',
//             OPTS=('OPTIMIZE','NOAUDIT','LOG')
//DBSTEP   EXEC PGM=DBPROG,
//             REGION=®ION,
//             PARM=('&DBNAME',&OPTS)
//INPUT    DD   DSN=&DBNAME..DATA,DISP=SHR
//DEBUG    DD   DUMMY
//         IF &DBG=Y THEN
//DEBUG    DD   SYSOUT=*
//         ENDIF
//         PEND

This example uses symbolic parameters for region size, program options, and conditional processing.

Types of Symbolic Parameters

Common Use Cases

Reusable Procedures

• Creating generalized procedures that work across different environments (dev/test/prod)
• Standardizing job steps while allowing for customization
• Maintaining a single procedure codebase for multiple applications

Date and Time Processing

• Using date-related symbolic parameters for dataset generations
• Creating date-stamped output files
• Controlling processing based on day of week or month

Conditional Processing

• Using symbolic parameters with IF/THEN/ELSE constructs
• Enabling debugging output based on parameter values
• Selecting different processing paths based on input parameters

System Symbols

z/OS provides several system symbols that can be used like symbolic parameters:

Using System Symbols

1
2
3
//REPJOB   JOB (ACCT#),'&SYSUID',CLASS=A
//STEP1    EXEC PGM=REPORTER
//OUTDD    DD   DSN=&SYSUID..REPORT.D&SYSDATE,DISP=(NEW,CATLG)

This example uses system symbols to include the submitter's user ID and current date in the job and dataset names.

Advanced Techniques

Nested Symbolic Parameters

1
2
3
4
5
//PROC1    PROC TYPE=TEST,
//             TEST='TEST.DATA',
//             PROD='PROD.DATA'
//STEP1    EXEC PGM=PROCESS
//INPUT    DD   DSN=&&TYPE..DATA,DISP=SHR

This example uses a symbolic parameter to determine which of two other symbolic parameters to use.

SET Statements for Dynamic Parameters

1
2
3
4
5
6
7
8
//SETJOB   JOB (ACCT#),'JOHN DOE',CLASS=A
//         SET DAY=MONDAY
//         SET ENV=TEST
//         IF &DAY=MONDAY THEN
//           SET ENV=PROD
//         ENDIF
//STEP1    EXEC PGM=PROCESS
//INDD     DD   DSN=&ENV..DATA,DISP=SHR

This example uses SET statements and conditional logic to dynamically set parameter values.

Substring Notation

1
2
3
4
5
6
//DATEJOB  JOB (ACCT#),'JOHN DOE',CLASS=A
//         SET FULLDATE=20230401  /* YYYYMMDD */
//STEP1    EXEC PGM=PROCESS
//YEARDD   DD   DSN=REPORT.&FULLDATE(1:4),DISP=SHR
//MONTHDD  DD   DSN=REPORT.&FULLDATE(5:2),DISP=SHR
//DAYDD    DD   DSN=REPORT.&FULLDATE(7:2),DISP=SHR

This example uses substring notation to extract parts of a date value.

Best Practices

1. Always provide default values for parameters to ensure procedures can run without explicit overrides
2. Use descriptive parameter names that clearly indicate their purpose
3. Document parameters with comments to explain their purpose, valid values, and usage
4. Group related parameters together in the PROC statement for readability
5. Be cautious with concatenation - use periods correctly to separate parameters from text
6. Avoid hardcoding values that might change between environments or over time
7. Use system symbols for date, time, and system-specific values where appropriate
8. Test procedures thoroughly with different parameter combinations

Troubleshooting

Common Issues

Debugging Techniques

• Add //JCLDUMP DD SYSOUT=* to see the JCL after symbolic parameter substitution
• Use %SET MSGLEVEL=(1,1) to see detailed JCL listing including substitution
• Add SYMLIST to the JOB statement to display resolved symbols in the job log
• Test with different parameter values to isolate issues

JES2 vs. JES3 Considerations

Symbolic parameter processing is mostly consistent between JES2 and JES3 environments:

• Basic symbolic parameter substitution works the same in both environments
• JES3 supports some additional symbolic parameters specific to its processing
• System symbol availability may vary between JES2 and JES3 installations
• Consult your system documentation for environment-specific details

Related Concepts

• PROC Statement - Defines procedures and their symbolic parameters
• SET Statement - Creates and modifies symbolic parameters
• IF Statement - Conditional processing based on symbolic parameter values
• EXPORT Statement - Makes symbolic parameters available to called procedures
• SYMLIST Parameter - Controls display of symbolic parameter substitution