Two ways to run our z/OS Java application on z/OS
Once we deploy our z/OS Java application to z/OS, there are two ways we can run this Java application. The first method is very familiar to existing Java programmers on Windows or Linux, and that is to run it via the command line interface in USS (Unix System Services). USS is a Unix component of z/OS, and behaves very similar to regular Unix environments. The second method is familiar to existing z/OS programmers, which is to run it in z/OS batch.
Deploy z/OS Java application to z/OS using IBM Explorer for z/OS
IBM Explorer for z/OS allows us to export our Java project to z/OS USS file system.
In the Package Explorer view, right click on our Insurance project, and click on Export… in the context menu. This will bring up the Export window. Under the General category, select z/OS UNIX File System.
This will copy our Insurance project, which is currently stored locally in our Eclipse environment, to the z/OS USS file system. Click Next.
Select our Insurance project as the resource to export. Select either an existing z/OS connection or create a new z/OS Remote System Connection. In the graphic below, we already have an existing z/OS connection.
Please Note: In order to connect to a z/OS server from within Eclipse using IBM Explorer for z/OS, the server side host component of IBM Explorer for z/OS Server must be installed on the z/OS server. See https://developer.ibm.com/mainframe/products/downloads for details.
Select the Destination Directory, and click Finish:
Compiling our z/OS Java program on z/OS
We’re going to open up a remote z/OS USS shell in order to compile our z/OS Java program.
Open up the Remote Systems view and browse to the remote z/OS system where we exported our Insurance Java project. Right-click on the Insurance directory, and choose Launch Shell from the context menu:
This will open up a remote z/OS USS shell environment within Eclipse.
Within the Remote Shell view, issue the following command to compile our z/OS Java application:
javac -d bin src/ReadPayeeData.java
- The compiled ReadPayeeData.class file should be in the bin directory under the Insurance project.
Running our z/OS Java application under the z/OS USS environment
Running a Java application under z/OS USS is like running Java in a Windows or Linux environment. First, we set our classpath point to the directory containing the Java class file we want to run, then we invoke the java command to run our program.
In the Remote Systems view, browse to our Insurance project and open up a remote shell (by right clicking on the Insurance directory and click on Launch Shell from the context menu).
Update the classpath so that it points to the bin directory under the Insurance project.
Run our z/OS Java program. We need to provide our Java program with the name of the z/OS data set to read from, and in this case, we want to read a data set called
Here is the output.
We’ve done all this inside our Eclipse IDE by using the Remote Shell view. If you prefer a bit more flexibility, you can SSH into your z/OS system’s USS shell environment using a free tool such as PuTTY.
Running our z/OS Java application under the traditional z/OS batch environment
Those z/OS programmers that have accustomed to running their COBOL or assembler applications under the z/OS batch environment should feel right at home running Java under this same environment. For those of us who are new to z/OS, this process can be a bit more challenging.
In order to run Java applications under z/OS batch, we need a launcher that can launch a Java application from batch, and this is where the JZOS batch launcher comes into play. We will be using the JZOS batch launcher to launch our z/OS Java application.
Setting up the JZOS batch launcher
The JZOS batch launcher is included as part of the IBM SDK Java Technology Edition for z/OS. But before we can use it, we need to move the JZOS batch launcher from the Java install directory in the USS environment into a z/OS data set, specifically, a PDSE (partitioned data set extended, aka LIBRARY) data set.
Let us create a z/OS PDSE data set. This the data set where we will copy our JZOS batch launcher into.
Open the Remote Systems view in Eclipse. Browse to our connected z/OS system, and right click on MVS Files, choose New -> Allocate Partitioned Data Set…
A new Allocate Partitioned Data Set window will pop up. Select your existing z/OS connection and choose a data set name for your data set. In our case, we decided on the name
JAVAFT1.HIGHRISK.JZOS.LOADLIB. Click Next.
We’re going to specify our data set allocation parameters manually, so select Specify characteristics (advanced allocation), and click Next.
We’re allocating the data set with the following characteristics as shown in the screen capture below. Click Finish when complete.
At this point, our z/OS PDSE data set should be allocated. Open the Remote Systems view and it will be listed under the Retrieved Data Sets category in MVS Files.
Let us go ahead and copy the JZOS batch launcher into the allocated PDSE data set.
We can find our JZOS batch launcher in the mvstools directory under our Java install path. Since we’re running Java 8.0 64-bit, our Java home directory is J8.0_64, and the JZOS batch launcher is a file called JVMLDM86. The LDM part of the name stands for load module, and 86 stands for Java 8.0 64-bit.
Open up a Remote Shell from the mvstools directory, and issue the following command to copy the JZOS batch launcher into the z/OS PDSE data set that we just allocated:
cp -X JVMLDM86 "//'JAVAFT1.HIGHRISK.JZOS.LOADLIB(JVMLDM86)'"
To verify that the JZOS batch launcher was copied successfully, open the Remote Systems view and look for the
JAVAFT1.HIGHRISK.JZOS.LOADLIBdata set under the MVS Files section of your existing z/OS connection. Refresh the data set by right-clicking and selecting Refresh and you should see the JZOS batch launcher load module:
Setting up z/OS batch scripts (aka JCL) that will start the JZOS batch launcher
Now that we have our JZOS batch launcher setup, we need to create some z/OS scripts that will kick off the JZOS batch launcher. These scripts are called JCL, also known as the Job Control Language. In this example, we’re going to use two JCLs, one JCL specifically for invoking the JZOS batch launcher and the other JCL for defining application specific environment.
The z/OS version of the IBM SDK Java Technology Edition includes samples of the z/OS batch scripts used to start the JZOS batch launcher. These samples can be found under the mvstools/samples/jcl directory of your z/OS Java installation.
The file JVMPRC86 contains what is known as a PROC, which runs the JZOS batch launcher.
The file JVMJCL86 defines application specific configurations and environment, and executes the PROC defined in JVMPRC86.
In our case, these JCL samples are for Java 8.0 64-bit, since their name ends in 86.
We want to copy these two JCL samples and place them in z/OS data sets. Create a new z/OS data set by opening the Remote Systems view and right click on your connected remote system’s MVS Files, and choose New -> Allocate Partitioned Data Set…
Were going to call our new data set
Again, we’re going to specify our data set characteristics using advanced allocation.
Click Next again.
Allocate the data set with the following characteristics as shown in the screen capture below.
Click Finish when complete.
We should now see the following under the Retrieved Data Sets section in the Remote Systems view.
Copy the two JCL samples under our z/OS Java installation path by highlighting them, right-clicking, and selecting Copy.
Right-click on the
JAVAFT1.HIGHRISK.JZOS.JCLdata set and choose Paste.
This will make copies of the two JCLs and place them under the
Refresh this data set and confirm that the two sample JCLs have been copied over successfully.
Configuring z/OS batch scripts (aka JCL)
Since the two sample JCLs that we copied over are just samples, we need to customize them for our particular environment and application.
- Let’s start by configuring JVMPRC86, the JCL that starts the JZOS batch launcher. The only change we need to make to this JCL is to tell it the location of our JZOS batch launcher. We do this by un-commenting the
LIBRARYparameter (on line 17) of the PROC and the
STEPLIB DDstatement (on line 24).
Update the LIBRARY parameter value to point to the PDSE data set containing our JZOS batch launcher,
Configure JVMJCL86 by updating the value of the
JAVACLSargument (on line 19) to the name of the Java class that we want to run. In this case, ReadPayeeData.
JAVA_HOME(on line 26) with our z/OS Java installation path,
/home/javaft1/javaonz/java/J8.0_64, ans update
APP_HOME(on line 37) with the location of our Java class file, which is located in
We need to provide a z/OS data set name as an argument to our Java program. This is the data set that our Java program will open and read data from, which is
JAVAFT1.HIGHRISK.DATA.PAYEE, in our example.
Finally, we’ll need to add a job card to the very beginning of this JCL. A job card tells the system that this JCL is a job that can be submitted for execution.
The name of our job is
On line 2, the PROCLIB statement tells the system the location of JVMPRC86, which we rely on to start the JZOS batch launcher. For this example, the location is
Submitting our job and running our Java application under z/OS batch
Once we have the JZOS batch launcher setup and our JCLs setup and configured, running our Java application under z/OS batch is as simple as clicking a few buttons.
Open the Remote Systems view, under the MVS Files category, look for our JVMJCL86 JCL in our data set
JAVAFT1.HIGHRISK.JZOS.JCL. Right-click on JVMJCL86, and choose Submit in the context menu. This will submit our job which will run our z/OS Java application using the JZOS batch launcher.
A window will pop up confirming the job submission:
If you click on Notify, a notification will display on the bottom of your Eclipse IDE when the job completes execution:
Notice the completion code of 0000. That means our Java application ran successfully!
Too see the output of our Java program, navigate to the JES category of the Remote Systems view, expand My Jobs, and search for our job, which is
The STDOUT report should contain the standard output of our Java application.
If we open it, that’s exactly what we’ll find:
After you complete writing your application:
- Show Deploy from z/OS Explorer
- Don’t want to deploy? Want to develop/test on your local machine… Then look into RD&T (not covered in this tutorial)
- Compile the program remotely
- Run it from USS directly, or
- Submit the program as a batch job using the JZOS Batch Launcher