Debugging ILE programs is now available inside of Visual Studio Code. We’ve added UI to make sure setting up the Debug Service to be a swift process.
After configuring the Debug Service, launching a debug session is a click of a button away. When you have active source open, a new Debug button will appear in the navigation bar. Breakpoints can be set prior to debugging, or during the debugging session.
Clicking the Debug button will display an input box which will allow the user to customise the command which 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 .
To debug a program from the Object Browser, right-click on the program object and select the Debug Program option. Like before this will also display an input box to modify the command which starts the debug job.
/QIBM/UserData/IBMiDebugService/certs by defaultdebug_service.pfxdebug_service.crtTo make use of the Debug Service, you need the following PTFs:
/QOpenSys/QIBM/ProdData/JavaVM/jdk11/64bit/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bitAfter you have installed the PTFs, the connection inside of Visual Studio Code will need to be restarted.
After connecting to a system in Code for IBM i, you can hover over the connection in the bottom status bar to check the Debugger version and status. The status will be on if both the Debug Server and Debug Service are running.
Clicking on the Debugger status will take you to the IBM i Debugger view. This view shows the status of the Debug Server and the Debug Service. It also allows to start/stop the Debug Server and manage the Debug Service.
The start/stop/restart actions are located on the right of each status. Running one of these actions will refresh the statuses once it’s done.
If the Debug Service is not correctly configured, a warning sign will appear next to it. Expanding the Debug Service node will show the cause of the issue.
The Debug Service needs a certificate to be able to be started. This is required because the Debug Service is basically a web server exposing web services through HTTPS, and encrypting the traffic on HTTPS requires a certificate. Supported formats for the certificate are PKCS12 and JKS. If Code for IBM i is used to generate the certificate, it will use the PKCS12 format.
By default, certificates are generated in /QIBM/UserData/IBMiDebugService/certs (which is the recommended location). The path to the Debug Service certificate is set in /QIBM/ProdData/IBMiDebugService/bin/DebugService.env with DEBUG_SERVICE_KEYSTORE_FILE.
If the certificate is missing, the IBM i Debugger view will show this error:
Clicking on the Setup Service Certificate button will start a process that offers to either generate a certificate or import an existing one (PKCS12 format only). Once the certificate is successfully generated or imported, two files will be found under /QIBM/UserData/IBMiDebugService/certs:
debug_service.pfx
debug_service.crt
Generating the certificates will also update the Debug Service configuration file /QIBM/ProdData/IBMiDebugService/bin/DebugService.env to set the correct path to the required JDK and save the encrypted certificate password.
If these certificates are deleted for some reason, they can be simply regenerated from the IBM i Debugger view as described above. They are used only to encrypt the traffic between the clients and Debug Service.
It also possible to regenerate the certificates by right-clicking on the Debug Service and choosing Regenerate service certificate
If the client certificate cannot be found locally or does not match the remote certificate, Code for IBM i will show a warning in the IBM i Debugger view and offer an action to import the client certificate.
Starting the Debug Service can be done from the IBM i Debugger view and requires *ALLOBJ special authority.
Clicking on the action to start the Service will first show a prompt showing SBMJOB parameters. Since the shell script that starts the service will be submitted, this lets you modify the submission parameters if needed. Only the CMD and JOB parameters are imposed.
Once the prompt is validated, the SBMJOB command will be executed and Code for IBM i will monitor its execution until the Debug Service is actually started (or fails to start).
If the Debug Service was configured from Code for IBM i (i.e the certificate was generated from Code for IBM i), then it is possible to start the Debug Service by running the same SBMJOB command that Code for IBM i uses:
SBMJOB CMD(STRQSH CMD('/QOpenSys/pkgs/bin/bash -c /QIBM/ProdData/IBMiDebugService/bin/startDebugService.sh')) JOB(DBGSVCE) JOBQ(QSYS/QUSRNOMAX) JOBD(QSYS/QSYSJOBD) USER(*CURRENT)The Debug Service depends on three ports by default:
While you can configure the ports in the Connection Settings, it is recommended the defaults are used for consistency.
As depicted in this diagram, the client (VS Code, IBM i Debug) connects to the Debug Service, which talks to the Debug Server.
STRDBGSVR. You may get an error message in VS Code if you attempt to debug when the Debug Server is not running.
This is a limitation for CL. The local variables will not show up in the Variables view for CL. You can add a local variable to the Watch view to inspect its value. The CL limitation also exists in RDi.
There is a known issue that when you start debugging from VS Code, the debugger hangs and doesn’t launch.
The fix is to check if you’ve got a prior debug job stuck in MSGW. You can do this with WRKACTJOB, or a similar command like WRKSBSJOB QBATCH.
Users should no longer face this issue as we now submit debug jobs to QSYSWRK with QSYSNOMAX.
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 greenscreen.
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/hostsYour entry might look like this:
# IP HOSTNAME192.168.0.20 MYIBMIIf 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.