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.
- 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.
You can specify an optional comment character string to initialize the Z Abend Investigator fault entry user title field.
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.
- 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 HFZXJAVA as an external JAR library dependency.
- Add the directory and file name to the current ClassPath.
Z Abend Investigator 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 IDISNAP interface SVC dump title:TESTFA1.TEMP.DA4E1SP.DAJAVAZZ.JZJ2CO2K.HIST(F00700). .SVCDUMP(0x00DB).JAVA IDI0162I.