← Using the JCL_FTP Definition TypeBalancing the Load →

System Tools on IBM z/OS

The system tools for IBM z/OS are distributed separately. The tools require z/OS 1.7 or higher.

The system tools can be used with MVS batch jobs started via the JCL_FTP Process Definition Type, via MVS batch jobs started via other means as well as using the UNIX System Services. Their intended use is the integration of Redwood Server in existing host scheduling solutions.

Installation

To install the system tools on a z/OS node please execute the following steps.

Unpack the software installation file

The software is distributed as client-tools-zos-{version}.zip. Copy this file to a workstation that has a UNZIP program and a FTP connection to the host.

In the zip file are two files:

FilenameContents
jtoolClient tool
secure.soSecure library

Transmit the installation material

Transfer the received installation material to the host. When 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 given 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.

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

Execute steps on z/OS USS shell

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

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.

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.

Copy software to PDSE

If your Redwood Server uses HTTP you can copy the jtool executable to a PDSE program object by rebinding. Use of a PDSE instead of PDS is mandatory as the program object uses version 3 program object features.

An example JCL step to copy it to a PDSE named JCS.LOAD is:

//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, with links to their generic (non z/OS) descriptions. z/OS specific additional instructions appear below as well as examples of the two most important tools: raising an event from the host and running a Redwood Server script from the host.

ToolPurposeConnection file
jechoPrint messages to stdout-
jeventRaise an eventYes
jftpTransfer files via FTP-
jgetfileGet a output fileYes
jlogLog in common logging format-
jputfileUpload file to the serverYes
jscriptRun a scriptYes
jsecretGenerate a user or network-processor secretYes
jsleepSleep a number of seconds-
jtoolinstall all or run any of the above-

In general the 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 Redwood Server job-context, and the job-context parameter is inoperative in all tools running on z/OS, even though the tools still mention this as a possibility.

Creating a connection file

Most of the system tools connect to the central Redwood Server using a 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 in stream files but also 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 to the proxy server, https://proxy.example.com:3128
  • PROXY_USER - The user for the proxy server, ignored if HTTP_PROXY is not set
  • PROXY_PASSWORD - The password for the proxy user, ignored if HTTP_PROXY is not set
  • NO_PROXY - Enforce a direct connection
note

These environment variables override the settings in the connection file.

Creating a connection file using JCL

To create a connection file you need to 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 Redwood 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 using UNIX System Services

The creation of the connection file is best accomplished using a UNIX System Services shell, not using OMVS. If you use the OMVS shell it will show the password that you enter.

The following example illustrates the creation of a connection file using a UNIX System Services shell. The Redwood 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 a Redwood Server jtool installed and then transfer the file to the z/OS host. The file must end up at the host in EBCDIC; when using FTP select the ASCII transfer mode to convert the file from ASCII to EBCDIC.

Raising an event in Redwood Server

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 but still send 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

Raising an event from UNIX System Services is simple: just call jevent with two or three arguments: the connection file, the name of the event and a raiser comment. The comment is optional.

For example to raise the event named E1:

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

Calling the Redwood Server API

You can call the 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 system tools use standard z/OS condition codes

Cond CodeMeaningExample
0Successful execution

4Warning

8ErrorFor instance, failed to raise event (no such event) or incorrect password
12Severe

16FatalSyntax error in arguments or unable to connect to server
← Using the JCL_FTP Definition TypeBalancing the Load →