UJOBCORR Parameter

Purpose

The UJOBCORR parameter provides a user-defined job correlator that allows for consistent tracking, management, and identification of jobs across systems. It enables users to assign a custom correlation value to a job, making it easier to track related jobs, associate them with external processes, or integrate with enterprise workload automation and scheduling tools.

Note:

The UJOBCORR parameter was introduced in z/OS 2.1 with JES2, providing enhanced job tracking capabilities that complement the system-generated job correlator.

Syntax

JOB Statement Format

jcl

1
//jobname JOB parameters,UJOBCORR='user-defined-correlator'

Parameter Value

user-defined-correlator

A 1-64 character string enclosed in single quotes
Can contain alphanumeric characters (A-Z, 0-9) and special characters
May contain single quotes, but they must be doubled ('') to be treated as part of the value
Case-sensitive - the value is stored and displayed exactly as specified
Trailing blanks are removed from the value

Usage Examples

Basic Usage

jcl

1
2
//PAYROLL JOB (ACCT#),'JOHN DOE',CLASS=A,
//         UJOBCORR='PAY-CYCLE-2023-Q1'

This job will have the user correlator "PAY-CYCLE-2023-Q1" associated with it.

With Special Characters

jcl

1
2
//REPORT JOB (ACCT#),'JANE SMITH',CLASS=A,
//         UJOBCORR='PROJ#123-PHASE2:MONTHLY-RUN'

This job uses special characters in the correlator to provide more detailed tracking information.

With Single Quotes

jcl

1
2
//BACKUP JOB (ACCT#),'ADMIN',CLASS=A,
//         UJOBCORR='SYSTEM''S_BACKUP-2023-04-01'

This job includes a single quote (apostrophe) in the correlator value, which is doubled to escape it.

With Date and Time Variables

jcl

1
2
//EXTRACT JOB (ACCT#),'ADMIN',CLASS=A,
//         UJOBCORR='EXTRACT-&SYSDATE-&SYSTIME'

This job uses JCL symbolic parameters to include date and time values in the correlator (requires appropriate SET statements or system symbols).

Job Correlator Concepts

System-Generated vs. User-Defined Correlators

z/OS job management involves two types of job correlators:

Correlator Type	Description	Format/Example
System-Generated	Automatically created by the system for every job, ensuring a unique identifier within the JES2 environment	`J0000023SYS1....D0000103`
User-Defined (UJOBCORR)	Specified by the user to provide meaningful context or integration with external systems	`PAY-CYCLE-2023-Q1`

Correlator Usage

Job correlators are made available through various interfaces:

JES2 operator commands and displays
SDSF panels and API
JES2 exit points
SMF records for accounting and reporting
ENF signals for integration with other subsystems
z/OSMF API for REST-based access

Common Use Cases

Enterprise Workload Automation

Linking batch jobs with their originating automation tool requests
Tracking multi-system job streams with end-to-end correlators
Associating jobs with business processes or applications

Audit and Compliance

Tracking job execution for regulatory compliance
Associating jobs with change requests or release processes
Creating audit trails for sensitive operations

Problem Determination

Quickly identifying related jobs during troubleshooting
Tracing data flows across multiple batch processes
Correlating error conditions across systems

Implementation Details

Accessing Job Correlator Information

Through SDSF

text

1
2
3
SDSF STATUS
SORT JCORR
FIND 'PAY-CYCLE'  /* Find jobs with specific correlator text */

SDSF provides the JCORR column to display job correlators in job status displays.

Through JES2 Commands

text

1
2
3
$D JOB(*),LONG  /* Display jobs with correlator information */
$D JOB(CORR=J0000023SYS1....D0000103)  /* Find by system correlator */
$D JOB(UJOBCORR=PAY-CYCLE-2023-Q1)  /* Find by user correlator */

Through Programmatic Interfaces

Applications can access job correlator information through:

SAPI (SYSOUT Application Programming Interface)
Extended Status SSI (Subsystem Interface) function
JES Property SSI function
SMF records (Type 26, 30, etc.)

Best Practices

Use meaningful correlators that identify the business process, application, or workflow
Include version or date information to distinguish between similar job runs
Establish naming conventions for correlators across the organization
Consider using hierarchical structures like "APPLICATION:PROCESS:STEP"
Avoid extremely long correlators that might be difficult to display or use in commands
Document correlator patterns to ensure consistent usage across teams
Leverage symbolic parameters to include dynamic information when appropriate

Troubleshooting

Common Issues

Issue	Possible Causes & Solutions
UJOBCORR parameter ignored	Ensure z/OS version supports UJOBCORR (z/OS 2.1 or later) Check JES2 maintenance levels Verify syntax and quoting
JCL error with UJOBCORR	Ensure quotes are properly paired and escaped Check for invalid characters in the correlator value Verify the correlator does not exceed 64 characters
Correlator not visible in displays	Customize SDSF to show the JCORR column Use LONG option on JES2 display commands Check if security policies restrict viewing correlator information

Diagnostic Commands

JES2 commands to verify correlator settings:

text

1
2
3
$DISPLY JOBDEF  /* Display JES2 job definition parameters */
$DISPLY LIMITS  /* Display JES2 system limits */
$DISPLY EXIT(5)  /* Display status of JES2 Exit 5 (Job Statement Scan) */

JES2 vs. JES3 Considerations

The UJOBCORR parameter has specific considerations in different JES environments:

UJOBCORR is a JES2-specific parameter introduced in z/OS 2.1
JES3 environments do not support the UJOBCORR parameter
In JES3 to JES2 migration scenarios, JCL using UJOBCORR should be reviewed
z/OS 2.5 with JES2 provides enhanced correlator capabilities

Related Concepts

JOB Statement - The statement where UJOBCORR is specified
NOTIFY Parameter - Used for job completion notification
SDSF - System Display and Search Facility for viewing job information
JES2 Commands - Commands for displaying and managing jobs