Configuring DevX Code Debug

You can create the following debug configuration.

• Creating DevX batch debug configuration
• Creating DevX CICS debug configuration
• Editing DevX CICS debug configuration
• Accessing the output logs for suspended debug session
• Creating DevX IMS MPP debug configuration
• Editing DevX IMS MPP debug configuration

Before you begin

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

Creating DevX batch debug configuration

You can create the DevX batch debug configuration manually or by creating the configuration file using the UI form.

To create a DevX 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. 
   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 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.

1. • 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.
   • scripting: Defines an initial script to use with your session. You can add the script if you want to skip the entry breakpoint while performing debugging.

1. • • initialScript: Member name containing the initial script.

     • datasets: Data set containing the initial script and any additional data sets that contain scripts called by the initial script.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": ""
          }
          "scripting": {
              "initialScript": "",
              "datasets": []
          }
       }
2. Save the launch.json file. 

To create a DevX 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 DevX Code Debug and select DevX Code Debug: Create Batch Launch Configuration... command from the list.
3. In the Name field, enter the name of the configuration.
4. Select HCI Connection from the dropdown.

5. In the JCL data set (member) field, click Find and select the JCL data set (member).

   Important

   If a JCL contains a single step, then the job name and Step details are auto-populated, and you can click + to enter the step and program manually.
   If a JCL contains multiple steps, the job name is auto-populated and when you click +, you can select the step from the list of the multiple steps to debug. You can enter the manual entry by selecting Add a new entry so I can manually specify the step to debug.

   If your JCL data set member contains any procedure libraries, you can configure those in the Settings. For more information Configuring-procedure-libraries.

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 a batch 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 Display a 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 after 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 based 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. 

To edit the batch 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 DevX Code Debug and select DevX Code Debug: Edit batch Launch Configuration... command from the list.
3. Select the launch configuration location. Based on the selected location, the batch launch configurations list is displayed.
4. Select the batch Launch Configuration that you want to edit. The batch form with pre-filled data is displayed.
5. Edit the required field and click Save Configuration.

Creating DevX CICS debug configuration

The following steps help you to create a DevX CICS debug configuration manually or by creating the configuration file using the UI form.

To create a DevX 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. 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 DevX 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 DevX Code Debug and select DevX Code 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 a single folder workspace, you can see the 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 DevX 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 DevX Code Debug and select DevX Code 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 DevX 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 DevX Code Debug and select DevX Code 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 based on workspace structure. 
         a. When no workspace is available, the launch configuration is created in the user settings file by default.
         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 the 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 in the debug console.

Editing DevX 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 DevX Code Debug and select DevX Code 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.