IBM z/OS Connector

Introduction

Prerequisites

• Version 9.2.9 or later
• Connections component (dependency handled by the catalog)
• 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:

Object Type	Name
Application	REDWOOD.Redwood_ZOS
Constraint Definition	REDWOOD.Redwood_ZOSConnectionConstraint
Extension Point	REDWOOD.Redwood_ZOS_Connection
Process Definition	REDWOOD.Redwood_ZOS_Template
Process Definition	REDWOOD.Redwood_ZOS_ShowJobs
Process Definition	REDWOOD.Redwood_ZOS_RunJob
Definition Type	REDWOOD.Redwood_ZOS
Library	REDWOOD.Redwood_ZOS
Service	REDWOOD.ServiceForRedwood_ZOS

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 agent where the RunMyJobs Process is running.

1. Navigate to Custom > Connections and choose .
   
2. Choose IBM z/OS under Select a Connection Type.
3. 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.
   
4. Choose Next or Security, this is a screen for all components, choose to specify which roles can access the connection information.
   
5. Choose Next or IBM z/OS Properties, this is specific for the z/OS component, you specify URL, Username, and Password for your connection.
   
6. 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.

note

By default, the job status is updated every 10 seconds.

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

note

In some versions of the product, multiline input is not supported in the process definition submit wizard. To work around this, add the Process Definition to a Chain, and use the chain editor to specify the multi-line JCL parameter.

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.

See Also

Privileges Required to use the z/OS connector

Introduction

Prerequisites

• The Redwood IBM z/OS connector is packaged as a separate car file available on request.
• It requires RunMyJobs / Cronacle / BPA version 9.1.x or newer.
• Privileges Required to use the z/OS connector
• Connectivity from the central Redwood server to BusinessObjects on its port
• Connectivity from the secure gateway to BusinessObjects on its port

Installation

On release 9.2.x or higher the .car file can be installed using standard promotion. On release 9.1.x the .car file can be imported by submitting System_APP_Install.

Contents of the car file

The car file consists of the following objects:

Object Type	Name
Application	ZOS.Redwood_ZOS
Process Definition	ZOS.Redwood_ZOS_Template
Process Definition	ZOS.Redwood_ZOS_ShowJobs
Process Definition	ZOS.Redwood_ZOS_RunJob
Library	ZOS.Redwood_ZOS

Setup

z/OS processes need their own Credential, Process Server, and Queue. These objects should not be in partition GLOBAL. By default, all the z/OS objects live in the partition ZOS. 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 agent where the RunMyJobs Process is running.

Credential

To set up the RunMyJobs connection to the z/OS API, create a Credential object with the fields set as follows:

• Partition: The Partition you want to store your Credential in
• Protocol: soap
• Real User: The username of the z/OS user that will submit the jobs
• Password: The z/OS user's password
• Endpoint: The protocol, host, and (optional) port for your z/OSMF instance.
  Examples:
  • https://my-zos-server
  • https://192.168.0.5
  • https://my-zos-server:443
  • https://192.168.0.5:4433
• Virtual User: the name of your z/OS Process Server

Example Credential

Authentication Note

By default, basic authentication is used. Basic auth is used for the first request, then an LTPA2 token is returned and is used for subsequent requests.

If your z/OSMF instance is configured to support JWT authentication, you can force the RunMyJobs definitions to use it by adding the prefix {token} in front of the real user (so in the example above, the Real User field would be set to {token}IBMUSER). When token authentication is specified, the jobs will first use the z/OSMF login endpoint to authenticate, then use the returned JWT token to make the subsequent calls to the API.

Process Server

The Process Server zOS_ProcessServer is used as an example to set up the connection to a z/OS system. To connect to more than one z/OS system or to use multiple users, duplicate the Process Server and create a new queue and a credential of type SOAP for that z/OS system user. Make sure that the ScriptService with the RedwoodScript definition type and the JobChainService with JobChain definition type are enabled on the Process Server.

Example of a process server:

Example Process Server

Queue

Finally, create a new Queue object that contains the process server created above. At runtime, specify this queue on the Control tab of the submit wizard. The job will use the process server name to look up the credential with the matching Virtual User field, and use that credential to authenticate to the server.

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.

note

By default, the job status is updated every 10 seconds.

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.
   • Example (Fully Qualified Dataset): Prefix with //, then enclose the fully qualified dataset in single quotes. //'USER.TEST.JOBS(TESTJOB)'
   • 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.
4. To submit a job from a Unix File, provide the absolute path the file.
   Example: /u/jdoe/testjob.jcl
5. Provide the JCL code directly in the JCL parameter.
6. 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

note

In some versions of the product, multiline input is not supported in the process definition submit wizard. To work around this, add the Process Definition to a Chain, and use the chain editor to specify the multi-line JCL parameter.

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.

See Also

Privileges Required to use the z/OS connector