Introduction

IBM provides the ability to cluster z/OS systems together using the IBM Sysplex technology, which is a combination of IBM hardware and software components. The individual z/OS systems are referred to as Sysplex members.

The IBM JES subsystem supports a Multi-Access Spool (MAS) configuration that allows for batch jobs to be distributed among participating JES subsystems. A JES MAS configuration may be used independently of a Sysplex environment or in combination with a Sysplex environment. When used in combination with a Sysplex environment, IBM recommends the JES MAS configuration match the Sysplex configuration.

The Universal Agent for z/OS Sysplex feature provides for the management of workload across all Sysplex members. This page describes the general architecture and design of the Universal Agent for z/OS Sysplex feature.

Sysplex Solution

From a workload management perspective, a z/OS Sysplex can be represented as a single z/OS image. A single-system view of the Sysplex is represented by a single Agent called the Primary agent which runs on any Sysplex member. Other agents, called Secondary agents, run on the other Sysplex members.

Neither the Universal Controller nor the Universal Agent for z/OS participate in the distribution of workload across the sysplex images. The controller simply executes z/OS tasks on the Primary z/OS agent that represents the Sysplex.

A batch job submitted to JES on one z/OS system may be routed by JES or by IBM Workload Manager (WLM) to any one of the Sysplex z/OS members. The routing or distribution of batch workload is based on JCL specifications, system configuration and the state of the Sysplex members.

Universal Controller starts a z/OS task by sending a task start request to the Primary Universal Agent for z/OS. The Agent submits the requested job to JES. The job can potentially execute on any one of the Sysplex members. The Agents installed in the z/OS Sysplex cooperate with each other to manage the execution of the job.

Each Agent in the Sysplex can provide complete job management capabilities regardless of which Agent in the Sysplex submitted the job to JES.

Job management capabilities include:

• Automatic data set cleanup prior to job execution.
• Tracking the execution of the job and job steps.
• Collecting and retrieving the job's JES sysout data sets.

The z/OS Agents use the IBM Cross-System Coupling Facility (XCF) for Agent-to-Agent communication within the Sysplex. The Agents utilize the XCF data sharing capabilities for message passing and sharing of common data structures.

UAG Sysplex

UAG for z/OS will create and join a Sysplex group if it is running Sysplex aware.

The XCF group name will consist of the characters UAG, followed by the first 4 (upper-case) characters of the system ID (system_id from UBRCFG00).

Each UAG will have a member name, which will be the group name appended with @ and followed by the MVS system name.

For example, UAG with a system ID of mndv, running on DVZOS202, would have a group name of UAGMNDV and a member name of UAGMNDV@DVZOS202.

UAG Sysplex System View

The Sysplex System View below illustrates the UAG deployment in a sample Sysplex environment. The Sysplex environment consists of two z/OS images, SYS1 and SYS2, and the Sysplex shared resources, JES, DASD, and XCF.

The following diagram illustrates a job submitted to one of two of the Sysplex members and the SMF exits that are called. The SMF exits reference the JME in ECSA and send events to the local UAGSRV via the event queue in z/OS High Common Storage.

1. A Launch message is received by the Primary UAG.
2. The Primary UAG writes a record to the Job Submission Checkpoint dataset, processes the JCL and submits it to the z/OS Internal Reader.
3. The JCL passes through JCL conversion and interpretation. The UAGUJV exit is invoked and sends an Event message to UAG to prompt it to look for JCL errors that might have prevented the job from entering the execution phase. (JCL conversion and interpretation can happen on different processors in the system depending on the system configuration.)
4. If a JCL error preventing the job from running is detected, a status message is sent to the Universal Controller and processing ends.
5. Once the job starts execution (on whatever system), program UAGRERUN gets control as the first step in the job. UAGRERUN performs pre-processing necessary to run and track the job on the local z/OS system. It creates the JME in ECSA to allow the SMF exits to track the job through Step Initiation, Step End and Job End processing.
6. As the job passes through Step End and Job End, Events are created on the Event Queue tracking the job's progress.
7. Events are removed from the Event Queue by the UAGSRV instance running on the system and processed.
8. In the case of a Primary UAG, Status messages are sent to the Universal Controller. In the case of a Secondary UAG, messages are queued to the XCF Message Queue. These messages are removed from the queue by the Primary UAG and Status messages are sent to the Universal Controller.
9. In both cases, any requested output is written to the UNVSPOOL directory for retrieval by the Universal Controller.
10. Any information required for eventual rerun processing is also sent to the Universal Controller.
     

Each of the components is described in the following table:
 

CF List Type Structure

UAG uses a CF List type structure with the following values:
 

IBM provides a CFSIZER web tool (Structure type OEM List ) which can be used to calculate the structure size. Given the input above, this tool returned the INITSIZE and SIZE values of 17M (at Coupling Facility Control Code Level 25). Please note that the sizes calculated by CFSIZER can vary (sometimes greatly) depending on the current CF level.

The structure name can be chosen by users and must be coded on the CF_STRUCT_NAME configuration option.

UAG uses this structure to communicate job tracking information from the Secondary agents to the Primary agent. List entries indicate events such as job start, step end and job end. List entries remain on the list until the primary agent has resources to process them. When the list structure is full, the secondary agents will wait until sufficient space is available before writing more tracking information. The required size of the structure is therefore dependent on the number of jobs being tracked, the number of job steps in those jobs and the resources available to the Primary agent to process the data.

File Monitor Support for Secondary Agents

File Monitors now function across a Sysplex. A File Monitor can be set, and the dataset Create, Change, or Delete will be detected on any system in the Sysplex where a UAG with the same system ID is running.

File Monitors will be detected while UAG is down as long as UAG was up when the File Monitor was set.

Exists and Missing File Monitors are resolved on the system where the Primary UAG is running. If a dataset is available only on a Secondary system, it will not be considered.

Configuration Parameters Used for Sysplex Configuration

Parameters in UBRCFG00

Parameters in UAGCFG00

z/OS Console Commands

This command causes an agent that is running in Sysplex Secondary mode to become a Primary agent until it is restarted or otherwise caused to become a Secondary agent.

If the agent is not running in Secondary mode, or a Primary agent is already active with the same system ID, the command will fail.

This command causes an agent that is running in Sysplex Primary mode to become a Secondary agent until it is restarted or otherwise caused to become a Primary agent.

If the agent is not running in Primary mode, the command will fail.