//PAYROLL JOB (ACCT),'NIGHTLY',CLASS=A,MSGCLASS=X
/*JOBPARM SYSAFF=SYS2
//STEP1 EXEC PGM=PAYRUNThis JCL system affinity example makes SYS2 the eligible JES2 member for the job. Use /*JOBPARM SYSAFF=SYS2 when a batch step depends on a Db2 subsystem, locally installed product, private load library, device, or test configuration that is not available on every member of the JES2 multi-access spool complex.
JES2 SYSAFF syntax and placement
Code the JES2 /*JOBPARM control statement directly after the JOB statement in a normal input stream. It begins with /*, not //. The member identifiers are installation-defined names, so copy them from a working job or confirm them with operations before submission.
//DB2LOAD JOB (ACCT),'LOAD',CLASS=A,MSGCLASS=X
/*JOBPARM SYSAFF=SYS2
//LOAD EXEC PGM=DSNUTILB
//STEPLIB DD DSN=DB2.SYS2.SDSNLOAD,DISP=SHRThis request restricts both conversion and execution to SYS2. It does not make an inactive member active, bypass job-class rules, or prove that the named Db2 subsystem is available. The step still needs valid DD statements, libraries, security access, and an initiator or WLM-managed class that can select it.
Choose one member, several members, or any member
| JES2 value | Eligible execution members | Typical use |
|---|---|---|
SYSAFF=SYS2 | SYS2 only | A subsystem or product exists only on SYS2. |
SYSAFF=(SYS1,SYS2) | Either SYS1 or SYS2 | The required service exists on two members. |
SYSAFF=* | The member that reads the job | Keep processing on the input member. |
SYSAFF=ANY | Any eligible member | Remove a narrower affinity when site rules permit. |
A list is an eligibility set, not a sequence. SYSAFF=(SYS1,SYS2) does not tell JES2 to try SYS1 first. JES2 applies class, priority, member state, scheduling-environment, security-label, and other selection rules before a member starts the job.
Use SCHENV when the dependency is a resource
//CICSRPT JOB (ACCT),'REPORT',CLASS=A,MSGCLASS=X,
// SCHENV=CICSREGNSCHENV= names a WLM scheduling environment. That environment contains resource requirements and their required states. A job can execute on a system where those requirements are satisfied, so operations can change eligibility by changing resource states without editing the JCL.
Use SYSAFF for a static member restriction. Use SCHENV when the real requirement is an available resource, such as a subsystem or application region. They can be combined, but the intersection must contain at least one eligible active system or the job waits. IBM also distinguishes their timing: SYSAFF controls conversion and execution, while SCHENV controls execution after conversion.
JES3 SYSTEM syntax
In a JES3 environment, the equivalent JECL form is the //*MAIN SYSTEM= statement. Use it only when the target installation runs JES3 and its standards call for this form.
//RPTJOB JOB (ACCT),'REPORT',CLASS=A,MSGCLASS=X
//*MAIN SYSTEM=(MVSA,MVSC)
//STEP1 EXEC PGM=RPTPGMSYSTEM=ANY permits any qualifying global or local system, SYSTEM=JGLOBAL selects the global processor, and SYSTEM=JLOCAL selects a local processor. A list such as SYSTEM=(MVSA,MVSC) names eligible processors. The selected processor must support the job class and any specifically requested devices or JES3-controlled resources.
System affinity is not remote-node routing
JES2 SYSAFF selects a member of the local JES2 MAS. It does not route a job to an unrelated NJE node. Remote execution uses facilities such as XMIT or JES routing controls defined by the installation. The JCL JECL statements reference owns that broader statement and routing intent.
Diagnose a job waiting for the target system
A job restricted to SYS2 remains queued when no eligible SYS2 initiator or WLM-managed class can select it. For JES2, an operator or authorized user can display detailed status with:
$DJ'PAYROLL',LONGIf the display reports SYSAFF, check that the coded member name exists, the member is active, its independent-mode state matches the request, and the job class is selectable there. If it reports SCHENV, find the required environment in the long display and check its state by system:
D WLM,SCHENV=CICSREGNA scheduling-environment delay can mask another reason that the job is ineligible. After the environment becomes available, review the job again for class limits, held execution, security-label affinity, duplicate job name, or other member-status restrictions.
Common system-affinity mistakes
| Symptom | What to check |
|---|---|
| JCL or JES syntax error | Confirm /*JOBPARM starts in column 1, uses no //, and contains a valid site-defined member name. |
| Job waits with SYSAFF status | Check member activity, independent mode, class selection, and whether a scheduler replaced the affinity. |
| Job waits with SCHENV status | Use the WLM display to find which required resource state is unavailable on eligible systems. |
| Job runs on an unexpected member | Inspect the submitted JCL, scheduler variables, JOB statement, input-device defaults, and exit changes rather than only the source member. |
| Program fails after correct routing | Affinity only selects a system. Check STEPLIB, subsystem name, DD allocation, authorization, and product startup separately. |
| Remote node never receives the job | Use the site's NJE routing method; SYSAFF is not a substitute for XMIT or ROUTE XEQ. |
Production checklist
- Confirm whether the installation uses JES2, JES3, or scheduler-managed routing.
- Verify the exact JES member name; do not assume the z/OS system name is identical.
- Choose a named affinity only when the job has a real system-local dependency.
- Prefer SCHENV when a resource state, rather than a permanent member name, defines eligibility.
- Check that at least one eligible system can select the job class.
- Confirm required subsystems, load libraries, devices, and security access on every eligible member.
- Review the scheduler's generated JCL so that two restrictions do not produce an empty eligible set.
- Use the long JES2 job display when the job waits.
For the JOB, EXEC, and DD relationship, see the JCL tutorial with examples. The JCL JOB statement guide covers job-level fields, and the JCL parameter-field guide explains positional and keyword coding.
Official IBM references
- IBM: Selecting a processor in JES2
- IBM: Selecting a processor using a scheduling environment
- IBM: Displaying or updating a job's affinity
- IBM: SYSTEM parameter
- IBM: JES2 job status, SYSAFF, and SCHENV
JCL system affinity FAQ
What does SYSAFF=* mean in JES2?
SYSAFF=* gives the job affinity to the JES2 member that reads the job. It is useful when the work must remain on that input member, but a named member is clearer when a scheduler or submission path can vary.
Can SYSAFF name more than one system?
Yes. A list such as SYSAFF=(SYS1,SYS2) makes either member eligible. JES2 selects an eligible member according to the rest of its job-selection rules; the list does not specify a preference order.
Why is a job delayed for SYSAFF?
The named JES2 members may be inactive, unable to select the job, or incompatible with the job's independent-mode requirement. Display the job with the JES2 long form and confirm the member name, state, class, scheduling environment, and security-label restrictions.
What is the difference between SYSAFF and SCHENV?
SYSAFF is a static list of eligible JES members and affects conversion and execution. SCHENV names a WLM scheduling environment whose resource states determine where the job may execute; it does not select the conversion system.
Code the narrowest eligible set that still has a live path to execution, then verify the submitted job rather than assuming the scheduler preserved the source JCL unchanged.
