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
• Creating Workbench IMS MPP debug configuration
• Editing Workbench IMS MPP 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 or by creating the configuration file using the UI form.

To create a Workbench batch debug configuration for a Workspace manually

1. In the left navigation panel of the VS code, click Run and Debug ().
2. On the Run and Debug panel, click create a launch.json file. 
   
   
   
   
3. Select Workbench Batch from the list displayed. 
   
   This creates a launch.json file under the .vscode folder.
   
4. Open the launch.json file from the workspace .vscode directory, and click Add Configuration. This creates a new launch configuration. 

5. The following property fields are displayed. These fields are mandatory. 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": ""
        }
     }  
6. Save the launch.json file. 

To create a Workbench batch debug configuration by using the UI form

1. From the menu bar, click View and then click Command Palette. You can also press Ctrl+Shift+P to open the command palette.
2. In the command palette, start typing Workbench Debug and select Workbench Debug: Create Batch Launch Configuration... command from the list.

3. 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.

4. In the  JCL data set and member field, enter the name of the JCL dataset member.

5. 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.

   While saving an untitled workspace or adding a folder to a saved .code-workspace file that has no associated folder, you must save your work.

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

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

4. 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
                   }
               ]
           }
5. 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.
6. Save the launch.json file.

To create a Workbench CICS debug configuration using the UI form

1. From the menu bar, click View and then click Command Palette. You can also press Ctrl+Shift+P to open the command palette.
2. 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.
3. In the Name field, enter the name of the launch configuration.
4. Select HCI Connection from the dropdown.
5. 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.
6. 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.
7. After you fill in all the required details, click Save Configuration.

8. 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.

9. 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.
   
   

Editing Workbench CICS debug configuration

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

To edit the CICS debug configuration

1. From the menu bar, click View and then click Command Palette. You can also press Ctrl+Shift+P to open the command palette.
2. In the command palette, start typing Workbench Debug and select Workbench Debug: Edit CICS Launch Configuration... command from the list.
3. Select the launch configuration location. Based on the selected location, the CICS Launch Configurations list is displayed.
4. Select the CICS Launch Configuration that you want to edit. The CICS form with pre-filled data is displayed.
5. 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.

Creating Workbench IMS MPP debug configuration

The following steps help you to create an IMS MPP launch configuration.

To create  an IMS MPP launch configuration

1. From the menu bar, click View and then click Command Palette. You can also press Ctrl+Shift+P to open the command palette.
2. In the command palette, start typing Workbench Debug and select Workbench Debug: Create IMS MPP Launch Configuration... command from the list. The IMS MPP Launch Configuration window is displayed with the form where you can fill in the following required details to create the IMS MPP launch configuration.
3. In the Name field, enter the name of the configuration.
4. In the IMS MPP JCL Execution section, perform the following actions.
   1. From the HCI Connection name list, select the required connection that defines the connection to the mainframe where you want to debug the job.
   2. In the JCL data set(member) field, enter the data set name or member containing the JCL to run the program. You can also click Find, to search the data set.
   3. Select the Hogan test check box if you want to set a flag for Code Debug IMS to perform a Hogan test.
5. In the Debug Criteria section, perform the following actions.
   1. In the Job name field, enter the job name of the JCL data set member that is submitted here. This job name is used by Code Debug IMS to intercept this job for testing.
   2. In the Step name field, enter the name of the step for Code Debug to intercept.
   3. In the IMS User ID field, enter the IMS User ID that you want to use to test this program/transaction. This field is used to specify the ID of the IMS user issuing the IMS transaction you want to debug and is applicable only if IMS user ID or the IMS DATA Value Driven Intercept support is enabled. In case, we leave it empty, it will be replaced by '*', indicating a generic match.
   4. Programs and Transactions - '+' to add multiple programs and transaction information.
      • In the Program field, enter the IMS MPP program to be tested using Code Debug IMS. 
      • In the Transaction field, enter the IMS MPP transaction to be tested using Code Debug IMS.
      • In the Data field, enter the IMS MPP data to be used by the program/transaction specified above. This field can be used in conjunction with the User ID field (if the IMS DATA Value Driven Intercept has been installed) to further restrict the selection of transactions to those that contain the specified data in the transaction buffer.
6. In the Datasets section, perform the following actions.
   1. In the Load libraries field, enter the comma-separated list of load libraries. The Load Libraries tab of an IMS MPP debug configuration allows you to define the load libraries that will be concatenated to the STEPLIB DD in your JCL.
   2. In the DDIO data sets field, enter an optional comma-separated list of DDIO data sets to be searched for program source code.
7. In the Log section, perform the following actions.
   1.  Select the Generate log after each debug session checkbox to display the log at the end of each debug session.
   2. In the Log data set name field, enter the log data set options for your session.
   3. Select the Delete and print log dataset at end of debug session print to a SYSOUT class check box to select the SYSOUT class from the Print to SYSOUT class drop-down list.
   4. In the Units field, enter the data set allocation. The space unit is TRK/CYL, default is TRK.
   5. In the Primary field, enter the primary value. The default value is 5.
   6. In the Secondary field, enter the secondary value. The default value is 5.
   7.  In the Unit field, enter the unit name.
   8. In the Volume field, enter the volume.
   9. In the Data class field, enter the data class.
   10. In the Storage class field, enter the storage class.
               
8.  Click Save Configuration. If all the required fields are filled you get an option for a location to be saved basis on workspace structure. 
         a. When no workspace is available, by default, the launch configuration is created in the user settings file.
         b. If you are in a workspace,
   1. 
      
      • User: Launch config is created in the settings.json file for the user
      • Workspace: If no folder, configuration is created in the code-workspace settings file. If you are in a single folder workspace, the configuration is created in a folder in the workspace.
      • Workspace Folder: Configuration is created in the selected folder or default folder if have only one. 

    The following is an example of the JSON configuration.

To execute the IMS MPP json

1. Click Run and Debug and select the configuration that you want to run. You see the logs in debug console, executing a transaction/program through the emulator will allow you to load the source in vs code window.
2. Once you start debugging, you can perform the debugging actions. On completion of the program, you will get a prompt to run another transaction. And if you select Yes, you can run another transaction through the emulator and continue with debugging. If not, you can click Cancel and see the final logs can be seen in debug console.

Editing Workbench IMS MPP debug configuration

You can edit the IMS MPP launch configurations that you have created.

To edit the IMS MPP debug configuration

1. From the menu bar, click View and then click Command Palette. You can also press Ctrl+Shift+P to open the command palette.
2. In the command palette, start typing Workbench Debug and select Workbench Debug: Edit IMS MPP Launch Configuration... command from the list.
3. Select the launch configuration location. Based on the selected location, the IMS MPP Launch Configurations list is displayed.
4. Select the IMS MPP Launch Configuration that you want to edit. The IMS MPP launch configuration form with pre-filled data is displayed.
5. Edit the required field and click Save Configuration.