GitHubContribute in GitHub: Edit online

Running a Debug session from Z Open Editor

To start a Debug session in VS Code, you need to first install the two IBM Z Open Debug extensions.

When you run the playbook initialize-local-files.yaml, it prints three JSON properties that you need to add to your VS Code user settings. Replace 10.x.x.x with your the address of your instance:

"zopendebug.connection.connectionName": "10.x.x.x",
"zopendebug.connection.connectionPort": 8192,
"zopendebug.connection.userName": "ibmuser",

The z/OS development and test stock image runs the REST services that are required by the Debug client by using a self-signed SSL certificate. You need to enable VS Code to accept such a certificate as valid. You can restart VS Code by using command line with a special parameter, for example:

code --ignore-certificate-errors /User/username/zopeneditor-sample

The initialize-local-files.yaml also creates VS Code launches that provide the IP address and special ports that are needed to connect to a debug session that is running on z/OS. Move the generated file ~/.zowe/launch.json to the .zowe folder in your Git repository with the following command:

mv ~/.zowe/launch.json ../.vscode/launch.json

If you did not run the Ansible script, you can create the launch manually by editing and copying the file ansible/templates/debug-launch.j2 and replacing values for username, IP address, and port (default: 8194).

The dbb-sam-build.yml Ansible playbook that you run earlier also generates and copied a JCL to the data set IBMUSER.SAMPLE.JCL called DEBUG that can be used for building and running a debug session of the SAM1 COBOL application on z/OS.

Similarly, you can manually create the JCL by filling in the variables in ansible/templates/DEBUG.j2 with the values list in the file ansible/inventories/host_vars/devtest1.yml.

When you have the VS Code user settings .vscode/launch.json, and IBMUSER.SAMPLE.JCL(DEBUG) in place, you can create a Debug Profile in VS Code with the cmd-shift-p (Mac) or ctrl-shift-p (Windows) command, and type or select Debug: IBM Z Open Debug Profiles view.

  1. Close the Welcome screen, click Create Profile, and select the Batch option. A form with the connection details based on your user settings is displayed.

  2. Check that a blue checkmark icon appears next to the form with the label Connected.

    Note: If the checkmark icon does not appear, make sure that you start VS Code with the --ignore-certificate-errors parameter, that you are connected to your VPN, and that the VS Code user settings are entered correctly.

  3. Click Create. A new profile in a table with a slider button in the Activate column is displayed.

  4. Click the slider and wait until you see Active and a green checkmark next to the entry in the Connection column.

You can now start and connect to a z/OS Debug session.

To start a Debug session on z/OS, you can use the DEBUG JCL that is generated and copied to IBMUSER.SAMPLE.JCL(DEBUG) by the dbb-sam-build.yml Ansible playbook, or start the session manually.

  1. Switch to the Zowe Explorer activity group in VS Code.

  2. In the Data Sets view, repeat the steps from earlier to get the data sets from IBMUSER.


  4. Right-click the file DEBUG and select Submit Job. A notification displays the ID of the new job.

  5. Click the ID to show the job in the Zowe Explorer Jobs view and open its spool files. The job should remain in Active state.

Then, use the VS Code Debug activity group to connect to the Debug session.

  1. From Run and Debug, select List parked IBM Z Open Debug sessions and click Play.

  2. Enter the password of the user IBMUSER. The default value is sys1.

  3. The Debug Console view is displayed in VS Code that shows you whether it finds a parked debug session. It shows a session ID and a state of Parked.

  4. If a parked session is not available, run the launch again. If it is not successful, investigate the Job's spool files again to see what might be wrong.

  5. When you see a parked session, select Connect to parked IBM Z Open Debug session from Run and Debug, and click Play.

  6. Enter the password again.

  7. The expanded source gets opened in a VS Code editor tab with the first line highlighted.

  8. The session is paused and you can now set breakpoints. For example, set a breakpoint in line 442 in paragraph "100-PROCESS-TRANSACTIONS" by clicking next to the line number until a red dot appears.

  9. When you see a hovering toolbar, you can click Continue to jump the toolbar to the breakpoint.

  10. Use the Variables view to inspect the values of Locals and Registers.

  11. Click Step over and Step into to step through the program.

  12. To finish the session, press Continue until the program ends, or click Stop.

Check the Zowe Explorer jobs view to confirm that the Debug session has ended. You can edit the program now, run a User Build, or build Ansible playbook and Debug again.