System debugging for IBM Technology for Java

These instructions present several options for debugging IBM® Technology for Java™ JVMs.

Interactive debugging from the CL command line

The simplest way to start the system debugger is with the OPTION(*DEBUG) parameter of the JAVA CL command. For example:
 > JAVA CLASS(Hello) OPTION(*DEBUG)

Enabling debug for the IBM Technology for Java JVM

In order to debug an IBM Technology for Java JVM job from another job, the JVM must be started with debug enabled. Java debug is managed by a debug agent. Starting this agent during JVM startup is the key to successfully debugging Java code. Once the JVM is successfully started with the debug agent, the JVM may be debugged using either the Start Service Job (STRSRVJOB) and Start Debug (STRDBG) commands or from the IBM i Debugger graphical user interface. The following sections describe various ways to start the debug agent. In each case the purpose of a parameter or environment variable is to indicate that the Java debug agent should be started. These descriptions start with the simplest situations and progress to more complicated ones.
Note:
  • The debug agent does not suspend the JVM prior to entering the main method. For short-running programs or for debugging the main method, additional Java code may be needed in order to stop the JVM. One way to do this is with a timed wait-loop. Another way is to read from standard input.
  • If debug is attempted on a JVM which does not have the debug agent enabled, a JVAB307 diagnostic message is sent to the job log of both the JVM job and the servicing job. The message text identifies the JVM job that does not have debug enabled. This message indicates that the JVM must be restarted in order to be successfully debugged. It is not possible to enable debug after the JVM is started.

Enabling Java debug from CL

To enable Java debug from CL, add the AGTPGM(D9TI) parameter to the JAVA CL command. For example:
> JAVA CLASS(Hello) AGTPGM(D9TI)

Enabling Java debug from Qshell or the PASE terminal

To enable Java debug from Qshell (QSH) or the PASE terminal (QP2TERM), add the -debug parameter in the java invocation. For example: 
> java -debug Hello
Using the -debug parameter is a simplest way to start the debug agent. It is the same as adding the -agentlib:d9ti parameter. The following will also start the debug agent:
> java -agentlib:d9ti Hello

Enabling Java debug for a batch job JVM

If the batch job JVM is started with the Submit Job (SBMJOB) CL command, then the AGTPGM(D9TI) parameter may be added to the JAVA CL command. For example, the following will start the batch job JVM with a debug agent:
> SBMJOB CMD(JAVA CLASS(HELLO) AGTPGM(D9TI))
        CPYENVVAR(*YES) ALWMLTTHD(*YES)
If the batch job is started in some other way, then the JAVA_TOOL_OPTIONS environment variable may be used to start the debug agent. The JAVA_TOOL_OPTIONS environment variable is automatically queried by the JVM during startup. If it is set to -debug or -agentlib:d9ti, then the debug agent will be started for the JVM. For example, one of the following may be used to set the environment variable:
> ADDENVVAR ENVVAR(JAVA_TOOL_OPTIONS) VALUE('-debug')
> ADDENVVAR ENVVAR(JAVA_TOOL_OPTIONS) VALUE('-agentlib:d9ti')
If the batch job does not automatically inherit all environment variables, then the JAVA_TOOL_OPTIONS environment variable will need to be set system-wide. For example:
> ADDENVVAR ENVVAR(JAVA_TOOL_OPTIONS) VALUE('-debug') LEVEL(*SYS)
Note: When you set the JAVA_TOOL_OPTIONS environment variable system-wide, all IBM Technology for Java JVMs started on the system are started with debug enabled. This may result in a significant performance degradation.

Enabling Java debug for a JVM created with the Java Invocation API

When using the JNI_CreateJavaVM API to create a JVM, or when calling a Java method from RPG using the EXTPROC(*JAVA) support, you can enable debug using any one of the following methods:
  • Set the JAVA_TOOL_OPTIONS environment variable to -debug.
  • Set the JAVA_TOOL_OPTIONS environment variable to -agentlib:d9ti.
  • Add the -debug parameter to the options parameter list passed to the JNI_CreateJavaVM API.
  • Add the -agentlib:d9ti parameter to the options parameter list passed to the JNI_CreateJavaVM API.
  • Add "-debug" or "-agentlib:d9ti" to the QIBM_RPG_JAVA_OPTIONS environment variable if you are starting the JVM by calling a Java method from RPG.

Debugging must be done from another job.

In addition, in order to see the Java source code for the classes being debugged, the DEBUGSOURCEPATH environment variable may need to be set to the base directory location of the Java source code.

Starting the IBM Technology for Java JVM from the IBM i Debugger graphical user interface

In order to start an IBM Technology for Java JVM from the IBM i Debugger graphical user interface, the JAVA_HOME environment variable must be set when starting the JVM job. You can set this environment variable using the Initialization Command display when starting the JVM. This display is located in the Start Debug window of the IBM i Debugger interface.

For example, in order to start a 32-bit JDK 6.0 JVM, add the following to the Initialization Command display: 
ADDENVVAR ENVVAR(JAVA_HOME) VALUE('/QOpenSys/QIBM/ProdData/JavaVM/jdk60/32bit')
Note: Watch points for local variables are not supported in the IBM Technology for Java JVM. The System Debug implementation for the IBM Technology for Java JVM uses JVMTI, which does not provide watch point capability for local variables.