Configuring Workbench Debug

You can create the following debug configuration.

Creating Workbench batch debug configuration
Creating Workbench CICS debug configuration

Before you begin

Install Workbench Explorer if you want to use the Workbench Debugger.
Create the connection profile to connect with HCI before you begin debugging.
Install Workbench Debugger on your mainframe.
Set up the workspace in VS code.

Creating Workbench batch debug configuration

You can create the Workbench batch debug configuration manually and automatically.

To create a Workbench batch debug configuration for a Workspace manually

In the left navigation panel of the VS code, click Run and Debug ().
On the Run and Debug panel, click create a launch.json file.
Select Workbench Batch from the list displayed.

This creates a launch.json file under the .vscode folder.
Open the launch.json file from the workspace .vscode directory, and click Add Configuration. This creates a new launch configuration.
The following property fields are displayed. These fields are mandatory fields. Enter the values in the required fields.
{
   "type": "workbench-batch",
   "request": "launch",
   "name": "Batch Launch",
   "hciConnectionName": "",
   "jclDatasetMember": "",
   "jobName": "",
   "steps": [
       {
           "step": "",
           "program": "",
           "DB2": false,
           "IMS": false
       }
    ]
}
- type and request: Identifies this configuration as a launch configuration for Workbench. Do not modify these fields.
- name: Specifies the name of the launch configuration as it should appear in the VS Code Run and Debug dropdown.
- hciConnectionName: Specifies the name of the HCI connection profile that defines the connection to the mainframe where the job is to be debugged.
- jclDatasetMember: Specifies the data set name or member containing the JCL to run the program. For a PDS member, specify this as HLQ.ABC.DEF(MEMBER). For a sequential data set, specify simply as HLQ.ABC.DEF.
- jobName: Specifies the job name for the batch program.
- steps: Array of job steps to debug.
- step: Specifies the name of the step within the JCL to be debugged.
- program: Specifies the name of the program to be debugged.
- DB2: Set as true or false, depending on whether Db2 is used.
- IMS: Set as true or false, depending on whether IMS is used.
  
  You can add the following optional properties to include all possible options. To include any of the following options, start typing the option names, and when it is visible on the screen select them.
- ddios: Specifies an optional comma-separated list of DDIO data sets to be searched for program source code. For example: ["HLQ.ABC.DEF","HLQ.GHI.JKL"]
- loadlibs: Specifies an optional comma-separated list of load libraries to be searched for load modules. For example: ["HLQ.ABC.DEF","HLQ.GHI.JKL"]
- log: Displays the log at the end of each debug session.
  - dsn: Enter the log data set options for your session.
  - spaceUnit: Enter the data set allocation. The space unit is TRK/CYL.
  - primary: Enter the primary value. The default value is 5.
  - secondary: Enter the secondary value. The default value is 5.
  - unit: Enter the unit name.
  - volume: Enter the volume.
  - dataClass: Enter the data class.
  - stgClass: Enter the storage class.
  - printToSysoutClass: Print output data set to SYSOUT. The output class is A-Z, 0-9.
  Following is the example with the optional fields added.
  {
     "type": "workbench-batch",
     "request": "launch",
     "name": "Batch Launch",
     "hciConnectionName": "",
     "jclDatasetMember": "",
     "jobName": "",
     "steps": [
         {
             "step": "",
             "program": "",
             "DB2": false,
             "IMS": false
         }
      ],
     "ddios": [],
     "loadlibs": [],
     "log": {
         "dsn": "",
         "spaceUnit": "TRK",
         "primary": "5",
         "secondry": "5",
         "unit": "",
         "volume": "",
         "dataClass": "",
         "stgClass": "",
         "printSysoutClass": ""
     }
  }
Save the launch.json file.

To create a Workbench batch debug configuration automatically

From the menu bar, click View and then click Command Palette. You can also press Ctrl+Shift+P to open the command palette.
In the command palette, start typing Workbench Debug and select Workbench Debug: Create Batch Launch Configuration... command from the list.
From the dropdown, select the required connection.
Important
If you have saved the credentials then you will be logged in to the selected profile, else you have to enter your credentials to log in to the selected connection.
In the JCL data set and member field, enter the name of the JCL dataset member.
Enter the configuration name.
Important
The location of the configuration file depends on the following scenarios:
- When no workspace is available, then by default, the configuration gets created in the user settings file.
- If you are in any workspace and select any of the following options:
  - User: configuration file is created in the settings.json file
  - Workspace: If any folder is not present, the configuration file is created in the code-workspace settings file. If you are in a single folder workspace, the configuration file is created in the folder in the workspace.
  - Workspace Folder: If multiple folders are present then you have to select the folder in which you want to create the configuration file and if only one folder is where the configuration file is created in the default folder.If you are in any workspace, then from the list, select the location where you want to create the launch configuration. If you are not in any workspace, the configuration file is created in the user settings file.

Creating Workbench CICS debug configuration

The following steps help you to create a Workbench CICS debug configuration.

To create a Workbench CICS debug configuration

In the left navigation panel of the VS code, click Run and Debug (). Alternatively, press Ctrl+Shift+D.
On the Run and Debug panel, click create a launch.json file.
Select Workbench CICS from the list displayed.

This creates a launch.json file under the .vscode folder.
Open the launch.json file from the workspace .vscode directory, and click Add Configuration. This creates a new launch configuration.
The following property fields are displayed. These fields are mandatory fields. Enter the values in the required fields.
   {
            "type": "workbench-cics",
            "request": "launch",
            "name": "CICS Launch",
            "hciConnectionName": "",
            "cicsRegion": "${command:AskForCICSRegion}",
            "program": {
                "loadModule": "",
                "csect": ""
            },
            "trap": [
                {
                    "users": {
                        "loggedInUser": true
                    },
                    "trapAbends": true
                }
            ]
        }
- type and request: Identifies this configuration as a launch configuration for Workbench. Do not modify these fields.
- name: Specifies the name of the launch configuration as it should appear in the VS Code Run and Debug dropdown.
- hciConnectionName: Specifies the name of the HCI connection profile that defines the connection to the mainframe where the job is to be debugged.
- cicsRegion: Lists the CICS region on which to run your debug session. When you start debugging, you need to select the region from the dropdown to debug.
- program: Specifies the name of the program to be debugged.
  Specify the load module name and the CSECT name of the program you want to debug.
- trap: Allows you to define the traps to be set upon startup of your debug session. Traps define the CICS activity subject to being trapped in a debug session.
Save the launch.json file.

Important

Once you start debugging, you can perform the following actions:

: Click to continue execution until a breakpoint or abend occurs or the program completes.

: Click to go forward to the following line of execution.

: Click to step into another program called from the same debug session