After configuring the Debug Service, launching a debug session is a click of a button away. To start a batch debug session, right-click on a program object from the Object Browser and select the Start Debugging > Debug as Batch action.
Debugging IBM i programs is now available inside of Visual Studio Code.
Supported language types:
Supported batch debug features:
Supported Service Entry Point (SEP) debug features:
The following features are not supported in the current release:
After configuring the Debug Service, launching a debug session is a click of a button away. To start a batch debug session, right-click on a program object from the Object Browser and select the Start Debugging > Debug as Batch action.
Selecting the Debug action will display an input box which allows the user to customise the command that starts the debug job. This allows the developer to pass in parameters, or call another program to launch the debug session.
After the debug session has started, every session will break on entry. You can read more about the debugging UI on the Debug actions section on the Visual Studio Code documentation .
The debug source will be opened in the editor area. A floating Debug panel which contains the common debug actions (e.g. continue, step over, stop, etc) will appear at the top. Breakpoints can be set prior to debugging, or during the debugging session. You can see the value of a local variable in the Variables view. You can also hover over a variable in the debug editor to show its value. A monitored expression can be added to the Watch view.
Service Entry Point (SEP) can be set using the Set Service Entry Point popup menu action from the Object Browser. SEP can also be set using the Create Service Entry Point toolbar action from the Service Entry Points view in the Run and Debug side bar. The action will prompt for the service entry point location. The service entry point location can be in a short format which includes the library name and program name (e.g. MY_LIB/MY_PGM
), or in a long format which also includes the program type, module name and procedure name (e.g. MY_LIB/MY_PGM *PGM/MY_MOD/MY_PROC
). The supported program types are *PGM
and *SRVPGM
.
The following settings are available from the Debugger tab of the IBM i: Connection Settings page. The page can be accessed from the Command Palette.
Debug port: The secure debug port.
SEP debug port: The Service Entry Point daemon port.
Update production files: Enable updating of production files during debugging.
Debug trace: Enable tracing for Debug Adapter Protocol.
The debug port and SEP debug port are specified in the DebugService.env file on the host.
STRDBGSVR
requirementThe Debug Service that is started depends on the traditional Debug Server.
If you receive this message, do as it says. Simply start the Debug Server with STRDBGSVR
from a green screen.
If you are getting a self-signed certificate error or a certificate signature failure when starting a batch debug session or setting a SEP, please use the following steps for diagnostics:
Find out the certificate location on the client machine
Turn on Debug trace (see details in FAQ entry “Can I get trace information for the debug service?” )
Inspect the “Connection settings” line in the Debug Console when starting a batch debug session or setting a SEP.
The “capath” field under “Connection Settings” contains the fully qualified path of the client certificate.
If the “capath” field is undefined, update your Code for IBM i extension to a newer level; otherwise continue with the next step.
Inspect the TrustStore and debug_service.crt files on the host
When you use Navigator to generate the debug service trust store, you will get the following two files on the host:
/QIBM/UserData/IBMIDEBUGSERVICE/TrustStore
/QIBM/UserData/IBMIDEBUGSERVICE/certs/debug_service.crt
Verify that the debug_service.crt file has the same contents as the certificate on the client machine, which is indicated by the “capath” value in the previous step. Both .crt files are text files. You can open a .crt file in a text editor to inspect its contents. If the certificate on the client machine is different from the debug_service.crt file on the host, you can remove the certificate on the client machine. Code for IBM i will download the client certificate again upon the next connection to the host.
It is always recommended you use a hostname in the connection settings to make use of the debugger.
Error that is shown when connecting to the debugger if connecting using an IP address.
This error occurs when the hostname used to connect to the debugger (which might be the IP address that was configured in the connection settings) is not the same as the host name created as part of the certificate.
If you are using a system that doesn’t have a host name (for example YOURSYSTEM
, or pub400.com
), then an entry should be added to your device’s ‘hosts’ file. This entry should be the same on all devices in your network to ensure that everyone is using the same hostname.
c:\Windows\System32\Drivers\etc\hosts
/etc/hosts
Your entry might look like this:
# IP HOSTNAME192.168.0.20 MYIBMI
If you find that you’ve added your local hostname entry and the error is still occurring, then you may need to delete the existing certificates from /QIBM/ProdData/IBMiDebugService/bin/certs
on the IFS and generate them again in the Walkthrough.
Question: Can I pass parameters to the batch program being debugged?
Answer: Use the Debug As Batch action, change Command used to start debugging 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 setting from the Debugger tab of Connection Settings. The Connection Settings page can be opened from View > Command Palette… > IBM i: Connection Settings. Please note that this setting applies to all debug sessions for the same connection.
Question: I am not able to set a line breakpoint when debugging a LISTING source.
Answer: Please check the following settings in the Settings page: Features > Debug > Allow Breakpoints Everywhere > Allow setting breakpoints in any file
Question: What is the JRE requirement for running the debug service?
Answer: A Java 11 JRE is required to run IBM i Debug Service on IBM i below 7.6. A Java 17 JRE is required to run IBM i Debug Service on IBM i 7.6. You can use the JAVA_HOME environment variable to specify a runtime JRE. If JAVA_HOME is not set, the following runtime JREs will be used:
/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit (IBM i below 7.6) /QOpenSys/QIBM/ProdData/JavaVM/jdk17/64bit (IBM i 7.6)
Question: How can I start IBM i Debug Service?
Answer: You can start IBM i Debug Service using one of the following solutions:
Using the Navigator
Using the IBM i Debugger view in the client
Running the following command from the host:
QSH CMD(‘/QIBM/ProdData/IBMiDebugService/bin/startDebugService.sh’)
Question: How can I stop IBM i Debug Service?
Answer: You can stop IBM i Debug Service using one of the following solutions:
QSH CMD(‘/QIBM/ProdData/IBMiDebugService/bin/stopDebugService.sh’)
Question: What port numbers are used by the debug service?
Answer: IBM i Debug Service uses three port numbers: the debug daemon port (default is 8001), the secure debug port (default is 8005) and the service entry point daemon port (default is 8008). The secure debug 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. The service entry point daemon port is used for service entry point communication.
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 debug port, you can change the following value in /QIBM/ProdData/IBMiDebugService/bin/DebugService.env to specify a different port number:
DBGSRV_SECURED_PORT=8005
For the service entry point daemon port, you can change the following value in /QIBM/ProdData/IBMiDebugService/bin/DebugService.env to specify a different port number:
DBGSRV_SEP_DAEMON_PORT=8008
You need to restart the debug service after changing a port number.
Question: How can I see the output of the debug service?
Answer: You can see the output of IBM i Debug Service from the log file under the following path on the host machine:
/QIBM/UserData/IBMIDEBUGSERVICE/DebugService_log.txt
Question: Can I get trace information for the debug service?
Answer: You can turn on tracing by checking the Debug trace setting from the Debugger tab of Connection Settings. The Connection Settings page can be opened from View > Command Palette… > IBM i: Connection Settings. Debug trace will appear in the Debug Console.
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. You need to start debug service before starting a debug session.
Question: I am seeing a message “Your debug server version is not up to date. IBM i Debug Service requires a host PTF update.”.
Answer: IBM i Debug Service depends on the following debug server PTFs for strong password encryption. You need to load one of the PTFs below or a superseded PTF.
Question: I do not have the QDBGSRV user profile after installing the debug service on IBM i 7.5.
Answer: The debug service PTFs on 7.3/7.4/7.5 are update installs. An update install depends on a previous installation of the debug service PTF. The update install does not create the QDBGSRV user profile. If you have not installed debug service before, please install the v1 debug service PTF first, and then update the debug service PTF to the next levels.
Question: I am getting the error that the startDebugServiceNavigator.log file cannot be created when starting debug service.
Answer: You can use the “DSPAUT OBJ(‘ifs_path’)” command to verify the authority of the following IFS folders:
/QIBM /QIBM/UserData /QIBM/UserData/IBMiDebugService
You should have *PUBLIC *RX authority on /QIBM and /QIBM/UserData, and *PUBLIC *RWX authority on /QIBM/UserData/IBMiDebugService.
Question: How can I set a Service Entry Point on a procedure?
Answer: Select the Set Service Entry Point action on the target program or service program. In the service entry point location prompt, change the last part of the entry field value “/*ALL/*ALL” to specify the module name and procedure name.
Question: What happens to the Service Entry Points after I disconnect from the current connection?
Answer: The Service Entry Points are removed from the debug client after the connection is terminated. However, the SEPs are still saved in the running host debug service job. The SEPs will be restored in the client if you connect to the same host again.
Question: Service entry point without a condition works for me but conditional service entry point does not work. The program appears to be hung from a 5250 session when a conditional service entry point is hit.
Answer: It may be an authority issue with your debug user profile. Your debug user profile need to have *USE authority to the profile that owns the QB5ROUTER job and also its job description. Suppose the owner of the QB5ROUTER job is USR1 and your debug user profile is USR2, and the job description of the USR1 profile is QGPL/USR1, you can use the following commands from a terminal session to grant additional authority to your debug user profile:
GRTOBJAUT OBJ(QGPL/USR1) OBJTYPE(*ALL) USER(USR2) AUT(*USE)
GRTOBJAUT OBJ(USR1) OBJTYPE(*USRPRF) USER(USR2) AUT(*USE)
You need to restart the debug service and the debug router (QB5ROUTER) after these changes.
Question: I started the second debug session, but it does not come up.
Answer: The debug client can support multiple debug sessions, but the IDE has a limitation that the new debug session does not automatically take focus, if you already have an existing debug session. You can select the new debug session from the drop down list of the Debug toolbar, or from the Call Stack view. The source of the new debug session will appear in a debug editor after the debug session is selected.
Question: I am seeing a Password Request dialog with message “The extension IBM: ibmidebug is requesting connection data.”
Answer: When the Service Entry Points view is populated, it connects to the running debug service to retrieve the current set of SEPs. This operation requires the user password. If you select Allow, the IBM i Developer extension will allow the IBM i Debug extension to access the user password in its secret store.
Question: What diagnostic information should I collect to report a debug problem?
Answer: Please collect the following diagnostic information: