Invoking Z Abend Investigator from a Java try-catch block

To capture the current Java™ state from a Java program, Z Abend Investigator can be invoked to create a history file fault entry, along with an associated MVS™ SVC dump.

The Z Abend Investigator history file that is used is the default history file. To use a different history file, specify it with the _HFZ_OPTS or _HFZ_OPTSFILE environment variables described in Options. The fault entry that is created can subsequently be reanalyzed using the Z Abend Investigator ISPF interface to review the Java and native code that was executing when Z Abend Investigator was called.

In order to facilitate Java dump capture, the following is required:
  • ALTER access must be granted to the Z Abend Investigator HFZ_SDUMP_ACCESS XFACILIT profile.
    Set up an XFACILIT class profile with the name HFZ_SDUMP_ACCESS (which is the same profile used for recovery fault recording SDUMP access) and provide ALTER access to the user IDs or groups for which Java dump capture is required. The following define would permit Z Abend Investigator to create Java capture SDUMPS for all users in the JDEV group, if their Java application encounters an exception.
    RDEF XFACILIT HFZ_SDUMP_ACCESS UACC(NONE)
    PERMIT HFZ_SDUMP_ACCESS CLASS(XFACILIT) ID(JDEV) ACCESS(ALTER)

    The ALTER access is to the XFACILIT HFZ_SDUMP_ACCESS profile, it is not to the actual SDUMP data sets. Z Abend Investigator uses authorized state to permit access to Java capture SDUMPs. The HFZ_SDUMP_ACCESS profile acts as a switch Z Abend Investigator can check to see if SDUMPs can be created for a given user.

  • The MVS post-dump exit HFZXTSEL must be installed. For details, see Installing the MVS post-dump exit HFZXTSEL.
  • The HFZS subsystem must be started. For details, see Using the Z Abend Investigator HFZS subsystem.

The call to Z Abend Investigator can be placed within a try-catch block, or anywhere else in your program, and is performed using the com.hcl.zai.Snap.dump method.

Read syntax diagramSkip visual syntax diagram
Syntax

>>-com.hcl.zai.Snap.dump--("--comment--");---------------------><

You can specify an optional comment character string to initialize the Z Abend Investigator fault entry user title field.

The following is an example showing how Z Abend Investigator might be called from within a Java try-catch block:
public class JavaTest {
  public static void main() {
    ...
    try {
      ...
    }
    catch() {
      ...
      com.hcl.zai.Snap.dump("Java error");  // Call Z Abend Investigator
    }
  }
}

Alternative snap dump invocation methods

There are several overloaded versions of the Java "Snap.dump" method that you can use to invoke Z Abend Investigator:

/**
  * Create a Fault Entry
  *
  * @param dumpTitle The user title to use for the Fault Entry. (non-null & non-empty).
  */
public static void dump(String dumpTitle)

/**
  * Create a Fault Entry
  *
  * @param dumpTitle The user title to use for the Fault Entry. (non-null & non-empty).
  *
  * @return The ID of the created Fault Entry, in the form <history file dataset>(<fault id>).
  * E.g. HFZ.HIST(F00001)
  *
  */
public static String dump(String dumpTitle, Throwable t)

/**
  * Create a Fault Entry.
  * (This should only be used when gathering diagnostic information requested by HCL Support.)
  *
  * @param dumpTitle The user title to use for the Fault Entry. (non-null & non-empty).
  * @param debug Specifying 'true' will enable verbose debug information.
  * Provide the output to HCL Support.
  *
  * @return The ID of the created Fault Entry, in the form <history file dataset>(<fault id>).
  * E.g. HFZ.HIST(F00001)
  */
public static String dump(String dumpTitle, Throwable e, boolean debug)

Adding the Snap class to the application class path

To facilitate calling the com.hcl.zai.Snap.dump method, the Z Abend Investigator HFZXJAVA Java library must either exist in the application program build path, or be available via the current class path.

The HFZXJAVA Java library can be obtained through the following steps:

  1. Do one of the following:
    • Copy the jar file your application directory on z/OS by using JCL similar to the following:
      //* --- Copy HFZXJAVA to an HFS directory:
      //CPYXJAVA EXEC PGM=BPXBATCH
      //STDPARM DD *
      SH cp "//'HFZ.SHFZDOC1(HFZXJAVA)'" /u/hunter2/hfzxjava.jar
      /*
      //STDOUT DD SYSOUT=*
      //STDERR DD SYSOUT=*
    • Perform binary FTP transfer of HFZ.SHFZDOC1(HFZXJAVA) to your project development directory as file HFZXJAVA.
      Note: The HFZ.SHFZDOC1(HFZXJAVA) data set and member are created as part of the Z Abend Investigator SMP/E installation and might exist with a different high-level qualifier.
  2. Do one of the following:
    1. Configure your project build path to include HFZXJAVA as an external JAR library dependency.
    2. Add the directory and file name to the current ClassPath.