SYMLIST

Purpose

The SYMLIST parameter specifies which JCL variables (system symbols) should be exported to subsequent jobs or displayed. It is used with the EXPORT statement to control which variables are made available across job boundaries, and with the SYMLIST command to generate debugging output of current variable values.

Context and Usage

SYMLIST is used in two distinct contexts in JCL:

1. With EXPORT statement: To specify which variables to make available to subsequent jobs
2. As a command: To display current values of JCL variables for debugging purposes

SYMLIST with EXPORT

Basic Syntax

1
2
3
//         EXPORT SYMLIST=(var1,var2,var3,...)
//         EXPORT SYMLIST=*
//         EXPORT SYMLIST=NONE

Options Explained

Examples

1
2
3
4
5
6
//JOB1     JOB (ACCT#),'ADMIN',CLASS=A
//         EXPORT SYMLIST=(TODAY,ENV,STATUS)
//         SET TODAY=&SYSDATE
//         SET ENV='PROD'
//         SET STATUS='NORMAL'
//         SET INTERNAL='PRIVATE'  /* Not exported */

This example exports only three variables (TODAY, ENV, and STATUS) to subsequent jobs. The INTERNAL variable will not be available to other jobs.

1
2
3
4
//JOB2     JOB (ACCT#),'ADMIN',CLASS=A
//         EXPORT SYMLIST=*
//         SET VAR1='VALUE1'
//         SET VAR2='VALUE2'

This example exports all variables defined in the job, including system-defined variables and any variables set within the job.

SYMLIST as a Command

Basic Syntax

1
2
3
//STEP1    EXEC PGM=IEFBR14
//SYMLIST  DD SYSOUT=*
//         SET VAR1='TEST'

The SYMLIST DD statement causes the system to display the values of all defined JCL variables at that point in the job.

Filtering Variables with SYMLIST

1
2
//SYMLIST  DD SYSOUT=*,
//            SYMLIST=(VAR1,VAR2,SYSDATE)

This form displays only the specified variables rather than all defined variables.

Example Output

1
2
3
4
5
VARIABLE   VALUE
--------   -----
VAR1       'TEST'
SYSDATE    '20230315'
SYSUID     'USER123'

This shows the typical format of SYMLIST output in the job log, displaying variable names and their current values.

Usage Scenarios

Selective Variable Export

1
2
3
4
5
6
7
8
//JOB1     JOB (ACCT#),'ADMIN',CLASS=A
//         SET CONFIG='PROD'
//         SET USERID='ADMIN01'
//         SET PASSWORD='SECRET'  /* Sensitive */
//         SET DATAFILE='MASTER.DATA'
//*
//         EXPORT SYMLIST=(CONFIG,USERID,DATAFILE)
//* Note: PASSWORD is deliberately not exported for security

This example shows selective export of variables, excluding sensitive information like passwords from being available to subsequent jobs.

Variable Debugging

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
//DEBUG    JOB (ACCT#),'ADMIN',CLASS=A
//         SET VAR1='ABC'
//         SET VAR2=123
//*
//DISPLAY1 EXEC PGM=IEFBR14
//SYMLIST  DD SYSOUT=*  /* Display all variables */
//*
//STEP1    EXEC PGM=PROCESS
//INPUT    DD DSN=&VAR1..DATA,DISP=SHR
//*
//         SET VAR1='XYZ'
//         SET VAR3='NEW'
//*
//DISPLAY2 EXEC PGM=IEFBR14
//SYMLIST  DD SYSOUT=*,
//            SYMLIST=(VAR1,VAR3)  /* Display specific variables */

This example demonstrates using SYMLIST at different points in a job to track variable values during execution, first displaying all variables and later checking only specific ones that have changed.

Multi-Job Variable Flow

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
//JOB1     JOB (ACCT#),'ADMIN',CLASS=A
//         SET TODAY=&SYSDATE
//         SET MODE='BATCH'
//         SET COUNT=0
//*
//SYMLIST  DD SYSOUT=*  /* Display before export */
//*
//         EXPORT SYMLIST=(TODAY,MODE)  /* Only export some */
//*
//STEP1    EXEC PGM=PROGRAM1
//         SET COUNT=100  /* Modified after EXPORT */
//*
//JOB2     JOB (ACCT#),'ADMIN',CLASS=A
//SYMLIST  DD SYSOUT=*  /* Check what was imported */
//*
//STEP1    EXEC PGM=PROGRAM2
//DD1      DD DSN=FILE.&TODAY..&MODE,DISP=SHR

This example shows how SYMLIST can be used to verify which variables are available to a job that follows one using the EXPORT statement. Note that COUNT would not be available to JOB2 because it wasn't in the EXPORT SYMLIST.

Best Practices

1. Explicitly list variables to export rather than using SYMLIST=* to prevent accidentally exposing sensitive information
2. Document exported variables with comments to indicate their purpose and expected usage in subsequent jobs
3. Use SYMLIST command strategically at key points in jobs to verify variable values during debugging
4. Keep exported variable lists manageable by only exporting what's needed by subsequent jobs
5. Consider prefixing related variables to make SYMLIST specifications more organized and easier to maintain
6. Be aware of security implications when exporting variables that might contain sensitive information
7. Verify variable values in receiving jobs using SYMLIST before using them in critical operations

Troubleshooting

Debugging Tips

• Use SYMLIST DD statements before and after key operations to track variable changes
• Add a SYMLIST statement immediately after EXPORT to verify which variables will be exported
• Place a SYMLIST statement at the beginning of jobs that receive exported variables
• Use MSGLEVEL=(1,1) to see expanded JCL with all variable substitutions
• Use strategic variable naming to make SYMLIST output more readable

JES2 vs JES3 Considerations

• SYMLIST functionality is similar in both JES2 and JES3 environments
• JES3 may provide additional diagnostics through SYMLIST output
• The display format of SYMLIST output may differ slightly between JES versions
• Some installation-specific limitations may apply to SYMLIST in either environment

Related Concepts

• EXPORT Statement - Uses SYMLIST to specify which variables to export
• JCL Variables - System symbols that can be displayed or exported with SYMLIST
• SET Statement - Defines variables that can be displayed or exported with SYMLIST
• JCL Debugging - Using SYMLIST for troubleshooting variable issues
• Execution Groups - Context for sharing variables between jobs