Configuring Workbench Debug

You can create the following debug configuration.

Creating Workbench batch debug configuration
Creating Workbench CICS debug configuration
Editing Workbench CICS debug configuration
Accessing the output logs for suspended debug session

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 or by creating the configuration file using the UI form.

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 by using the UI form

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 manually or by creating the configuration file using the UI form.

To create a Workbench CICS debug configuration manually

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.
   {
            "type": "workbench-cics",
            "request": "launch",
            "name": "CICS Launch",
            "hciConnectionName": "",
            "cicsRegion": "${command:AskForCICSRegion}",
            "program": {
                "loadModule": "",
                "csect": ""
            },
            "trap": [
                {
                    "users": {
                        "loggedInUser": true
                    },
                    "trapAbends": true
                }
            ]
        }
The following property fields are displayed. These fields are mandatory fields. Enter the values in the required fields.
- 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.

To create a Workbench CICS debug configuration using the UI form

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 CICS Launch Configuration... command from the list. The CICS Launch Configuration window is displayed with the form where you can fill in the following required details to generate CICS Configuration.
In the Name field, enter the name of the launch configuration.
Select HCI Connection from the dropdown.
Select CICS Region from the dropdown, it is based on the selected HCI connection. If you have selected Prompt me, then it will prompt a list of CICS regions during the Configuration launch.
Click Add Trap. The Add Trap dialog box is displayed. Add all the required details to add a trap and click Save Trap. You can edit a trap by right-clicking and choosing from the context menu.
After you fill in all the required details, click Save Configuration.
Select the location where you want to create the launch configuration.
Important
The dropdown options available to select the location to create the configuration are based on the kind of workspace you are in:
- If you are in a file workspace or in a single folder workspace, you can see User and Workspace options in the dropdown.
- If you are in a workspace with multiple root folders, you can see User, Workspace, and Workspace Folder options in the dropdown. In this case, if you have only one multi-root folder it'll pick that folder, by default.
When you select the location the launch configuration is created.
Select the folder in which we want to create our configuration. This option is displayed when more than one root folder is available in the workspace.

The location of launch config creation depends on different scenarios:

When no workspace is available, by default, the launch configuration is created in the user settings file, when you enter the launch configuration name.
If you are in a workspace:
- User: Launch config will be created in the settings.json file for the user
- Workspace: If no folder, configuration will get created in the code-workspace settings file. If you are in a single folder workspace, the configuration will get created in a folder in the workspace.
- Workspace Folder: Configuration will get created in the selected folder or default folder if have only one.
  For the first time, the folder structure for launch.json is created automatically on selection.

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

Editing Workbench CICS debug configuration

You can edit the CICS launch configurations that you have created.

To edit the CICS debug configuration

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: Edit CICS Launch Configuration... command from the list.
Select the launch configuration location. Based on the selected location, the CICS Launch Configurations list is displayed.
Select the CICS Launch Configuration that you want to edit. The CICS form with pre-filled data is displayed.
Edit the required field and click Save Configuration.

Accessing the output logs for suspended debug session

You can see the output logs of the suspended debug session. When you launch a debug session and see the debug session suspended message, click Open Log to see the batch output log for the session.