Invoking Fault Analyzer from Java dump events

The Java™ -Xdump environment switch can be used to take a TDUMP when an exception occurs and pass that TDUMP on to Fault Analyzer to generate an analysis report. For general detail about using the -Xdump settings, go to https://www.ibm.com/docs/en/sdk-java-technology/8?topic=options-xdump. This reference describes the Java™ internal events that can trigger a dump and the filters that can be applied.

The following setup is an example of using -Xdump to get a Fault Analyzer report for a NullPointerException or a SocketException:

java -Xdump:system:events=throw+catch+uncaught,filter=*NullPointerException*,opts=IEATDUMP
-Xdump:system:events=throw+catch+uncaught,filter=*SocketException*,opts=IEATDUMP
-Xdump:tool:events=throw+catch+uncaught,filter=*NullPointerException*,
       exec="tso 'idida dsn(%last) datasets(idihist(da.test.gui.hist))' "
-Xdump:tool:events=throw+catch+uncaught,filter=*SocketException*,
       exec="tso 'idida dsn(%last) datasets(idihist(da.test.gui.hist))' " Java-program-name

The 'system' dump agent with opts=IEATDUMP is used to capture a raw TDUMP, and then the 'tool' dump agent for the same event using the exec= option calls Fault Analyzer, passing the TDUMP via the dsn(%last) token.

The "exec" in the Xdump:tool options provides Java™ with a command to invoke when the requested events are triggered. Because the "exec" string needs to be double quoted and the resulting -Xdump strings are long, it can be easier if the entire sequence is provided through the STDPARM DD in the BPXBATCH job that is used to run the Java™ program.

The range suboption can be used to limit the number of dumps generated for a specific exception. In the above example, providing a range 1..4 means that dumps are only generated for four NullPointerException or SocketException throw events, and any more are ignored. This option is especially useful in cases where exceptions are caught and rethrown, but it does mean future Exceptions are not processed.

The priority suboption can be used to make sure dumps are created in a specific order. So, if a Java™ dump or Heap dump is also required, then to prevent Fault Analyzer being called on those dumps, make sure the non-TDUMPs either have lower or higher priority than BOTH the Xdump system and Xdump tool together.