EasySMF:JE Java Quickstart

This page is a guide to quickly getting up and running with the EasySMF:JE Java API on z/OS.

You can install all components except Java into your personal libraries and home directory, which makes trialling EasySMF:JE simple. If Java 8 is already installed, you should be able to install EasySMF:JE and be running the sample programs against your SMF data in 30 minutes or less.

Complete installation instructions are included in the
Installation and User Guide

Prerequisites

Java 8

Java 8 introduced the java.time date and time classes which are ideal for working with SMF dates and times. EasySMF:JE uses these classes extensively, so Java 8 is required.

Installation of Java on z/OS is outside the scope of this guide. Refer to IBM 31-bit SDK for z/OS, Java Technology Edition, Version 8 and/or IBM 64-bit SDK for z/OS, Java Technology Edition, Version 8 for Java installation instructions.

JZOS Batch Launcher

The JZOS batch launcher allows you to run Java as a regular z/OS batch job, using JCL DD statements to define input and output.

Documentation can be found here:

Installation consists of copying the load module from the Java installation into a PDS/E, and setting up a JCL PROC.

1. Allocate datasets for JZOS load modules and JCL

//jobname   JOB CLASS=A,                 
//        MSGCLASS=H,                   
//        NOTIFY=&SYSUID                
//ALLOC    EXEC PGM=IEFBR14             
//DD1      DD DISP=(NEW,CATLG),         
//        DSN=hlq.JZOS.LOADLIB,    
//        DSNTYPE=LIBRARY,              
//        SPACE=(TRK,(50,10,10)),       
//        RECFM=U,BLKSIZE=32760         
//DD2      DD DISP=(NEW,CATLG),         
//        DSN=hlq.JZOS.CNTL,        
//        SPACE=(TRK,(10,5,5)),         
//        RECFM=FB,LRECL=80,BLKSIZE=6160

2. Copy JZOS JCL and load modules from the Java installation.

This JCL copies both 31 bit and 64 bit components. EasySMF will run as either 31 bit or 64 bit, so if you have only set up one version of Java you can delete the lines referring to the other version.

//jobname  JOB CLASS=A,                   
//             MSGCLASS=H,                
//             NOTIFY=&SYSUID             
//S1  EXEC PGM=BPXBATCH,REGION=512M       
//STDENV  DD *                            
JAVA=/usr/lpp/java/J8.0                   
JAVA64=/usr/lpp/java/J8.0_64              
//STDPARM DD *                            
SH                                        
 cp $JAVA/mvstools/samples/jcl/JVMJCL80   
    "//'hlq.JZOS.CNTL(JVMJCL80)'";    
 cp $JAVA/mvstools/samples/jcl/JVMPRC80   
    "//'hlq.JZOS.CNTL(JVMPRC80)'";    
 cp -X $JAVA/mvstools/JVMLDM80            
    "//'hlq.JZOS.LOADLIB(JVMLDM80)'";
 cp $JAVA64/mvstools/samples/jcl/JVMJCL86 
    "//'hlq.JZOS.CNTL(JVMJCL86)'";    
 cp $JAVA64/mvstools/samples/jcl/JVMPRC86 
    "//'hlq.JZOS.CNTL(JVMPRC86)'";    
 cp -X $JAVA64/mvstools/JVMLDM86          
    "//'hlq.JZOS.LOADLIB(JVMLDM86)'";

3. Update the JZOS JCL

JZOS batch launcher procs are in hlq.JZOS.CNTL members JVMPRC86 and JVMPRC80.

Update the JCL to uncomment the LIBRARY parameter and point it to your JZOS LOADLIB, and uncomment the STEPLIB.

EasySMF:JE installation

1. Download EasySMF:JE and request a trial key

EasySMF:JE can be downloaded here: TSO TRANSMIT format, for installation on z/OS.

Request a 30 day trial key here: 30 Day Trial. Enter your email address at the bottom of the page to receive a trial key. The key should be delivered immediately via email. If you do not receive it within a few minutes, check your spam folder.

2. Upload installation file to z/OS

Allocate a FB 80 sequential dataset to receive the installation file.

//jobname  JOB CLASS=A,                 
//        MSGCLASS=H,                   
//        NOTIFY=&SYSUID                
//ALLOC   EXEC PGM=IEFBR14              
//DD1      DD DISP=(NEW,CATLG),         
//        DSN=hlq.EASYSMF.INSTALL.XMI,      
//        SPACE=(TRK,(300,50)),         
//        RECFM=FB,LRECL=80,BLKSIZE=6160

Upload the installation file in BINARY format to the dataset you allocated.

3. Use TSO RECEIVE to restore the installation PDS

TSO RECEIVE INDATASET('hlq.EASYSMF.INSTALL.XMI')

Dataset VENDOR.EASYSMF.VnRnMn.INSTALL from AJR on N1
Enter restore parameters or 'DELETE' or 'END' +

Hit enter to accept the default name hlq.EASYSMF.VnRnMn.INSTALL
or respond:

dataset('<your.output.dataset>')

4. Edit and run the #INSTALL job

By default, the #INSTALL job installs EASYSMF:JE into the java subdirectory in your home directory. This is typically a suitable location for initial testing and evaluation.

The #INSTALL job installs EasySMF:JE into the following directories in the destination directory:

easysmf-je-v-r-m/jar: EasySMF and related jar files
easysmf-je-v-r-m/documentation: The EasySMF javadoc jar file
easysmf-je-v-r-m/samples: Source code for EasySMF sample reports

Change the SRC parameter to point to the installation PDS. Change the DEST parameter if you want to install to a different location. Submit the job.

5. Install the EasySMF:JE key

The EasySMF:JE key is a text file that looks like:

**License:
MQ0KMjAxNS0wOS0wNA0KVGVtcG9yYXJ5IEtleQ0K
**Sig:
bBvA9pCvG145BQrvaser65geM8zaIxJsAt5XJVtwpB3Ld4TXB4LzaCFNdRgXtQQR
IGAg+KhMLyaMM66gFMsFQduE1A5AK6wWi2Z9hBBm/YOBqCW4gbw9iWzeApE09VaQ
LbFkhc6WNyv2/27VZXJ/nkAyUBzX9uyVEKb4Vc+oX0M=
**End

The format of the key is designed so that it can be easily pasted into a 3270 emulator session.

Put the key in a convenient dataset. EasySMF jobs use the EZSMFKEY DDNAME to find the key.

//EZSMFKEY DD DISP=SHR,DSN=YOUR.DATASET(EZSMFK)

6. Run IVPs and sample jobs

Four IVP jobs are provided to verify the installation and demonstrate the use of EasySMF:JE.

IVP1: This job runs a sample class installed with EasySMF to verify that the EasySMF classes can be located.
IVP2: This job runs the same class as the previous job, but it compiles and runs it from source.
IVP3: This job compiles and runs a sample SMF report. The report lists the top 10 job names by CPU time between 8:30 am and 5:30 pm for each day of the week.
IVP4: This job runs one of the sample SMF programs from the Samples jar file. It reports SMF record statistics (count, size, MB) by type and subtype.

Customize the JCL symbols in the jobs as required:

JAVAHOME: The location of your Java installation. E.g. '/usr/lpp/java/J8.0'
ESMFPATH: The location where you installed EasySMF-JE. This should be the same as DEST in the #INSTALL job e.g. './java' to for the java subdirectory under your home directory.
EZSMFKEY: A dataset containing the temporary or permanent key for EasySMF.
JAVACLS: The name of the class to run. This needs to include the Java package qualifiers and be and surrounded by triple apostrophes for correct symbol substitution. e.g. '''com/blackhillsoftware/samples/RecordCount'''
TARGET: The location to store compiled java class files. e.g. './java/target'
SMFDATA: A dataset containing SMF data.

What Next?

Investigate the EasySMF samples, and use them to develop your own reports.

Sample 1 : SMF Records by type and subtype
Sample 2 : Prime Shift Top CPU Consumers
Sample 3 : Performance Index

Installation on other platforms (Windows, Linux etc)

You can edit, complie and run Java programs on z/OS, but development is much easier using an IDE like Eclipse on a workstation. The resulting .class files can then be uploaded and run on z/OS.

A zip file containing the EasySMF components is available here:
Zip format, for use on Windows, Linux etc.

Add the contents of the jar subdirectory to the Java classpath.

You will also require ibmjzos.jar to develop on other platforms. This is not distributed with EasySMF, you will need to copy it from your z/OS Java Installation. Typically it would be located somewhere like /usr/lpp/java/J8.0/lib/ext/. Be sure to comply with IBM licensing restrictions. Add it to the Java classpath.