com.blackhillsoftware.smf.realtime (EasySMF RTI 0.9.9 API)

package com.blackhillsoftware.smf.realtime

This package provides a Java interface to the z/OS SMF Real Time Interface.

The SMF Real Time Interface allows programs to read SMF data from a SMF In Memory Resource as it is produced.

Using SmfConnection

SmfConnection is the key class in the package.

SmfConnection uses a fluent interface to define the connection. To create a SmfConnection:

Create an instance of SmfConnection.Connectable using SmfConnection.forResourceName(String) with the name of a SMF in memory resource defined to z/OS, e.g. IFASMF.MYRECS.
Set options e.g. disconnectOnStop() and onMissedData() as required.

Call connect() to connect to the resource and get the SmfConnection object.

SmfConnection implements Closeable so that it can be used in a try-with-resources block to make sure that the connection is closed when the program exits the block.

  try (SmfConnection connection = 
          SmfConnection.forResourceName("IFASMF.MYRECS")
              .disconnectOnStop()
              .connect())
  {
      for (byte[] recordData : connection)
      {
          // process recordData
      }
  }

Process the data as required, e.g. create an EasySMF SmfRecord:
```
SmfRecord smfrec = new SmfRecord(recordData);
```

SmfConnection Options

Disconnect on STOP

The SmfConnection will wait for records as long as the in memory resource is available and the connection has not been closed. Set the disconnectOnStop() option when creating the connection if you want the SmfConnection to set up a command handler to close the connection when a MVS STOP command is received. Alternatively, the connection can be closed from another thread e.g. in your own MvsCommandCallback, or after a record has been read.

Interaction with JZOS MvsCommandCallback

SmfConnection implements the disconnectOnStop function by registering a MvsCommandCallback to receive the STOP command.

You may need to set up your own call back function to respond to MVS commands. There are 3 ways to handle this:

Register your callback first, before creating the SmfConnection. The SmfConnection will pass calls to a MvsCommandCallback that was registered when it registers its own callback, or
Use the Black Hill Software z/OS Utilities CommandHandler class to set up your command handler(s). This class supports multiple command handlers in multiple classes, or
Save the existing MvsCommandCallback and call those call back functions from your own MvsCommandCallback.

Reading records

SmfConnection provides several choices for reading records:

The Iterable interface to read SMF records as a sequence of byte arrays.
The Stream interface to read SMF records as a Java stream of byte arrays. The Stream interface supports Parallel Streams for multi-threaded processing.
The SmfConnection.read() method to read single records as byte arrays.

All read methods will wait if no SMF records are currently available.

Queued Data

Multiple records can be returned from the in memory resource and queued internally. When records are queued in the SmfConnection, a record can be read immediately without waiting.

The SmfConnection.isEmpty() method tells you whether there are more records queued in the SmfConnection (not the SMF in memory resource). This can be useful if you want to process records in a batch e.g. sending via a HTTP connection, but without risking waiting if there are no records currently in the in memory resource.

Missed Data

If the Java program can't keep up with the rate that SMF data is being produced (e.g. the program waits for something else, or it is not getting enough CPU time), eventually the z/OS SMF buffer will wrap around and data will be lost.

If this happens, the default action is to throw a MissedDataException.

You can change this behavior by creating a call back function to take other action and optionally suppress the exception. The function receives a MissedDataEvent object. Set throwException(false) on the MissedDataEvent object to indicate the exception should be suppressed. The handler function can be specified using Connectable.onMissedData(Consumer) prior to calling connect().

E.g. For the first missed data events, output a message and suppress the exception. After 5 events, allow the SmfConnection to throw the exception:

 
  try (SmfConnection connection = 
            SmfConnection.forResourceName("IFASMF.MYRECS")
              .onMissedData(e -> handleMissedData(e))
              .connect())
  {
      ...
  }
  
  ...
  
  int missedCount = 0;
  void handleMissedData(MissedDataEvent e)
  {
      missedCount++;
      if (missedCount <= 5)
      {
          System.out.println("Missed Data!");
          e.throwException(false);
      }
  }

Development and Testing

The SmfConnection class provides a simulation mode to test your code on a development system e.g. a PC where the SMF in memory resources are not available.

To use the simulation mode, define the environment variable:

SIMULATE_RTI=Y

Define another environment variable specifying a file name for the in memory resource name, replacing dots with underscores e.g:

IFASMF_MYRECS=C:\Users\Andrew\SMF\testdata.smf

The data in the file needs to be complete SMF records including RDW, e.g. downloaded from z/OS using the "BINARY" and "SITE RDW" FTP options.

Class

Description

InMemoryResource

Information about an in memory resource defined to SMF.

MissedDataEvent

Class to control whether or not an exception is thrown when the z/OS SMF in memory resource wraps around.

MissedDataException

This exception indicates that the z/OS buffer for the in memory resource wrapped around and data was discarded (return code 04 reason code X'0401' from IFAMGET).

Query

Program to print SMF In Memory Resources and the record types they receive.

SmfConnection

Connect to and read from a z/OS SMF in Memory Resource (z/OS SMF Real Time Interface).

SmfConnection.Connectable

Class used to set options for the SmfConnection prior to connection to the in memory resource.

Version

Display the version from the command line.

Package com.blackhillsoftware.smf.realtime