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.
- 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.
You can specify an optional comment character string to initialize the Fault Analyzer fault entry user title field.
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
- 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.
- 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.
- Copy the jar file your application directory on z/OS by using JCL similar to the
following:
- Do one of the following:
- Configure your project build path to include IDIXJAVA as an external JAR library dependency.
- Add the directory and file name to the current ClassPath.
- Do one of the following:
- 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.
- Copy the jar file your application directory on z/OS by using JCL similar to the
following:
- Do one of the following:
- Configure your project build path to include IDIXJA11 as an external JAR library dependency.
- Add the directory and file name to the current ClassPath.
- Do one of the following:
Fault Analyzer Java SVC dump titles
- Java IDISNAP interface SVC dump
title
history-file-name(fault-id)^^SVCDUMP(0x asid).JAVA IDISNAP^
Note:^
represents the non-printable characterX'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 characterX'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.