Debugging

Supported Features

Supported language types:

• RPG (including RPGLE and OPM RPG)
• COBOL
• C/C++
• CL

Supported debug features:

• Debugging of batch programs
• Passing parameters to a batch program via the Debug As Batch (Prompt) action
• Setting line breakpoints
• Saving breakpoints across debug sessions
• Stepping (step into/over/return)
• Viewing variable values in the Locals view
• Monitoring expressions in the Watch view
• Displaying variable values in debug editor hover
• Debugging with the *SOURCE and *LIST views
• Debugging with the Update Production Files option

Limitations

The following features are not supported in the current release:

• Debugging of interactive programs
• Service Entry Point debug
• Code coverage

The IBM i debugger has the following limitations:

• A debug session may leave two running jobs (QPWFSERVSO and QZRCSRVS) under the debug user. These jobs will be terminated when IBM i Debug Service is stopped. The user can also manually terminate these jobs.

Debugging from IBM i Project Explorer

With a project in IBM i Project Explorer, connect to the IBM i. Under the IBM i connection, using Library List or a QSYS query under My Queries, show a program object. Two debug actions will be available as inline actions or from the popup menu: Debug As Batch and Debug as Batch (Prompt). Prompt enables the parameters to SBMJOB to be specified. Select an action to start debug.

When debug starts, the debug panel will open on the left and the source will open in the editor. From the debug panel, the following actions are available: Continue, Step Over, Step into, Step out, Restart, and Stop. In the editor, breakpoints can be set on lines in the left margin.

While debugging, the Variables view will show the variable values. In the editor, hovering over a variable will show its value.

Settings

Frequently Asked Questions

Question: Can I pass parameters to the batch program being debugged?
Answer: Use the Debug As Batch (Prompt)… inline action, change Command to start batch job to specify program parameters.

Question: Can I debug with Update Production Files set to true?
Answer: You can turn on Update Production Files by checking the Update production files option from the IBM i Debug Settings page in the debug client. Please note that this is a global setting, which affects all subsequent debug sessions. You can uncheck Update production files later when you no longer need this option.

Question: What is the JRE requirement for running the debug service?
Answer: A Java 8 JRE is required to run IBM i Debug Service. This requirement is satisfied when one of the followings is true:

• /bin/java is a link to the java command in a Java 8 installation
• The environment variable JAVA_HOME is set to a Java 8 installation

Question: How can I stop IBM i Debug Service?
Answer: You can run the following command to stop IBM i Debug Service:

QSH CMD('/QIBM/ProdData/IBMiDebugService/bin/stopDebugService.sh')

Question: What port numbers are used by the debug service?
Answer: IBM i Debug Service uses two port number: the debug daemon port (default is 8001) and the secure port (default is 8005). The secure port is used by the secure communication between the debug service and the debug client. The debug daemon port is only used to stop the debug service.

Question: How can I change the port numbers for the debug service?
Answer: For the debug daemon port, you can change the following value in file /QIBM/ProdData/IBMiDebugService/bin/DebugService.env to specify a different port number:

DBGSRV_PORT=8001

For the secure port, you need to make two changes:

• change the following value in /QIBM/ProdData/IBMiDebugService/bin/DebugService.env:

  DBGSRV_SECURED_PORT=8005

• change the Connection Port in the IBM i Debug Settings page from the debug client After the changes, the debug service must be stopped and started.

Question: How can I see the output of the debug service?
Answer: You can see the output of IBM i Debug Service from the QPRINT file at the output queue QUSRSYS/QDBGSRV. You may need to stop the debug service before inspecting the content of the QPRINT file.

Question: Can I get trace information for the debug service?
Answer: You can turn on tracing by checking the Enable tracing for Debug Adapter Protocol option in the IBM i Debug Settings page from the debug client. The trace will appear in the Debug Console.

Question: Some messages appear in the Debug Console after a debug launch. But the debug session does not come up.
Answer: A batch program under debug uses the QBATCH job queue by default. Verify whether there is another job holding the QBATCH job queue. You can terminate the batch job that is holding the QBATCH job queue, or specify a new job queue using Command to start batch job from Debug As Batch (Prompt).

Question: I am getting a message “EQAVS1007E myHost on port 8005 could not be connected” when I start a debug session.
Answer: IBM i Debug Service is not started yet. Please start it from the playbook first.

Question: The start of the debug service fails and a log file is generated under the path /QIBM/UserData/IBMIDEBUGSERVICE/QDBGSRV/.eclipse.
Answer: You can remove the whole Eclipse cache file directory under /QIBM/UserData/IBMIDEBUGSERVICE/QDBGSRV/.eclipse and restart the debug service.

Question: What diagnostic information should I collect to report a debug problem?
Answer: Please collect the following two pieces of information:

• The content of the QPRINT file under the QUSRSYS/QDBGSRV output queue. You may need to stop the debug service before inspecting the QPRINT file. If you have multiple QPRINT files, locate the one with the latest time stamp.
• Check the Enable tracing for Debug Adapter Protocol option from the IBM i Debug Settings page in the debug client. Save the trace text in the Debug Console to a file. Edit the file to remove the user password that appears under the trace statement for the launch request.

For information on using ARCAD tools, see How to use ARCAD integration with IBM i Modernization Engine for Lifecycle Integration