Command-line System Tools on IBM z/OS

Command-line tools for IBM z/OS require z/OS 1.7 or higher and are distributed separately from RunMyJobs.

The system tools can be used with MVS batch jobs started via the JCL_FTP Definition Type, via MVS batch jobs started via other means, and with UNIX System Services. Their intended use is the integration of RunMyJobs into existing host scheduling solutions.

Installation

The software is distributed as client-tools-zos-{version}.zip. This file contains a client tool named jtool and a secure library named secure.so.

1. Copy this file to a workstation that has a zip program and a FTP connection to the host and decompress it there.

2. Transfer the two files to the host. If you are using FTP, use BINARY transfer mode. You must always transfer the files to a HFS or ZFS file system, not a PDSE library. An example to transfer it to a z/OS host using a UNIX or Microsoft Windows version of jtool is shown below. Use an explicit UNIX path as the target name to make sure that the z/OS FTP server places the file on HFS or ZFS.

   Copy

   jtool unzip client-tools-zos-9.1.1.0.zip
   jtool ftp put -binary ibmuser PASSWORD jtool     /usr/local/bin/jtool
   jtool ftp put -binary ibmuser PASSWORD secure.so /usr/local/bin/secure.so

3. Once you have transferred the files, log in to the z/OS host and set the executable bits on the files and install links.

   Copy

   cd /usr/local/bin
                       chmod 755 jtool secure.so
                   ./jtool install

   You will now have jecho, jftp, jlog, jscript, jsleep, jcat, jevent, jgetfile and jputfile links to jtool so that you can use these directly.

4. If your Redwood Server uses HTTPS (as opposed to HTTP), you must also transfer secure.so to the host system. secure.so can only be used with jtool if it is in the same directory, and this has to be a ZFS/HFS directory and cannot be a PDSE library.

   Note: If you use Redwood Server in a public cloud you must use HTTPS, and thus cannot use jtool in a PDSE.

Copying the Command-line Tools to PDSE

If your RunMyJobs server uses HTTP, you can copy the jtool executable to a PDSE program object by rebinding. Use of a PDSE instead of PDS is required because the program object uses version 3 program object features.

For example, to use a JCL Step to copy jtool to a PDSE named JCS.LOAD:

//STEP1     EXEC PGM=IEWBLINK,REGION=1000K,
//          PARM='LIST,REUS,RENT,LET,MAP'
//SYSPRINT DD  SYSOUT=*
//SYSLMOD  DD  DSN=&SYSUID..JCS.LOAD,DISP=SHR
//*
//INLIB    DD  PATH='/usr/local/bin/jtool',
//             PATHOPTS=(ORDONLY)
//*
//SYSLIN   DD *
        INCLUDE INLIB
        ENTRY   CEESTART
        NAME    JTOOL
/*

Like the USS version of jtool, the PDSE version can see by the member name what command it is supposed to be executing, saving you an argument to be passed. In other words, if you transfer it to a member named JEVENT, it will interpret this the same as being named JTOOL and called with the event first argument.

jtool ftp put -binary ibmuser PASSWORD secure.so /usr/local/bin/secure.so

Available Tools

The following tools are available on z/OS. Additional instructions specific to z/OS can be found below, as well as examples of the two most important tools: raising an event from the host, and running a RunMyJobs script from the host.

In general, these tools perform the same function as on other operating systems. One restriction is that z/OS jobs run under the control of JES, and thus do not have a RunMyJobs job context. Consequently, the job context parameter is inoperative in all tools running on z/OS.

Creating a Connection File

Most of the system tools connect to the central RunMyJobs server using an HTTP(S) connection. The tools authenticate themselves using a connection file that is created using the jsecret or jtool secret tool.

Connection files are humanly readable files that can successfully be stored both in stream files and in libraries with RECFM=FB with LRECL=80.

The files are portable between ASCII and EBCDIC based systems. You can create one on a UNIX or Microsoft Windows system, and transfer it to the z/OS host (or the other way around), as long as you translate the file from ASCII to EBCDIC.

Proxy Settings

The following environment variables are used to retrieve proxy server connection details.

• HTTP_PROXY: The URL of the proxy server. For example: https://proxy.example.com:3128.
• PROXY_USER: The user for the proxy server. This is ignored if HTTP_PROXY is not set.
• PROXY_PASSWORD: The password for the proxy user. This is ignored if HTTP_PROXY is not set.
• NO_PROXY: Enforces a direct connection.

Note: These environment variables override the settings in the connection file.

Creating a Connection File with JCL

To create a connection file, you must call jsecret, or jtool with the word secret as the first parameter.

The following example illustrates the creation of a connection file using JCL. The RunMyJobs server is named pr1.masalan.com, and the port it is listening on is 10180.

//DEMO1    JOB 0,'CREATE CONNFILE',CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//*
//MAIN     EXEC PGM=JTOOL,
//         PARM='/ secret -c DD:CONN https://pr1.masalan.com:10180/redwood'
//CONN     DD DISP=SHR,DSN=JCS.DEMO.CNTL(CONN1)
//SYSPRINT DD SYSOUT=*
//SYSIN    DD *
admin
mypwd
/*

Creating a Connection File with UNIX System Services

It is best to create the connection file with a UNIX System Services shell, rather than OMVS. If you use the OMVS shell, it will show the password you enter.

The following example illustrates the creation of a connection file using a UNIX System Services shell. The RunMyJobs server is named pr1.masalan.com, and the port it is listening on is 10180.

$ /u/redwood/bin/jsecret  -c /u/jcsoper/admin.conn https://pr1.masalan.com:10180/redwood
User:  admin
Password: ****** (if using a character mode shell,  no input will appear)

Creating a Connection File on a Different System

You can also run the above command on a UNIX, Microsoft Windows, or HP OpenVMS system that has jtool installed, then transfer the file to the z/OS host. The file must arrive at the host in EBCDIC format. If you are using FTP, select the ASCII transfer mode to convert the file from ASCII to EBCDIC.

Raising Events

Raising an event from JCL using a PDSE

The following example raises the event named E1 from JCL.

//DEMO2    JOB 0,'RAISE EVENT',CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//*
//STEP1     EXEC PGM=JEVENT,
//          PARM='/ DD:CONFILE E1 "Raised from JCL"'
//STEPLIB  DD  DISP=SHR,DSN=HLQ.LIB.PROCLIB
//SYSPRINT DD  SYSOUT=*
//CONFILE  DD  DISP=SHR,DSN=JCS.DEMO.CNTL(CONN1)

The following example uses a HFS copy of jtool and the connection file. It uses BPXBATCH with the STDPARM data definition to avoid the length limit on the PARM parameter while still sending commands inline with the JCL.

//DEMO3    JOB 0,'RAISE EVENT',CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//S1  EXEC PGM=BPXBATCH
//STDPARM  DD *
SH
echo "admin" > /tmp/pwd.tmp ;
echo "mypassword" >> /tmp/pwd.tmp ;
/usr/local/bin/jtool secret -c /tmp/us.conn
  https://pr1.example.com/redwood < /tmp/pwd.tmp ;
rm /tmp/pwd.tmp ;
/usr/local/bin/jtool event /tmp/us.conn jclEvent
  "Raised by JES"
/*
//STDOUT  DD SYSOUT=*
//STDERR  DD SYSOUT=*

Raising an Event from UNIX System Services

To raise an event from UNIX System Services, call jevent with two or three arguments: the connection file, the name of the event, and an optional raiser comment.

For example, to raise an event named E1:

/usr/local/bin/jtool event -c /u/jcsoper/admin.conn  E1 "Raised from z/OS UNIX System Services"

Calling the RunMyJobs API

You can call the RunMyJobs API using jscript or jtool script. The jscript tool supports RedwoodScript.

The following example submits a process named System_Info. Note that in the SYSIN stream, a line with just / ends a command in jscript, causing it to be executed, and that /* terminates the STDIN DD input.

//DEMO4    JOB 0,'SUBMIT JOB IN CENTRAL SERVER',CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
//*
//* Run the Redwood Server job System_Sleep
//*
//MAIN     EXEC PGM=JSCRIPT,
//         PARM='/ DD:CONFILE'
//STEPLIB  DD  DISP=SHR,DSN=JCS.LIB.PROCLIB
//SYSPRINT DD  SYSOUT=*
//CONFILE  DD  DISP=SHR,DSN=JCS.DEMO.CNTL(CONN1)
//SYSIN    DD *
{
  JobDefinition jDefinition = jcsSession.getJobDefinitionByName("System_Sleep");
  Job j = jDefinition.prepare();
  jcsSession.persist();
}
/
/*

For clarity, in the above example the following jscript was executed:

{
  JobDefinition jDefinition = jcsSession.getJobDefinitionByName("System_info");
  Job j = jDefinition.prepare();
  jcsSession.persist();
}
/

System Tool Condition Codes

The command-line system tools use standard z/OS condition codes.