Debugging a Java application

The JVM in CICS® supports the Java™ Platform Debugger Architecture (JPDA), which is the standard debugging mechanism provided in the Java Platform.

About this task

You can use any tool that supports JDPA to debug a Java application running in CICS. For example, you can use the Java Debugger (JDB) that is included with the Java SDK on z/OS®. To attach a JPDA remote debugger, you must set some options in the JVM profile.

IBM® provides monitoring and diagnostic tools for Java, including Health Center. IBM Health Center is available in the IBM Support Assistant Workbench. These free tools are available to download from IBM as described in the Getting Started guide for IBM Health Center.

Procedure

Add the debugging option to the JVM profile to start the JVM in debug mode:
```
-agentlib:jdwp=transport=dt_socket,server=y,address=port,suspend=n
```
Select a free port to connect to the debugger remotely.
If the JVM profile is shared by more than one JVM server, you can use a different JVM profile for debugging.
Note: The default value for suspend is y. This value suspends the JVM and waits for the remote client debugger to attach before processing continues. Specifying a value of n will prevent the JVM server from suspending.
Add these properties to the JVM profile when debugging a Liberty JVM server to avoid hot-swap complications with Liberty trace. This will also indicate to Liberty that it should operate in a debug cognizant mode:
```
-Dwas.debug.mode=true
-Dcom.ibm.websphere.ras.inject.at.transform=true 
```
Attach the debugger to the JVM.
If an error occurs during the connection, for example the port value is incorrect, messages are written to the JVM standard output and standard error streams.
Using the debugger, check the initial state of the JVM. For example, check the identity of threads that are started and system classes that are loaded.
Set a breakpoint at a suitable point in the Java application by specifying the full Java class name and source code line number. If the debugger indicates that activation of this breakpoint is deferred, it is because the class might not yet have loaded.
Let the JVM run through the CICS middleware code to the application breakpoint, at which point it suspends execution again.
Examine the source code of the loaded classes and variables and set further breakpoints to step through the code as required.
End the debug session. You can let the application run to completion, at which point the connection between the debugger and the CICS JVM closes. Some debuggers support forced termination of the JVM, which results in an abend and error messages on the CICS system console.