Invoking Fault Analyzer from a Java try-catch block

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

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

In order to facilitate Java™ dump capture, the following is required:

ALTER access must be granted to the Fault Analyzer IDI_SDUMP_ACCESS XFACILIT profile.
Set up an XFACILIT class profile with the name IDI_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 Fault Analyzer to create Java™ capture SDUMPS for all users in the JDEV group, if their Java™ application encounters an exception.
```
RDEF XFACILIT IDI_SDUMP_ACCESS UACC(NONE)
PERMIT IDI_SDUMP_ACCESS CLASS(XFACILIT) ID(JDEV) ACCESS(ALTER)
```
The ALTER access is to the XFACILIT IDI_SDUMP_ACCESS profile, it is not to the actual SDUMP data sets. Fault Analyzer uses authorized state to permit access to Java™ capture SDUMPs. The IDI_SDUMP_ACCESS profile acts as a switch Fault Analyzer can check to see if SDUMPs can be created for a given user.
The MVS™ post-dump exit IDIXTSEL must be installed. For details, see Installing the MVS post-dump exit IDIXTSEL.
The IDIS subsystem must be started. For details, see Using the Fault Analyzer IDIS subsystem.

The call to Fault Analyzer can be placed within a try-catch block, or anywhere else in your program, and is performed using the com.ibm.faultanalyzer.Snap.dump method.

Figure 1. Syntax

You can specify an optional comment character string to initialize the Fault Analyzer fault entry user title field.

The following is an example showing how Fault Analyzer might be called from within a Java™ try-catch block:

public class JavaTest {
  public static void main() {
    ...
    try {
      ...
    }
    catch() {
      ...
      com.ibm.faultanalyzer.Snap.dump("Java error");  // Call Fault Analyzer
    }
  }
}

Alternative snap dump invocation methods

There are several overloaded versions of the Java™ "Snap.dump" method that you can use to invoke Fault Analyzer:

/**
  * 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. IDI.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 IBM 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 IBM Support.
  *
  * @return The ID of the created Fault Entry, in the form <history file dataset>(<fault id>).
  * E.g. IDI.HIST(F00001)
  */
public static String dump(String dumpTitle, Throwable e, boolean debug)

Adding the Snap class to the application class path

In the following, IDIXJAxx refers to:

IDIXJAVA if using a version of Java earlier than version 11.
IDIXJA11 if using Java version 11 or later.

To facilitate calling the com.ibm.faultanalyzer.Snap.dump method, the Fault Analyzer IDIXJAxx Java™ library must either exist in the application program build path, or be available via the current class path.

The IDIXJAxx Java™ library can be obtained through the following steps:

If using a version of Java JVM earlier than version 11:

Do one of the following:
- Copy the jar file your application directory on z/OS by using JCL similar to the following:
```
//* --- Copy IDIXJAVA to an HFS directory:
//CPYXJAVA EXEC PGM=BPXBATCH
//STDPARM DD *
SH cp "//'IDI.SIDIDOC1(IDIXJAVA)'" /u/hunter2/idixjava.jar
/*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
```
- Perform binary FTP transfer of IDI.SIDIDOC1(IDIXJAVA) to your project development directory as file IDIXJAVA.
  Note: The IDI.SIDIDOC1(IDIXJAVA) data set and member are created as part of the Fault Analyzer 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 IDIXJAVA as an external JAR library dependency.
2. Add the directory and file name to the current ClassPath.

If using Java JVM version 11 or later:

Do one of the following:
- Copy the jar file your application directory on z/OS by using JCL similar to the following:
```
//* --- Copy IDIXJA11 to an HFS directory:
//CPYXJAVA EXEC PGM=BPXBATCH
//STDPARM DD *
SH cp "//'IDI.SIDIDOC1(IDIXJA11)'" /u/hunter2/idixja11.jar
/*
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
```
- Perform binary FTP transfer of IDI.SIDIDOC1(IDIXJA11) to your project development directory as file IDIXJA11.
  Note: The IDI.SIDIDOC1(IDIXJA11) data set and member are created as part of the Fault Analyzer 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 IDIXJA11 as an external JAR library dependency.
2. Add the directory and file name to the current ClassPath.

Fault Analyzer Java SVC dump titles

The Fault Analyzer Java dump title depends on whether the dump is written using the IDISNAP interface or the BPXBATCH interface.

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