OS/390 JOBS

OS/390 Jobs contain the necessary parameters to execute processing steps on OS/390 target systems, to monitor those steps and to define how runtime options and reports must be processed. Your Automation Engine system is connected to the target system through the Agent; the Agent interprets the commands so that the target system understands them.

Prerequisites

The Agent is active
The Agent is assigned to the Job on the Attributes page
The Job has a Login (LOGIN) object assigned that contains the credentials to log in to the target system

For more information about the integration between the Automation Engine and OS/390 systems, see AE and z/OS.

This page includes the following:

Defining OS/390 Jobs

An OS/390 Job definition consists of the following pages:

Standard pages that are always available, no matter what type of object you are defining:
Additional pages that are always available for executable objects:
The OS/390 page described here.

To Define an OS/390 Job

Add an object of type Job > OS/390. The new object opens to the OS/390 page.
In the Parameters section you define the configuration of the Job depending on its type:
- Type: Automation Engine (AE)
  
  This type means that the Job logic is defined entirely in Automic Automation, that is, you write the Job JCL directly on the Job Process page.
  - Job Name
    
    Dataset that contains the JCL. The Job card is generated from the host attributes defined here. The Pre-Process JCL is added before the first step. The script must be empty.
    
    The Job card defined in this Job object will be then inserted, whether the JCL contains a Job card or not.
  - Programmer's Name
    
    Name of the programmer. It identifies the Job owner or its Job Group (optional). The name is recorded in the Job card.
    
    Maximum length: 20 characters
  - Job Class
    
    Class in which the Job should run
  - Account
    
    Account number or accounting information as required by the OS390 system
    
    Maximum length: 40 characters
  - Priority
    
    Priority with which the Job should be executed
    
    Allowed values: 1 to 15, where 1 is the highest and 15 the lowest priority
  - MSGCLASS
    
    Message class assigned to the Job.
  - MSGLEVEL
    
    Trace option for the Job log. Numerical value for command and message separated by a comma.
    
    Allowed formats: "Command,Message", ",Message" or "Command"
    
    Allowed values for outputting commands:
    - "0" - Outputs exclusively commands
    - "1" - All job commands, JES2 or JES3 control commands, procedure commands and all IEF653I messages
    - "2" - All job commands (JCL) and the JES2 or JES3 control commands
    Allowed values for outputting messages:
    - "0" - Only JCL messages. In the case of abortions also JES control commands and operator messages. For SMS errors also the corresponding messages.
    - "1" - All JCL, JES, operator and SMS messages.
  - Notify
    
    Notification to be sent by the OS/390 system when the Jon completes processing
    
    Maximum length: 17 characters.
  - Scheduling Environment
    
    Name of the Workload Manager (WLM) scheduling environment to associate with this Job. A scheduling environment is a list of resources and their required settings. By associating a scheduling environment name with a Job, you ensure that the Job will be scheduled for execution only on a system that satisfies those resource state requirements.
  - Job Parameters
    
    Placeholder for any supported additional job card parameter
  - Return Code
    
    This setting is relevant if the Job end should be monitored via SMF Records. The return codes of the Job STEPS are collected in this case.
    - Highest
      
      The highest return code is used when the Job ends
    - Latest
      
      Only the return code that has occurred last is considered
    The administrator can specify whether SMF Records should be used for monitoring Job ends using the SMFJob= in the INI file of the Event Monitor and the UC_EX_JOB_MD=UC4START variable in the INI file of the Agent.
- Type: OS/390 JCL
  
  Select this option if the Job JCL is taken from the OS/390 system and it is not defined in the Automation Engine. However, with this type the Job card is generated by the Automation Engine.
  
  When you select this option, an additional OS/390 File Name input field is displayed. Here you enter the name of the dataset or member which contains Job JCL.
  
  Example: SYSS.AWA.JCL.JOB1 or SYSS.AWA.JCLLIB(UC4JOB1)
  
  Jobs can also originate from the Librarian source administration system.
  
  Syntax: *LIBRARIAN(Dataset, Member).
  
  Maximum length: 225 characters
  
  Allowed format: Dataset name and member name must be in single quotation marks. Otherwise, the Agent puts the name of the user under which it runs in front.
  
  Example:
  
  In IBMUSER.SYSS.AWA.JCL.JOB1 , the Agent ignores the first file line if type "z/OS JCL" is selected because it expects the job card in it.
- Type: JCL incl. OS/390 job card
  
  Select this option if both the Job JCL and the JOb card are defined on the OS/390 system and not in the Automation Engine. No runtime options are available, as the definitions made in the Job card apply.
  
  You can write a pre-processing script on the Pre-Process page of the Job. When generating the Job, the JCL from the Pre-Process page is added before the first step of the Job.
  
  If you select this option, the OS/390 File Name and Return Code fields are displayed.
  
  In OS/390 File Name enter the name of the dataset that contains the job JCL and the job card.
In the Job Report section configure the following:

Where to Store the Report

You have two options. You can select one or both simultaneously:
- Store to: Database means that when the Job has been executed, the process log available on the target system (on the Agent) is stored in the database.
  
  When a Job has been executed on an Agent, the corresponding report is stored on the Agent computer. After the Automation Engine has written this data to the database, the report is automatically deleted from the Agent computer. If it cannot be deleted due to an error, the deletion process is not repeated and an error message is displayed.
- Store to: File means that the process log is stored as a file on the target system (Agent).
When to Generate the Report

You have two options:
- Generate: Always means that the process log of the operating system is always written.
- Generate: On error only means that the process log is kept when an error occurs. Example, when the Job is canceled or aborted.
OS/390-Specific Options
- Job Log Complexity
  
  You specify here the content of the log:
  - Agent default configuration
    The job log complexity depends on the configuration in the Agent INI file (completeJobout= parameter)
  - Store JES statistics and job output
    The JES statistics and job output are stored in the job log
  - Store only JES statistics
    JESMSGLG, JESJCL, and JESYSMSG are included
- Delete Job Log
  - Agent Default Configuration
    Whether the job log is deleted depends on the configuration in the Agent INI file (jobPurge= parameter)
  - Delete after reading
    The job log is deleted after it has been read by the agent
  - Do not purge
    The job log remains in the JES spool
- Print Release
  - Agent Default Configuration
    Whether the job log is deleted depends on the configuration that is made in the INI file of the agent (the relMsgClass= parameter)
  - Release after reading
    The job log is deleted after it has been read by the agent
  - Do not release
    The job log remains in the JES spool
- Obtain Message Classes
  
  Message classes which should be read and routed. Specify one or several message classes. Examples: "A", "ABC", "X1".
  
  Any order is possible. The following values are also allowed: *DEFAULT and *ALL.
  - DEFAULT
    The message classes which should be read depend on the configuration that is made in the INI file of the agent (the getMsgClass= parameter).
    
    If this setting is used, *DEFAULT must also be specified in the Route Message Classes to field.
  - ALL
    All classes are read.
- Route Message Classes to
  
  Message classes that should be routed.
  
  After it has been transferred to the Automation Engine, the job log can be routed to the specified message classes (example, for an Output Management System)
  
  Enter either one or the number of message classes that are specified in Obtain Message Classes. The order is relevant.
  
  Examples:
  - The following message classes are read "ABC" and routed "DEF". Class "A" is routed to class "D", "B" to "E" and "C" to "F".
  - The following message classes are read: "ABC" and routed: "D". Class "A", "B" and "C" are routed to class "D".
    
    The following values can be used instead of message classes:
    - DEFAULT
      The message classes which should be routed depend on the configuration that is made in the INI file of the agent (routeMsgClass= parameter)
      
      This setting must be specified if *DEFAULT has also been specified in the Obtain Message Classes field
    - NO
      No routing is made
Go to the Attributes page and configure the following:
- Select the OS/390 Agent.
- Select the Login object that contains the credentials that the Agent needs to access the z/OS system.
Go to the General > Runtime page.

In the Return Code Handling section select Completion Code to display OS/390-specific options. Here you can assign a return code and a status to each step in the Job.
1. Enter the Step Name and the Return Code and select the status.
2. Click Add to add the completion code and repeat with all the steps in the Job.
Save the object.

Executing, Accessing the Report and Monitoring

After you have configured the Job, you can execute it to check if it behaves as expected. Click the Execute button in the toolbar. As soon as the Job has executed, you find information about its execution in the following areas of the user interface:

Job Report

Automic Automation provides various types of reports with comprehensive information about the execution of objects. For OS/390 Jobs, the most relevant one is SREP. This report records every step that the Job has gone through.

To open the SREP report, do the following:

Click Open Report to open the report view.
In the dropdown list on the upper left corner of the report window, select SREP.

For more information, see Working with the Reports View.

Task List

Each row in the Tasks list in the Process Monitoring perspective corresponds to an execution of an object. Usually, only active tasks are displayed in this list, unless you have configured it otherwise.

For more information, see The Task List.

Execution List

Every execution of the Job is recorded and stored. You can access the Job execution list to check what happened in each execution.

For more information, see Execution Data.

Job Monitor

As soon as the Job has started, its monitor is visible in the Process Monitoring perspective. It provides the configuration details with which the Job has been executed. It also shows the JCL.

For more information, see Monitoring Jobs.

Job and Task Details

You can also access both the configuration details about the Job object and of its executions (tasks) by means of the Details button.

For more information, see Viewing Object and Task Details.

Workload Management (WLM) Integration

The OS/390 Agent can perform built-in checks before submitting Jobs to the JES. If so defined, these checks are always performed, also in cases where the Job would not run on the OS/390. If a Job is blocked due to one of these checks, its status is 1683 Waiting for remote resource. A message is displayed in the Remote Status column in the Tasks list (Process Monitoring perspective) that explains the reason. The blocking reason is also logged in the Job report (SREP).

The following checks are available; your system administrator them in the Agent INI file:

Duplicate Job check

Before submitting a Job to the JES, the Agent checks whether a Job with the same name is already running. If it finds one, the Job is not submitted.

This duplicate is useful if you want to start multiple OS/390 Jobs that have the same OS/390 name but different names in the Automation Engine. Although these Jobs can be started in the Automation Engine, they would cause a queue in OS/390. This check avoids such situations.

This check considers all the Jobs in one Agent.
Scheduling environment check

This check prevents a Job from being submitted to JES if the scheduling environment is not available in any of the systems to which it may be submitted.
Initiator check

This check prevents the OS/390 Agent from starting additional Jobs if all OS/390 initiators are busy. The WLM in OS/390 can adjust the number of available initiators. The Agent must check their number to determine the maximum number of Jobs that can be started at a certain point in time.

Advantages of these checks:

Jobs that cannot run do not use up the JES Queue
Blocked Jobs are marked as such in the Tasks list, which also provides information about the blocking reason
Jobs with status 1683: Waiting for remote resource do not occupy abstract resources (WORKLOAD_MAX_JOB) within the Automation Engine
The runtime computation for temporarily blocked Jobs is more accurate because the waiting time does not count as runtime

Important! These checks do not guarantee that every Job that is submitted to JES runs immediately. These are the reasons:

The nature of the checks
- If the initiator check is only done at SYSPLEX level, Jobs may be submitted even if no single system has free resources
- The duplicate Job check does not take Jobs into account that were submitted by other Agents, Processes or Users
Timing issues

A resource might become unavailable in the short time span between resource check and the submission of the Job.
Job routing

The resource checks do not take into account whether Jobs are routed to certain systems (due to SYSTEM/SYSAFF parameters) after submission.

Example: The Agent finds that the required scheduling environment is available on system A. The Agent submits the Job. However, due to the SYSAFF parameter, the Job is routed to system B, where the scheduling environment is not available.

The default Job class is inquired by the Agent only once at start-up, either from JES or from the "defaultJobclass" parameter in the INI file. If the default Job class changes while the Agent is running, the scheduling environment and initiator checks do not work correctly for Jobs without specified job class. In this case, the Agent has to be restarted for the checks to work properly again.