IBM z/OS Connector 2.0.0.0

Introduction

Prerequisites

• Version 9.2.9 or later
• Connection component 1.0.0.2 or later. Note that the Connections component will be installed or updated automatically if necessary when you install this extension.
• Privileges Required to Use the z/OS connector

Installation

The component is available in the Catalog.

Contents of the car file

The car file consists of the following objects:

Setup

z/OS processes need their own Connection, Process Server, and Queue. These objects should not be in Partition GLOBAL. By default, all the z/OS objects live in the Partition REDWOOD. This connector uses the z/OS Management Facility REST API (z/OSMF) to communicate with the z/OS mainframe server (Using the z/OSMF REST services - IBM Documentation). For this connector to work, the z/OSMF component must be installed on your mainframe and accessible via https from the Platform Agent where the RunMyJobs Process is running.

1. Navigate to Custom > Connections.

2. Click .

   

3. Choose IBM z/OS under Select a Connection Type.
4. Choose Next or Basic Properties, you create a Queue and Process Server for your IBM z/OS connection, all required settings will be set automatically.
5. Choose Next or Security and click to specify which roles can access the connection information.
6. Choose Next or IBM z/OS Properties, this is specific for the z/OS component, you specify URL, Username, and Password for your connection.
7. Navigate to Environment > Process Server, locate your z/OS Process Server and start it, ensure it reaches status Running.

Process Definitions

Redwood_ZOS_ShowJobs: Retrieve info about z/OS Jobs

To retrieve the list of z/OS jobs from the server, navigate to the Redwood_ZOS application and submit the ZOS_ShowJobs definition.

On the Parameters tab of the Submit Wizard, some filters are available to narrow the list of results:

Select a Queue that contains at least one z/OS Process Server, then choose Submit.

When the process completes, there are two ways to view the output:

1. The list of jobs matching the specified filters is printed to the job's stdout.log file
2. An output parameter of type Table called jobsTable is attached to the job, along with a job file called jobsTable.rtx. This is a table containing details about the z/OS jobs that were returned. This table can be referenced in downstream jobs to check job statuses, etc. The table columns are:
   • JobId: The ID of the job on the z/OS system
   • JobName: The name of the job on the z/OS system
   • Status: The z/OS job status
   • RetCode: The return code of the z/OS job

Redwood_ZOS_RunJob : Submit and monitor a z/OS job

The Redwood_ZOS_RunJob parameter allows you to submit a z/OS job from JCL and monitor it until completion.

Monitoring

After the job is submitted, the corresponding RunMyJobs Process will continue to run until the remote z/OS job is complete. The Remote fields in the Process Monitor view are updated as the job is running to reflect the Remote ID, Remote System, and Remote Status of the z/OS job.

To configure the polling interval, set the following registry key (on the Configuration > Registry menu):

Full Path: /configuration/jcs/apps/ibm/zos/PollInterval Value: The value of the polling interval (in seconds), e.g. 30

Status Mapping

When the z/OS job completes, the RunMyJobs process will finish with a status that matches the z/OS return code.

• CC 0000 and 0004 are treated as success, and the RunMyJobs process will end in a Completed status, with a return code of 0 or 4.
• Any other status is treated as failure, and the RunMyJobs process will end in an Error status.

The numeric value of any CC codes (e.g. 0008, 00016) will also be set as the job return code.

Killing the z/OS Job

While the job is executing, if you kill the RunMyJobs process, a cancel command will be issued to z/OS to attempt to cancel the remote job.

Providing the JCL to Run

There are two different ways to provide the JCL code to run:

1. Provide the path to a DataSet or Unix File on the z/OS server that contains the JCL code to run.
2. Provide the path to the file or data set in the Path to Data Set or Unix File to Execute parameter. Leave the JCL to Execute parameter empty.
3. To submit a job from a DataSet, prefix the path with a double slash (//) and provide the data set name. This could be a sequential data set or a member of a partitioned data set.
4. Example (Fully Qualified Dataset): Prefix with //, then enclose the fully qualified dataset in single quotes. //'USER.TEST.JOBS(TESTJOB)'
   
5. Example(Non-Fully Qualified Dataset): Prefix with //, without quotes. //TEST.JOBS(TESTJOB)Note: The fully qualified path is required if restart handling is enabled, so the use of option 1 is preferred.
   
6. To submit a job from a Unix File, provide the absolute path the file.
   
   Example: /u/jdoe/testjob.jcl
7. Provide the JCL code directly in the JCL parameter.
8. Supply the JCL code directly in the JCL to Execute parameter. Leave the Path to Data Set or Unix File parameter empty.

//JDOECPY JOB (JDOE),'COPY JOB',CLASS=L,MSGCLASS=X
//COPY01   EXEC PGM=IEBGENER
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD DSN=OLDFILE,DISP=SHR
//SYSUT2   DD DSN=NEWFILE,
//            DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(40,5),RLSE),
//            DCB=(LRECL=115,BLKSIZE=1150)
//SYSIN  DD DUMMY

Sample JCL code

Other Input Parameters

• Internal Reader Record Format: The record format to use. Supported options are F (Fixed) or V (Variable). When submitting a job from a data set, this should be left blank, or else it must be set to match the format of the data set that is being submitted. For UNIX file or JCL submissions, the default value of F is used if the parameter is left blank.
• Internal Reader Record Length: The value to use for the internal reader logical record length. When submitting a job from a data set, this should be left blank, or else it must be set to match the record length of the data set that is being submitted. For UNIX file or JCL submissions, the default value of 80 is used if the parameter is left blank.
• JCL Symbols: A comma-separated list of key=value pairs to supply values for any symbolic parameters in the JCL. For example, if the symbols &File and &Number are used in the JCL, the value of this field could look like this: File=MYFILE,Number=25
• Retrieve Spool Lists: When set to Yes, all spool lists will be downloaded from the server and attached to the Process as Job Files.
• Enable Restart Options: When set to Yes, restart options will be enabled for this job. If the z/OS job completes in failure, the RunMyJobs process will go into a CONSOLE status, and an Operator Message is sent to allow the user to choose how to proceed. See Restart Handling section below for more details.

Output Parameters

• Job ID: The ID of the z/OS job (for example JOB00329)
• Job Name: The Name of the z/OS job
• Job Return Code: The actual return code of the z/OS job (e.g. CC 0000)

Restart Handling

If the Enable Restart Options parameter is set to Yes, the user will have the opportunity to choose how to proceed if the z/OS job fails. If the z/OS job fails, the RunMyJobs process will go into a CONSOLE status, and an Operator Message is sent. The user can reply to the Operator Message to choose how to proceed. The reply can be done either by finding the Operator Message in the Operator Messages view and selecting the Reply option from the context menu, or selecting the Reply option from the context menu of the Process Definition.

The following options are available on the Operator Message:

• Finish Job in Error: The RunMyJobs process is set to status ERROR. Nothing happens to the remote z/OS job.
• Complete Job: The RunMyJobs process is set to status COMPLETED. Nothing happens to the remote z/OS job.
• Restart z/OS job: The RunMyJobs process is restarted with all the same parameters, which resubmits the z/OS job from the beginning.
• Restart from Step xxx: Restarts the job from a particular step in the JCL.
  • NOTE: The restart steps will only be provided if the JESMSGLG file is available from the z/OS job spool files. An appropriate MSGLEVEL must be specified in the JCL to produce this file if restarting from a specific step is desired.
  • NOTE2: To facilitate the restart from a particular step when the original job was submitted from a DataSet or UnixFile, the Process must download the contents of that file to add the restart parameter to the JCL. As such, the z/OS account specified to submit the job must have the appropriate access to read the file contents and fetch the JCL code.

Once you make a selection and reply to the Operator Message, the original job will complete (it will complete in error unless the Complete Job option was selected). If a restart option was selected, a new RunMyJobs process will start to submit the new z/OS job.

Redwood_ZOS_Template

This template definition is provided to facilitate creating definitions that run specific z/OS jobs. It's functionality and parameters are the same as the Redwood_ZOS_RunJob definition. To create a definition, choose New (from template)... from the context menu of Redwood_ZOS_Template.

Troubleshooting

When issues occur, it is possible to get additional logging information in the output files. To enable this additional logging, select the Debug options for both Out Log and Error Log on the Advanced Options tab on the Control page when you submit the process that requires troubleshooting.

Privileges Required

To use z/OS Connections, you need one of the following:

• scheduler-administrator or redwood-administrator role.
• scheduler-user or redwood-login role in combination with the following system-wide, Partition-wide or object-level privileges.

Built-in Roles

• The scheduler-administrator or redwood-administrator built-in role provides full control over all z/OS connections.

Creating, Modifying z/OS Connections

You need all of the following privilege ranks to be able to create and modify z/OS connections:

• View - on Partitions GLOBAL and ZOS.
• View - on application REDWOOD.Redwood_ZOS.
• View - on the existing z/OS Process Server and Queue, if applicable.
• View - on constraint definition REDWOOD.Redwood_ZOSConnectionConstraint.
• View - on extension point REDWOOD.Redwood_ZOS_Connection.
• View - on Definition Type REDWOOD.Redwood_ZOS.
• View - on Process Server service REDWOOD.ServiceForRedwood_ZOS.
• Create - on Process Server and Queue if a new Process Server and Queue are required.
• Create - on ZOSConnection.

Using the z/OS Component

You need all of the following privilege ranks to be able to use an z/OS connection:

• View - on Partitions GLOBAL and ZOS.
• View - on application REDWOOD.Redwood_ZOS.
• View - on Redwood_ZOS library.
• Submit - on Process Definitions REDWOOD.Redwood_ZOS_RunJob and ZOS.Redwood_ZOS_ShowJobs.
• View - on the Process Server of the ZOS connection.
• JobAdministrator - on the Queue of the z/OS component.
• View - on ZOSConnection.

Deleting z/OS Connections

• View - on Partition REDWOOD.
• Delete - on ZOSConnection.

See Also

• z/OS Connector Component

• Privileges Required to Use Applications

• Privileges Required to Use Objects