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.

Figure 1. Syntax

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:

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.
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.

Z Abend Investigator Java SVC dump titles

The Z Abend Investigator Java dump title depends on whether the dump is written using the HFZSNAP interface or the BPXBATCH interface.

Java HFZSNAP interface SVC dump title
history-file-name(fault-id)^^SVCDUMP(0x asid).JAVA HFZSNAP^
Note: ^ represents the non-printable character X'00'.
The following is an example of a Java HFZSNAP interface SVC dump title:
```
TESTFA1.TEMP.DA5E1SP.DAJAVAZZ.JC83201.HIST(F00027).    .SVCDUMP(0x0138).JAVA HFZSNAP.
```
Java BPXBATCH interface SVC dump title
history-file-name(fault-id)^^SVCDUMP(0x asid).JAVA IDI0162I^
Note: ^ represents the non-printable character X'00'.
The following is an example of a Java HFZSNAP interface SVC dump title:
```
TESTFA1.TEMP.DA4E1SP.DAJAVAZZ.JZJ2CO2K.HIST(F00700).   .SVCDUMP(0x00DB).JAVA IDI0162I.
```