SYSTEM Parameter

Purpose

The SYSTEM parameter specifies which system or system group in a JES2 or JES3 multi-system environment should execute a job or job step. This parameter provides control over workload distribution across multiple systems in a sysplex, allowing jobs to run on specific systems based on resource requirements, system capabilities, or operational considerations.

Syntax

JOB Statement Format

jcl

1
//jobname JOB parameters,SYSTEM=name

EXEC Statement Format

jcl

1
//stepname EXEC PGM=program,SYSTEM=name

Parameter Values

name

1-8 character name of a system or system group defined to JES
Can be a specific system name (e.g., SYS1, PROD1)
Can be a system group name that includes multiple systems
Can include a reference to a symbolic parameter (e.g., &SYSNAME)
The system name must be defined to JES as a valid execution system

Note:

If you omit the SYSTEM parameter, JES will select an available system based on workload balancing, resource availability, and installation-defined selection criteria.

Usage Examples

Basic JOB Level Specification

jcl

1
2
//TESTJOB JOB (ACCT),'JOHN DOE',CLASS=A,
//         MSGCLASS=X,SYSTEM=SYS1

This job will run only on the system named SYS1.

Step Level Specification

jcl

1
2
3
//TESTJOB JOB (ACCT),'JOHN DOE',CLASS=A
//STEP1   EXEC PGM=PAYROLL,SYSTEM=PROD1
//STEP2   EXEC PGM=REPORT,SYSTEM=REPORT1

STEP1 will run on system PROD1, while STEP2 will run on system REPORT1.

Using System Groups

jcl

1
2
//TESTJOB JOB (ACCT),'JOHN DOE',CLASS=A,
//         MSGCLASS=X,SYSTEM=PRODGRP

This job can run on any system in the PRODGRP group, as defined to JES.

Using Symbolic Parameters

jcl

1
2
3
//TESTJOB JOB (ACCT),'JOHN DOE',CLASS=A
//         SET SYSID=SYS3
//STEP1   EXEC PGM=PAYROLL,SYSTEM=&SYSID

This job will run on the system specified by the symbolic parameter SYSID, which is set to SYS3.

Sysplex Concepts

JES2 Multi-Access Spool (MAS)

In a JES2 environment:

Multi-Access Spool (MAS): Multiple JES2 systems share spool and checkpoint datasets
System affinity: Jobs can be directed to specific systems using SYSTEM or SYSAFF parameters
System selection: Without specific direction, JES2 selects systems based on workload balancing
Independent conversion: Job JCL can be converted on any system in the MAS

JES3 Complex

In a JES3 environment:

Global processor: Central controlling system for job scheduling
Local processors: Systems where jobs can execute
System selection: JES3 manages workload balancing across systems
Device eligibility: JES3 considers device requirements when selecting systems

Evolution Note:

IBM has announced the end of service for JES3, with JES2 being the strategic job entry subsystem going forward. Many installations have migrated or are migrating from JES3 to JES2.

Parameter Interactions

Relationship with SYSAFF Parameter

In JES2 environments, both SYSTEM and SYSAFF parameters can be used to specify system affinity:

SYSTEM: Available on both JOB and EXEC statements
SYSAFF: Available only on the JOB statement in JES2
If both are specified on the JOB statement, SYSAFF takes precedence

Interaction with CLASS Parameter

The CLASS parameter can indirectly determine system selection:

Specific job classes may be set up to run on specific systems
JES initialization parameters map job classes to systems
SYSTEM parameter overrides class-based routing

JCL Errors and System Selection

The handling of invalid SYSTEM values depends on the environment:

Scenario	Result
Invalid system name on JOB statement	Job is typically held or rejected with an error message
Invalid system name on EXEC statement	Step may be bypassed or job may be held, depending on installation options
Specified system is inactive	Job may wait in queue until the system becomes available

Practical Applications

When to Use the SYSTEM Parameter

System-Specific Resources: When a job requires hardware, software, or datasets only available on specific systems
Workload Balancing: To distribute computationally intensive jobs across systems
System Maintenance: To direct work away from systems scheduled for maintenance
Testing and Production Separation: To ensure test jobs run on test systems and production jobs on production systems
Capacity Planning: To align workloads with system capacity

Multi-Step Job Considerations

When designing multi-step jobs that use the SYSTEM parameter:

Consider data dependencies between steps running on different systems
Be aware of potential delays when jobs transfer between systems
Account for different system environments that might affect job behavior
Understand the implications for dataset access across systems

Implementation Details

JES2 Implementation

In JES2, system affinity is controlled through several mechanisms:

DESTID statements: Define system names and aliases in JES2 initialization parameters
SYSAFF parameter: An alternative to SYSTEM for specifying system affinity
/*JOBPARM statement: Can also specify system affinity using the SYSAFF parameter
JES2 commands: Operators can modify a job's system affinity using the $T command

JES3 Implementation

In JES3, system selection involves these considerations:

MAINPROC statements: Define systems in the JES3 complex during initialization
//*MAIN statement: Can also specify system requirements using the SYSTEM parameter
CLASS statements: Define which systems can process specific job classes
Device availability: JES3 considers device requirements when selecting execution systems

System Group Configuration

Defining System Groups

System groups allow jobs to run on any system within a defined group:

JES2 System Group Definition

jcl

1
2
3
/* JES2 Initialization Parameters */
NODEDEF NAME=NODE1
DESTID(PRODGRP) DEST=N1-R(PR1,PR2,PR3)

This defines a system group named PRODGRP that includes systems PR1, PR2, and PR3.

JES3 System Group Definition

jcl

1
2
/* JES3 Initialization Statements */
GROUP,NAME=PRODGRP,EXRESC=(PR1,PR2,PR3)

This defines a system group named PRODGRP in JES3 that includes systems PR1, PR2, and PR3.

Troubleshooting

Common Issues

Issue	Possible Solution
Job remains in queue with "AWAITING EXECUTION" status	Check if the specified system is active or if there are resource constraints
JCL error message indicating invalid system name	Verify that the system name is correctly spelled and defined to JES
Job runs on an unexpected system	Check for conflicting specifications in JOB statement, EXEC statement, and JES control statements
Steps run on different systems than expected	Review the SYSTEM parameter on each EXEC statement and job-level specifications

Common Error Messages

$HASP104 SYSTEM NOT DEFINED (JES2) - The specified system name is not defined to JES
IAT4201 SYSTEM NOT DEFINED TO JES3 (JES3) - The specified system name is not defined in the JES3 complex

Best Practices

Use system groups rather than individual system names when possible to provide flexibility
Document system requirements for jobs that need specific systems
Use symbolic parameters for system names to make JCL more portable
Consider workload balancing implications when directing jobs to specific systems
Coordinate with system programming to ensure system names are correctly defined
Be aware of resource availability on target systems to avoid long queue times
Use step-level SYSTEM parameters when different steps have different system requirements

Monitoring System Assignments

Commands for Checking System Assignment

Operators can use these commands to check which system a job is assigned to:

JES2 Commands

text

1
$D J(jobname)

This command displays information about the job, including its system affinity.

JES3 Commands

text

1
*I J=jobname

This command shows information about the job, including its assigned system.

Related Concepts

JOB Statement - Where the SYSTEM parameter can be specified at the job level
EXEC Statement - Where the SYSTEM parameter can be specified at the step level
SYSAFF Parameter - Alternative JES2 parameter for specifying system affinity
CLASS Parameter - Can indirectly affect system selection