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:

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:
  • General Page
  • Version Management Page
  • Documentation Page
• Additional pages that are always available for executable objects:
  • Process Pages
  • Attributes Page
  • Registering External Output Files
  • Variables Page
  • Prompt Sets Page
  • Rollback Page
• The OS/390 page described here.

To define an OS/390 job, do the following:

1. Add an object of type Job > OS/390. The new object opens to the OS/390 page.

2. 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.

3. In the Job Report section configure the following:

   report of OS390 jobs,OS390 jobs

   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

   report of OS390 jobs,OS390 jobs

   • 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

4. 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.

5. 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.

6. Save the object.

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.