Automating JCL job submission from z/VM

This topic describes how to coordinate z/OS jobs with z/VM work, by submitting z/OS jobs directly from z/VM.

Overview

This section demonstrates how to:

• Submit jobs with the FILETYPE=JES mode of the z/OS FTP server.
• Use the VMFTP tool to process output from FTP.
• Automate JCL job submission using a REXX wrapper.

Automating JCL job submission

z/OS Job Control Language (JCL) is a powerful and mature language and environment for submitting work or jobs to the mainframe. JCL jobs can be submitted in a number of different ways, including:

• Interactively through a z/OS TSO session
• Remotely through RSCS from different environments
• Remotely through FTP from different environments

This section focuses on submitting JCL from z/VM through FTP. It consists of the following sections:

• Submitting JCL Jobs Using FTP
• Obtaining and Installing the VMFTP Tool
• Writing a VMFTP Macro
• Two Sample JCL Jobs
• Adding a Wrapper Around FTPJOB
• Putting it All Together

Submitting JCL Jobs Using FTP

The z/OS FTP server has a special mode for submitting JCL jobs and retrieving their output. When the FTP subcommand site filetype=jes is issued, the subcommands get, put, and delete take on a different meaning. For example, in an FTP session to z/OS, consider the following subcommands:

After issuing the site filetype=jes subcommand, the put subcommand submits a JCL job with the specified file name. After the job has completed, the get subcommand retrieves the output. The file type of X is special as the FTP server concatenates all output files from the job into one. The output files include:

• The job log
• The JCL
• System messages
• Program output (DD SYSOUT=)

Consider the following example where MDMS JCL is a file on the user’s A disk with a sample JCL job:

In this example, the job named MDMS is submitted through FTP. It is given the next available job number, 09623 in this example. That job number is then used on the get subcommand with the .X file type to retrieve all output from the job.

Obtaining and Installing the VMFTP Tool

To automate the submission of JCL jobs, the job number must be obtained from the FTP server output after each job is submitted. The code to read the FTP output could be written from scratch, or an existing tool could be used. Many people suggested using the VMFTP tool when this question came up on the IBM-VM list server. For access to this resource see:

http://listserv.uark.edu/cgi-bin/wa?A0=IBMVM

To utilize the VMFTP tool, perform the following steps:

• Download VMARC to a workstation so you can unpack the VFMTP file. It can be obtained from the z/VM downloads page:
  http://www.vm.ibm.com/download/
  It can be directly downloaded from:
  http://www.vm.ibm.com/download/vmarc.module

• Download the VMFTP tool to a workstation. It can be downloaded from:
  http://zvm.sru.edu/~DOWNLOAD/
  Search for VMFTPUPD.

  Important

  There is an older package VMFTP from 1997. Do not use that one as it has known bugs fixed buy VMFTPUPD.

• From the workstation, FTP the files vmarc.module and vmftp.vmarc in binary to a z/VM virtual machine from where the JCL jobs will be submitted.
• Start a 3270 session to the same z/VM virtual machine where the two files were copied.
• Deblock the VMARC MODULE with the following pipe command:
  ==> pipe < vmarc module a | deblock cms | > vmarc module a
• Deblock the VMFTP VMARC file with the following pipe command:
  ==> pipe < vmftpupd vmarc a | fblock 80 00 | > vmftpupd vmarc a f 80

• Use the VMARC command to unpack the VMFTP package:

  ==> vmarc unpk vmftpupd vmarc a
  VMFTP ASSEMBLE A1. Bytes in= 26880, bytes out= 52224 ( 194%)
  VMFTP CNTRL A1. Bytes in= 240, bytes out= 400 ( 166%)
  VMFTP HELPCMS A1. Bytes in= 3920, bytes out= 7078 ( 180%)
  VMFTP MEMO A1. Bytes in= 2080, bytes out= 3416 ( 164%)
  VMFTP MODULE A1. Bytes in= 5520, bytes out= 7843 ( 142%)
  VMFTP NODELAY A1. Bytes in= 320, bytes out= 480 ( 150%)
  VMFTP NOMASKPW A1. Bytes in= 1920, bytes out= 3886 ( 202%)
  VMFTP TEXT A1. Bytes in= 7200, bytes out= 12640 ( 175%)
  VMFTP UPDTCONT A1. Bytes in= 1440, bytes out= 3040 ( 211%)
  VMFTP UPDTC250 A1. Bytes in= 400, bytes out= 560 ( 140%)
  VMFTP UPDTPASV A1. Bytes in= 400, bytes out= 400 ( 100%)
  VMFTP UPDTXLAT A1. Bytes in= 1600, bytes out= 3600 ( 225%)
  GETDIR VMFTP A1. Bytes in= 1280, bytes out= 5920 ( 462%)
  TEST VMFTP A1. Bytes in= 640, bytes out= 2720 ( 425%)
  TESTNOPW VMFTP A1. Bytes in= 480, bytes out= 2080 ( 433%)

You should now be able to use the VMFTP tool by creating FTP macros with a file type of VMFTP and invoking them with the VMFTP command. Some brief help with “drill-down” capability is invoked with the following command:

Writing a VMFTP Macro

Following is a VMFTP macro, named FTPJOB VMFTP, to submit a JCL job. It is passed one argument, the JCL job name. It does the following:

• Reads the input argument and sets the jobName variable
• Starts an FTP session with the OPEN, USER, and PASSWORD subcommands
• Goes into JCL mode with the SITE FILETYPE=JES subcommand
• Submits the job with the PUT subcommand
• Obtains the JCL job name
• Gets the JCL output with the GET subcommand
• Searches for error messages (FDRnnn**) and prints them when found
• Ends the FTP session

This macro can now be tested.

Two Sample JCL Jobs

Two sample JCL jobs are used to test the FTPJOB VMFTP macro, one designed to succeed and the other to fail:

1. MDMS JCL - a job to sort the list of planets included as data within the job. It is designed to succeed.

   ==> type mdms jcl a
   
   //MDMS JOB ('PR=YES'),'MIKE',CLASS=M,MSGCLASS=X
   //STEP1 EXEC PGM=SORT
   //SYSIN DD *
    SORT FIELDS=(1,75,CH,A)
   /*
   //SYSOUT DD SYSOUT=*
   //SORTIN DD *
   NEPTUNE
   EARTH
   VENUS
   MERCURY
   MARS
   URANUS
   SATURN
   JUPITER
   /*
   //SORTOUT DD SYSOUT=*
   /*
   

2. MDMC JCL - A job that performs an FDRPASVM SIMSWAP operation. It is designed to fail (volume serial number is not correct).

   ==> type mdmc jcl a
   
   //MDMC JOB ('PR=YES'),'MIKE',CLASS=M,MSGCLASS=X
   //PAS.SYSIN DD *
    SIMSWAP TYPE=FULL,LARGERSIZE=OK,MAXTASKS=4,NONRESPONDING=FAIL
   *SIMSWAPMON TYPE=FULL,LARGERSIZE=OK,MAXTASKS=4,NONRESPONDING=FAIL
   *SWAPDUMP TYPE=FULL,LARGERSIZE=OK,MAXTASKS=4,NONRESPONDING=FAIL
   *SWAP TYPE=FULL,LARGERSIZE=OK,MAXTASKS=4,NONRESPONDING=FAIL
    MOUNT VOL=73BSP1,SWAPUNIT=188B

Now that a VMFTP macro is written and sample jobs exist, they can be submitted to z/OS with the VMFTP command with the FTPJOB macro as the argument.

Submitting a Successful JCL Job

Following is an example of submitting the job to sort planets with the VMFTP command. To pass in the JCL job name, the (PARM operand is utilized.

The output file is a concatenation of all the output files from the z/OS job. Note that the last output file shows the sorted data.

Submitting a JCL Job that Fails

The second job, MDMC JCL, is submitted, and the error messages in the output are displayed:

The output shows that a job was submitted, its output was retrieved, and error messages were found.

Adding a Wrapper Around FTPJOB

Now that there is a process to submit a single job, a REXX EXEC wrapper can be written around it to submit a series of jobs. Following is the REXX EXEC to accomplish this:

This EXEC reads the job names from the file FTPJOBS LIST A. To test, this file had three job names:

These three jobs have different expected outcomes:

MDMS JCL A job that should succeedMDMC JCL A job that should fail with certain error messagesNOSUCH JCL A nonexistent job (no such file)

Putting it All Together

Following is an example of running the FTPJOBS EXEC:

The output shows that no error messages were found in the output of the MDMS job, error messages were found in the output of the MDMC job and printed, and an error message stated that the NOSUCH job file was not found.