Overview

Skill Level: Any Skill Level

This article shows how a sample java code is implemented to request a z/OS batch job and to retrieve job outputs. This article also explains how to make a request to a z/OS server from a client and to retrieve the resulting outputs from the z/OS server.

Ingredients

  • Java environment on Windows or Unix
  • Apache Commons Net Library
  • FTP server on z/OS

Step-by-step

  1. Introduction

    You can submit z/OS batch jobs through a z/OS FTP server as described in “Submit batch jobs from Java on z/OS“. You can also retrieve job outputs as described in “Access z/OS batch jobs from Java“. To retrieve job outputs, you must have a means to detect the completion of a job. This article provides a sample java code and shows how this sample code is implemented to request a z/OS batch job and to retrieve outputs from the batch job.

  2. Basic function

    The basic function of the sample code is to submit a job to z/OS and then retrieve the job log file.

    FTP session

    The following shows a basic flow for an FTP session to submit a job and retrieve the job log file:

    1. Start an FTP session to the z/OS FTP server. Enter the user ID and the password.
    2. Issue the QUOTE SITE command to identify the file as having JCL statements (FILETYPE=JES) and to retrieve the job log file with any jobname (JESJOBNAME=*)
    3. Issue the put command to send the job file to z/OS.
    4. Issue the get command with the job number to retrieve the job log file.

    An example of an FTP session log on a Windows client is shown below. The sample code basically runs the same as below.

    C:\work>ftp 192.168.54.11

    Connected to 192.168.54.11.

    220-FTPD1 IBM FTP CS V2R2 at RSI1.rocketsoftware.com, 22:06:51 on 2017-08-22.

    220 Connection will close if idle for more than 5 minutes.

    User (192.168.54.11:(none)): tssys

    331 Send password please.

    Password:

    230 TSSYS is logged on.  Working directory is “TSSYS.”.

    ftp> QUOTE SITE FILETYPE=JES JESJOBNAME=*

    200 SITE command was accepted

    ftp> put listcat.jcl

    200 Port request OK.

    125 Sending Job to JES internal reader FIXrecfm 80

    250-It is known to JES as J0867114

    250 Transfer completed successfully.

    ftp: 473 bytes sent in 0.18Seconds 2.61Kbytes/sec.

    ftp> get J0867114.1

    200 Port request OK.

    125 Sending data set TSSYS.LISTCAT1.J0867114.D0000002.JESMSGLG

    250 Transfer completed successfully.

    ftp: 1330 bytes received in 0.00Seconds 1330.00Kbytes/sec.

    ftp> get J0867114

    200 Port request OK.

    125 Sending all spool files for requested Jobid

    250 Transfer completed successfully.

    ftp: 6331 bytes received in 1.18Seconds 5.39Kbytes/sec.

     

    Sending job and retrieving output

    When a job is submitted to z/OS, a job number is assigned. Job output can be retrieved by using this job number.

    The sample code retrieves the job number from the reply upon job submission. In the above session log, the job number is printed on the following line:

    250-It is known to JES as J0867114

    Use the get command with the job number to retrieve job output files. To retrieve all job output files, specify the job number for the get command. If you specify a job number with “.1” at the end for the get command, only the below JESMSGLG file is retrieved. A JESMSGLG file contains information to identify whether the job ended.

    Message $HASP395 in a JESMSGLG file indicates that the job completed. If -JCL ERROR is printed instead of message $HASP395, it indicates that an error occurred during the job but the job completed. If either of these items is printed in the JESMSGLG file, it means all the job outputs are ready to be retrieved. If neither of these items is printed, wait for a while and check the JESMSGLG file again.

    If you are on z/OS Version 2, a job completion code is printed with message $HASP395 (RC=xxxx). If the job completion code is not zero, the sample code ends with return code 4 to alert the non-zero job completion code.

    1                   J E S 2  J O B  L O G  —  S Y S T E M  R S I 1  —  N O D E  R S P L E X I 1       

    0

     21.56.04 J0867103 —- TUESDAY,   22 AUG 2017 —-

     21.56.04 J0867103  IRR010I  USERID TSSYS    IS ASSIGNED TO THIS JOB.

     21.56.04 J0867103  ICH70001I TSSYS    LAST ACCESS AT 21:55:52 ON TUESDAY, AUGUST 22, 2017

     21.56.04 J0867103  $HASP373 LISTCAT1 STARTED – INIT 13   – CLASS A        – SYS RSI1

     21.56.04 J0867103  IEF403I LISTCAT1 – STARTED – TIME=21.56.04

     21.56.04 J0867103  RKTSW01I                                          ————- Timings (HH:MM:SS.hh) ————–

     21.56.04 J0867103  RKTSW01I   JOBNAME  STEPNAME PROCSTEP STEP    RC  CPU (Total)  CPU (TCB)    CPU (SRB)     zIIP Usage

     21.56.04 J0867103  RKTSW01I   LISTCAT1 STEP1               1     00  00:00:00.00  00:00:00.00  00:00:00.00  00:00:00.00

     21.56.04 J0867103  IEF404I LISTCAT1 – ENDED – TIME=21.56.04

     21.56.04 J0867103  RKTSW01I   LISTCAT1 JOB TOTALS:                   00:00:00.00  00:00:00.00  00:00:00.00  00:00:00.00

     21.56.04 J0867103  $HASP395 LISTCAT1 ENDED – RC=0000

    0—— JES2 JOB STATISTICS ——

    –  22 AUG 2017 JOB EXECUTION DATE

    –            7 CARDS READ

    –          103 SYSOUT PRINT RECORDS

    –            0 SYSOUT PUNCH RECORDS

    –            9 SYSOUT SPOOL KBYTES

    –         0.00 MINUTES EXECUTION TIME

  3. How to run the sample code

    1. Download the .zip file file containing the sample code. Extract the .zip file to an arbitrary location.
    2. Download the Apache Common Net Library and save the binaries (jar file) to the same location.
    3. Edit rsub.cmd for Windows or rsub.sh for Unix to match your environment.
    4. Open rsub.properties and change xxxxx to your FTP user ID and yyyyyyyy to your FTP password. The values set in rsub.properties are used as default values but you can change them at run time by using program parameters.

      # userid to submit JCL to host

      userid = xxxxx

      # password to submit JCL to host

      password = yyyyyyyy

    5. Run rsub.cmd or rsub.sh with the host name and the local file name as shown below. 

      C:\work>rsub rsi1 listcat.jcl

       

      C:\work>java RemoteJclSubmitter rsi1 listcat.jcl

      11:38:09 RemoteJclSubmitter FTP session started.

      11:38:20 RemoteJclSubmitter submitted listcat.jcl to rsi1 as J0826417.

      11:38:26 RemoteJclSubmitter created listcat.jcl.J0826417.log from rsi1 :

       22.37.58 J0826417  $HASP395 LISTCAT1 ENDED – RC=0000

      11:38:27 RemoteJclSubmitter ended with RC=0.

  4. Program interface

    The java program interface is shown below.

    Expected Parameters: <host> <JCLfile> (options)

        -u <userid>          Userid to submit <JCLfile> to <host>.

        -p <password>        Password to submit <JCLfile> to <host>.

        -r <retrycount>      Maximum retry attempts to retrieve job output.

        -w <waitsecond>      Wait time, in seconds, to retrieve job output.

        -o <outputfile>      Job output file. Default is <JCLfile>.Jxxxxxxx.log.

        -f <ftplogfile>      FTP log file. Default is <JCLfile>.rsubftp.log.

        -xb <xferbeforejob>  Transfer file list before submitting <JCLfile>.

        -xa <xferafterjob>   Transfer file list after the completion of <JCLfile> job.

        -qs <quotestart>     QUOTE SITE command file at the start.

        -qb <quotebeforejob> QUOTE SITE command file before submitting <JCLfile>.

        -qa <quoteafterjob>  QUOTE SITE command file after the completion of <JCLfile> job.

        If these options are not supplied, values in rsub.properties are used as default values.

    The default behavior of this program is to submit <JCLfile> to <host> by using the values in rsub.properties or the values supplied at run time.

    In addition, if the -xb option is specified, files in <xferbeforejob> are transferred before submitting <JCLfile>.

    Also, if the -xa option is specified, files in <xferafterjob> are transferred after the completion of <JCLfile> job.

      

    Return codes:

    0: Normal end

    4: Warning

    8: Error

    12: Severe error

  5. Advance functions

    The sample code supports options to transfer files between your local machine and z/OS before and after running the JCL job. These options allow you to put client requests to z/OS input data sets before submitting the JCL job and get z/OS output data sets after the job completes.

    The sample code also supports an option to invoke the SITE subcommand. By using the SITE subcommand, you can change code pages between EBCDIC and ASCII during your FTP session. By default, the FTP will convert the code pages using the default code page conversion table that is defined to each FTP server. However, if you want to change it explicitly, you can use the SITE subcommand to change the code pages.

     

    Transfer file list

    To request a file transfer before the job, use the “-xb” parameter. To request a file transfer after the job, use the “-xa” parameter. Both parameters must be provided with a transfer file list.

    A transfer file list must be in the following format:

    1stToken,2ndToken,3rdToken,4thToken

    g,’HostFileName’,LocalFileName[,b]

    p,LocalFileName,’HostFileName'[,b]

    1stToken : ‘g’ indicates get, ‘p’ indicates put

    4thToken : ‘b’ indicates binary mode

     

    An example of a transfer file list before the job is shown below.

     

    p,btsin.request,’IMSDEV.BTS.TEST.BTSIN.VAR’

    p,null.data,’IMSDEV.BTS.TEST.BTSISRIO.VAR’,b

     

    An example of a transfer file list after the job is shown below.

     

    g,’IMSDEV.BTS.TEST.BTSISRIO.VAR’,btsisrio.response

     

     

    SITE subcommand option file

    To specify SITE subcommand options, use “-qs”, “-qb”, and “-qa” parameters. All the parameters must be provided with a SITE subcommand option file. SITE subcommand parameters specified on these parameters take affect at the following time:

    -qs: At the start of the program.

    -qb: Before the JCL job is submitted.

    -qa: After the JCL job is completed.

    For a list of SITE subcommand options, see SIte subcommand—Send site-specific information to a host.

    For example, to change the encoding for single byte character set while transferring the files to z/OS, you create a SITE subcommand option file (below Listing) and provide this file with the “-qs” parameter at run time.

    SBD=(IBM-037,IBM-850)

    Here is another example. If host files referred to from your JCL job contain multibyte data, which is a data type that is not supported in the JCL job itself, you create three SITE subcommand option files, each containing a line in the below figure, and specify each file with the following parameters:

    • File containing “ENCODING=M MBD=(IBM-939,IBM-932)” with the -qs parameter. This causes the code page to change at FTP file transfer that occurs at the beginning of the program.
    • File containing “ENCODING=S” with the -qb parameter. This causes ENCODING=SBCS to take effect at the start of the JCL job.
    • File containing “ENCODING=M” with the -qa parameter. This causes ENCODING=MBCS to take effect at FTP file transfer that occurs after the JCL job is complete.

     

    ENCODING=M MBD=(IBM-939,IBM-932)

    ENCODING=S

    ENCODING=M

  6. Advanced example

    IBM provides IBM IMS Batch Terminal Simulator for z/OS (IMS Batch Terminal Simulator for z/OS) for testing IMS applications. If you apply PTF UI50918 to IMS Batch Terminal Simulator, you can use the sample code with IMS Batch Terminal Simulator.

    The following example shows how to request IMS Batch Terminal Simulator to run an IMS sample application, the PART transaction with parameter AN960C10, and results of the transaction. 

     

    C:\work>btsclient

    Enter transaction data :PART AN960C10

    C:\work>call rsub rsie btssamp2.jcl -xb btsbefore.txt -xa btsafter.txt

     

    C:\work>java RemoteJclSubmitter rsie btssamp2.jcl -xb btsbefore.txt -xa btsafter.txt

    15:24:34 RemoteJclSubmitter FTP session started.

    15:24:38 RemoteJclSubmitter submitted btssamp2.jcl to rsie as JOB08902.

    15:24:44 RemoteJclSubmitter created btssamp2.jcl.JOB08902.log from rsie :

     02.24.19 JOB08902  $HASP395 BTSPART  ENDED – RC=0000

    15:24:46 RemoteJclSubmitter ended with RC=0.

    Response data from BTS :

    PART=AN960C10         DESC=WASHER                PROC CODE=74

     

    INV CODE=2  MAKE DEPT=12-00  PLAN REV NUM=    MAKE TIME= 63  COMM CODE=14

       

    The following figure shows the IMS Batch Terminal Simulator job, btssamp2.jcl, that was submitted in the above example. 

    //BTSPART  JOB MSGCLASS=A

    //         JCLLIB ORDER=(IMSDEV.BTS.COMMON.PROCLIB)

    //BTSSAMP2 EXEC BTS,KW=’DLI’,IMSIDX=’IMS.IDJ1′,BTSIDX=’IMSDEV.BTS.IDX1′

    //G.STEPLIB  DD DISP=SHR,DSN=IMSTJP.BTS410.SBTSLMD0

    //           DD DISP=SHR,DSN=IMSDEV.BTS.IDX1.PGMLIB

    //           DD DISP=SHR,DSN=IMS.IDJ1.SDFSRESL

    //G.IMS      DD DISP=SHR,DSN=IMSDEV.BTS.IDX1.PSBLIB

    //           DD DISP=SHR,DSN=IMSDEV.BTS.IDX1.DBDLIB

    //G.IMSACB   DD DISP=SHR,DSN=IMSDEV.BTS.IDX1.ACBLIB

    //G.FORMAT   DD DISP=SHR,DSN=IMSDEV.BTS.IDX1.FORMAT

    //G.BTSIN    DD DISP=SHR,DSN=IMSDEV.BTS.TEST.BTSIN.VAR

    //G.BTSISRIO DD DISP=SHR,DSN=IMSDEV.BTS.TEST.BTSISRIO.VAR

    //G.DI21PART DD DSN=RSTEST.BTS.IDX1.DI21PART,DISP=SHR

    //G.DI21PARO DD DSN=RSTEST.BTS.IDX1.DI21PARO,DISP=SHR

    //DFSVSAMP   DD *

    4096,4

    8192,4

    //*

    //

     

    The 1st example in Advance function shows contents of the transfer file list (btsbefore.txt) that was used in this advanced example. Because this transfer file list was supplied with the “-xb” parameter, local file btsin.request was transferred to the host as IMSDEV.BTS.TEST.BTSIN.VAR (RECFM=V, LRECL=32756) before the job. Local file null.data was also transferred to the host as IMSDEV.BTS.TEST.BTSISRIO.VAR (RECFM=V, LRECL=32756) as binary data.

    The 2nd example in Advance function shows contents of the transfer file list (btsafter.txt) that was used in this advanced example. Because this transfer file list was supplied with the “-xa” parameter, host file IMSDEV.BTS.TEST.BTSISRIO.VAR (RECFM=V, LRECL=32760) was transferred from the host to local as btsisrio.response after the job.

     

Join The Discussion