EasySMF:JE 2.2.1 API

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.2.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
0Smf0RecordIPL
2Smf2RecordDump Header
3Smf3RecordDump Trailer
6Smf6RecordExternal Writer, JES2 Output Writer, PSF, IP Printway
7Smf7RecordData Lost
8Smf8RecordI/O Configuration
10Smf10RecordAllocation Recovery
11Smf11RecordVary Offline
14Smf14RecordRead Dataset
15Smf15RecordWrite Dataset
16Smf16RecordDFSORT Statistics
17Smf17RecordScratch Dataset
18Smf18RecordRename Dataset
19Smf19RecordDASD Volume
21Smf21RecordErrors by Volume
23Smf23RecordSMF Status
30Smf30RecordJob Accounting
41Smf41RecordVLF Statistics
42Smf42RecordDFSMS Statistics
60Smf60RecordVVDS Update
61Smf61RecordICF Define
62Smf62RecordVSAM Open
64Smf64RecordVSAM Status
65Smf65RecordICF Delete
66Smf66RecordICF Alter
70Smf70RecordRMF Processor Activity
71Smf71RecordRMF Paging Activity
72Smf72RecordRMF Workload Activity
73Smf73RecordRMF Channel Path Activity
74Smf74RecordRMF Various Resources
75Smf75RecordRMF Page Dataset Activity
76Smf76RecordRMF Trace Activity
77Smf77RecordRMF Enqueue Activity
78Smf78RecordRMF Virtual Storage & I/O Queuing
79Smf79RecordRMF Monitor II
88Smf88RecordSystem Logger
89Smf89RecordUsage Data
92Smf92RecordFilesystem Activity
98Smf98RecordHFTS Statistics
100Smf100RecordDB2 Statistics
101Smf101RecordDB2 Accounting
110Smf110RecordCICS Statistics
121Smf121RecordJava Runtime Performance
Modules
Module
Description