Attaching a debugger to a CICS JVM

To run a JVM in debug mode and allow a JPDA remote debugger to be attached, you must set some options in the JVM profile for the JVM. Customizing or creating JVM profiles and JVM properties files explains the procedure for customizing options in a JVM profile.

The specific options required for debugging are as follows:
Xdebug
This option is required to start the JVM in debug mode; that is, with the JPDA interfaces active.
Xrunjdwp=(suboption=...,suboption=...)
This option specifies the details of the connection between the debugger and the CICS JVM. These details include the TCP/IP address to be used for the connection, and the sequence in which connection occurs. Different debuggers have different connection requirements and capabilities; refer to the documentation provided with the debugger. Some typical example settings are as follows:
Xrunjdwp=(transport=dt_socket,server=y,address=9876)
This set of suboptions specifies that:
  • The standard TCP/IP socket connection mechanism is used
  • The server starts first (server=y) and waits for the debugger to attach to it
  • The CICS JVM listens on TCP/IP port 9876 for a debugger to attach to it.
The CICS JVM waits after initialization for instructions from the debugger before executing the application code.
If you’re using the Java debugger supplied with WebSphere Studio Enterprise Edition, you should specify the Xrunjdwp option in your JVM profile. In addition, in WebSphere Studio you must create a Remote Java Application definition, within the Debug Perspective, that specifies:
  • The IP address (or host name) of the z/OS system that hosts the CICS region.
  • The TCP/IP port number (called "address" in the Xrunjdwp syntax) that the CICS JVM is using. (This is the same number specified to CICS on the Xrunjdwp option.)
  • That a standard TCP/IP socket connection (Socket Attach) is to be used.
Xrunjdwp=(transport=dt_socket,address=bos.hurs.ibm.com:6789)
This set of suboptions specifies that:
  • The standard TCP/IP socket connection mechanism is used
  • Omitting the server option defaults to server=no, which means the debugger starts first and waits for the JVM to attach to it
  • The JVM attaches to a debugger that is running on a machine called bos.hurs.ibm.com on port number 6789.
After initialization the JVM waits for instructions from the debugger before executing the application code.
If your debugger is WebSphere Studio, you must specify server=y.
REUSE=NO
A JVM that has been run in debug mode is not a candidate for reuse. Set this option to NO to ensure that the JVM is discarded after the debug session.
The CICS® System Definition Guide has full information about the options available in a JVM profile.
When you set these options in a JVM profile, any CICS JVM program that uses that profile runs in debug mode (and waits for attach from, or attempts to attach to a debugger). You should therefore ensure that the JVM profile applies only to programs that you wish to debug. Remember: Instead of configuring any of the CICS-supplied sample profiles for debug, you should create a separate JVM profile specifically for debug use, and set the appropriate CICS PROGRAM resource definition to use this debug JVM profile.

For enterprise beans, you need to specify the debug JVM profile in the PROGRAM definition for the request processor program that is used by the enterprise bean. The default request processor program, which is named by the default CIRP transaction on REQUESTMODEL definitions, is DFJIIRP. To modify CICS-supplied definitions for this purpose, such as those in CSD group DFHIIOP, you have to copy the definitions to your own group first—DFHIIOP is locked and cannot be modified. However, bear in mind that if you modify the PROGRAM definition for the default request processor program to use the debug JVM profile, there is a strong risk that it will be used for programs other than those you want to debug. It is safer to set up a different PROGRAM definition to be used by the enterprise beans that you want to debug.

Errors during initialization of the debug connection (for example incorrect TCP/IP host or port values) result in messages on the JVM standard output and standard error streams. Redirecting JVM output tells you how to set the destination for these messages.

The debugger should give an indication that it has successfully attached to the CICS JVM. The initial state of the JVM (such as the identity of threads that have started, and system classes that are loaded) is visible in the debugger user interface. The JVM will have suspended execution, and the Java application in CICS (enterprise bean, CORBA object or Java program) will not yet have started. Your next action is normally to set a breakpoint at a suitable point in the Java application by specifying the full Java class name and source code line number. As the application class will not usually have been loaded at this point, the debugger indicates that activation of this breakpoint is deferred until the class is loaded. You should then let the JVM run through the CICS middleware code to the application breakpoint, at which point it suspends execution again. You can then examine loaded classes, and variables, set further breakpoints and step through code as required.

To terminate 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. This normally results in an abend and error messages on the CICS system console.

To fully enable the capabilities of a Java source code debugger, the Java code to be debugged must be compiled using the -g option on the Java compiler (javac command). Additional symbolic information is then preserved in the .class file, which is used when the debugger is attached at run time. IDEs usually support this compiler option via a user setting .