EasySMF:JE provides Java classes to work with z/OS SMF data. The classes are designed to provide a consistent interface to SMF data across different SMF record types.

Maven Dependency

Define the Black Hill Software repository and add the dependency to your POM:

 
<repositories>
    <repository>
        <id>black-hill-software</id>
        <name>Black Hill Software Repository</name>
        <url>https://repository.blackhillsoftware.com/public</url>
    </repository>
</repositories>
	
<dependencies>
    <dependency>
        <groupId>com.blackhillsoftware.smf</groupId>
        <artifactId>easysmf-je</artifactId>
        <version>2.3.1</version>
    </dependency>
</dependencies>

Reading SMF records

Use the SmfRecordReader class to read SMF records from a DDNAME, an input file or a stream. The SmfRecordReader can return all records, or select specific types and subtypes using the SmfRecordReader.include(int) methods.

Processing records

Process records by iterating over the reader:


for (SmfRecord record : reader)
{
   // process record
}

or by using Java Streams:


long recordcount = reader.stream()
    .filter(r -> 
            r.smfTime().isAfter(LocalTime.of(9, 00)) 
         && r.smfTime().isBefore(LocalTime.of(17, 00)))
    .count();

Extracting record sections

SMF records are typically made up of multiple sections. Methods are provided to extract the sections from the record. To retrieve a section, convert the SMF record to the specialized type and call the method.

 
reader.include(30);
for (SmfRecord record : reader)
{
   Smf30Record r30 = Smf30Record.from(record);
   IdentificationSection idSection = r30.identificationSection();
   List<ExcpSection> = r30.excpSections();
}

Typically, if a section is described by a SMF triplet (offset, length, count) then the sections will be returned in a List of the section type e.g. Smf30Record.excpSections(). The list may be empty if there are no sections in this record i.e. the count is zero.

If it is documented that only one of the section type can occur, a method may return the single section e.g. Smf30Record.identificationSection(). If the section might not be present that method will return null if the section does not exist e.g. Smf30Record.completionSection().

In a few cases classes provide 2 methods, one that returns 1 section or null and another that returns a List of 1 or 0 items. The List allows you to iterate over the section (iterating 0 times if it is not present) instead of checking for null, which can give slightly neater code.

Data Conversion

The API aims to provide a consistent interface across different types and sections, and converts values to standard Java types for simple programming.

Dates and Times

Dates and times are converted to java.time classes. Java.time represents dates and times with a precision of 1 nanosecond, which is sufficient for most SMF fields.

Times representing a duration e.g. CPU or elapsed time are converted to Duration.
Durations are also provided as Java double with the value in seconds for simple calculations.
Dates and times of day are converted to LocalDate, LocalTime, LocalDateTime, LocalDateTime, or ZonedDateTime depending on exactly what information is in the field.

Typically, times based on UTC(GMT) are converted to ZonedDateTime with ZoneOffset.UTC. Other dates and times are converted to LocalDate/Times.

Java has time zone rules so it is possible to apply a ZoneId to a LocalDateTime and perform date aware conversions between time zones. See: LocalDateTime.atZone(java.time.ZoneId)

The raw numeric value of date and time fields is also provided.

Numeric Values

1, 2 and 3 byte integer values and 4 byte signed integer values are converted to int (32 bit signed) values.
4-7 byte integer values and 8 byte signed values are converted to long (64 bit signed).
8 byte unsigned values are available as both long (64 bit signed) and as a BigInteger.
The long value may provide better performance if the value will not exceed the maximum value for a Java long. If a value does exceed the maximum value (i.e. the high order bit is set) an exception will be thrown. If the field value might exceed the maximum value for a long, use the BigInteger version.
Integer values greater than 8 bytes are converted to BigInteger.
Floating point values are converted to Java double.

String Values

EBCDIC and UTF8 string/character values are converted to Java String.

Flags

Flag bits within a byte are converted to a boolean value indicating whether the bit is set.

Data Type Errors

If you discover a field with an incorrect data type, please report it as a problem instead of programming around it. Changing the data type later will require modifications to any existing programs that refer to the field.

License Key

EasySMF:JE requires a license key to use.

You can obtain a temporary trial key from https://www.blackhillsoftware.com/30-day-trial/.

z/OS

Add the license key to your JCL:

//EZSMFKEY DD *
**License:
MQ0KMjAyMy0wMy0xNg0KVGVtcG9yYXJ5IEtleQ0K
**Sig:
FuHoSh3wb6CnZkAkQbgErJnMebKA33g3Ytl8zoKNpZ+ypbcJceVGbCRIfT/uqlR3
n3GlhkMTV4ZaQY4JI2/QbolvCmE7D2ZBFx3d7EYajyaR/dPw0bXkwTEED73i8f7/
n3O4eqja9O0ATxQUheTF0Gjnd/RzKcL5S7dyE6cEpPw=
**End

Windows/Linux

Save the license key to a file, and set an environment variable to point to the file.

Linux

export EASYSMFKEY=/home/andrew/easysmfkey.txt

Windows

set EASYSMFKEY=C:\Users\Andrew\Documents\easysmfkey.txt

Or
Settings -> Edit environment variables for your account...
and add the environment variable.

SMF Record Types

EasySMF provides classes for the following record types:

SMF Record Types
0	`Smf0Record`	IPL
2	`Smf2Record`	Dump Header
3	`Smf3Record`	Dump Trailer
6	`Smf6Record`	External Writer, JES2 Output Writer, PSF, IP Printway
7	`Smf7Record`	Data Lost
8	`Smf8Record`	I/O Configuration
10	`Smf10Record`	Allocation Recovery
11	`Smf11Record`	Vary Offline
14	`Smf14Record`	Read Dataset
15	`Smf15Record`	Write Dataset
16	`Smf16Record`	DFSORT Statistics
17	`Smf17Record`	Scratch Dataset
18	`Smf18Record`	Rename Dataset
19	`Smf19Record`	DASD Volume
21	`Smf21Record`	Errors by Volume
23	`Smf23Record`	SMF Status
30	`Smf30Record`	Job Accounting
41	`Smf41Record`	VLF Statistics
42	`Smf42Record`	DFSMS Statistics
60	`Smf60Record`	VVDS Update
61	`Smf61Record`	ICF Define
62	`Smf62Record`	VSAM Open
64	`Smf64Record`	VSAM Status
65	`Smf65Record`	ICF Delete
66	`Smf66Record`	ICF Alter
70	`Smf70Record`	RMF Processor Activity
71	`Smf71Record`	RMF Paging Activity
72	`Smf72Record`	RMF Workload Activity
73	`Smf73Record`	RMF Channel Path Activity
74	`Smf74Record`	RMF Various Resources
75	`Smf75Record`	RMF Page Dataset Activity
76	`Smf76Record`	RMF Trace Activity
77	`Smf77Record`	RMF Enqueue Activity
78	`Smf78Record`	RMF Virtual Storage & I/O Queuing
79	`Smf79Record`	RMF Monitor II
88	`Smf88Record`	System Logger
89	`Smf89Record`	Usage Data
92	`Smf92Record`	Filesystem Activity
98	`Smf98Record`	HFTS Statistics
100	`Smf100Record`	DB2 Statistics
101	`Smf101Record`	DB2 Accounting
110	`Smf110Record`	CICS Statistics
121	`Smf121Record`	Java Runtime Performance

Modules

Module

Description

com.blackhillsoftware.easysmf.je

EasySMF:JE 2.3.1 API