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:
- Never configure for debug the JVM profiles that are involved
with the shared class cache; that is, the JVM profiles for worker
JVMs that specify CLASSCACHE=YES, and the JVM profile for the master
JVM that initializes the shared class cache. JVM debugging is not
supported for shared classes, and if you configure these JVM profiles
for debug, CICS ignores your setting. DFHJVMPC and DFHJVMCC are the
CICS-supplied sample profiles for worker and master JVMs respectively.
- Avoid configuring for debug the CICS-supplied sample JVM
profiles DFHJVMPR and DFHJVMPS, and the JVM profile DFHJVMCD for CICS-supplied
system programs. It is possible to configure these profiles for debug,
provided they have not been changed to specify CLASSCACHE=YES, but
because they are used as defaults within CICS, there is a strong risk
that they will be used for programs other than those you want to debug.
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 .