Launching a Debug Session for an Existing Module on z/OS

Using IBM Developer for z Systems you can debug any language on the mainframe. For those who have taken Jon Sayle’s classes before, you know you can use IDz to generate JCL that will compile, link, and debug your code. The JCL is generated from a property group. However, what do you do if you want to debug a program that has already been built by someone else, or some SCM tool like Changeman or Endeavor?

Well, you can use the Debug Launch configurations to handle this. This is a nifty way of kicking a debugging session with or without access to the code. However, you will need to be sure you can access the SYSDEBUG, Listing, or SYSADATA file that was generated when the program was built. SYSDEBUG is needed for COBOL or PL/I. A SYSADATA is needed for any high level assembler program. As long as you know these, the next step is to generate the debug launch configuration, and there are two options for how this is configured. If you are not generating SYSDEBUG or SYSADATA files and promoting them with your load modules, you will not be able to effectively debug these modules. We also recommend that you change your promotion and deployment strategy as well!

First, let’s create a debug configuration. Within IDz (and the z/OS project’s perspective), click the Debug icon in the top toolbar, and select Debug Configurations…

Next, we’ll assume we are creating a debug configuration for a batch application (you’ll see debug configuration options for IMS, CICS, DB2 launches also). Right click on MVS Batch Application and select New.

JCL Generation Option

The debugger ultimately needs the following information to get a session started:

• The load module to execute
• The source to lookup (or debug information)
• How to connect the debug manager back to your workstation
• Any program or runtime parameters that the load module needs

You can store this in either a property group, or in the workbench preferences. This option above uses the workbench preferences. Click on the Preferences link to bring those up.

Here, you will specify the debug option of TEST (NOTEST makes no sense if you’re not testing!). You can list a z/OS Debugger commands data set that has a text list of commands that you send to the z/OS debugger to setup the debugging environment for the module. The z/OS Debugger dataset is the location of the debugger (if needed). Use this if you need to ensure the z/OS debugger dataset is added to the STEPLIB of your JCL.

You will need a default job card here. Enter a job card that is appropriate for your environment.

For Source lookup, you will need to enter the source member, and either the SYSDEBUG dataset (for COBOL and PL/I), or SYSADATA and EQALANGX files for C/C++ and Assembler (you cannot debug assembler modules without the ADATA file).

Click OK to go back to the debug configuration panel. Now you need to have a base JCL to start from, which the JCL generation will modify. This could be an existing JCL that you use to run the batch file, with some caveats. Now click on the Debug Options tab.

Here on the debug options tab, it should inherit the settings from your other preferences, but can override them for this launch configuration (such as enabling tracing, specifying LE options, or pointing to the z/OS debugger installed data set. Most importantly here is the option to override the connection information. The Debug Manager on z/OS is called by this launch configuration’s JCL (indirectly via a CEEOPTS DD statement). It must know how to communicate the debug session back to your IDz workstation. Most of the time, you may not need to configure it. However, there are times where you may have a complex firewall or VLAN setup that requires you to enter a specific user name (which the Debug Manager can map to your IP address), or your explicit IP address and port number where the debug listener is running.

The Debug Tool Compatibility mode checkbox here would make the debugger act like Debug Tool, which may be appropriate if you are debugging some old COBOL 3 code, or you have other issues with your environment that interfere with using standard mode.

On the Additional JCL tab, you will override the source lookup and Job card from your preferences. As you can see, while the preferences apply to the whole workbench, the launch configuration allows you to override as needed. This adheres to the standard of configuration by exception.

The other tabs can be glossed over. At this point, you can click Apply. You’re now ready to debug your module.

Option 2: Using a Property Group

This is our recommended approach, as you can have MANY property groups, and these can be shared amongst developers using he Import/Export features of the Property Group Manager.

On the JCL tab, change the Property Group drop down to the property group you created for your module. This could be the same property group you used if you did the compilation. Here you point to the load module you are going to debug (with the other option, you have to rely on the existing JCL to point to the correct load module). For the Property Group, you need to configure the JCL tab and Run tabs. On the Run Tab, configure the Debug section to suit your needs as shown below:

WHen you use the Property Group option, the Debug Options, Additional JCL tabs become disabled as all the information is pulled from the property group. Now all you have to do is click Apply and Debug and start the debug session. Once you’ve ended the session, all you need to start it again, is to click the Debug icon, and the debug configuration name you created (shown below).

So, as a summary, you don’t have to create a whole new load module to debug. As long as you have the matching source, and SYSDEBUG dataset (or SYSADATA, you can debug it. Even if it was optimize (OPT level 1 or higher for COBOL), you can still debug it, with some limitations. However, you need the SYSDEBUG or SYSADATA/EQALANGX files as well as the source. Make these part of your environments normal promotion and deployment routines.