Batch Interactive Debugging Scenario
This tutorial will introduce you BMC AMI DevX Code Debug for TSO & IMS within BMC AMI DevX Workbench for Eclipse. You will use a couple of time-saving functions including 'right-click" access to Code Debug commands and the ability to record and playback code executions to help resolve difficult abends.
You will use the Code Debug Monitor command to help us solve a problem with a COBOL Program. This command allows you to record the execution of a program and play it back in review mode. While in Review Mode you can leverage all the DevX Code Debug commands as you simulate reverse execution.
In this scenario, we have a small payroll application that has an employee file as input. This employee file includes multiple record types, including hourly, salary, and management-type employees. The program processes each of these record types as it executes.
Instructions
- This guide contains many screenshots to provide a visual reference
- Every action is in blue
- Please note each place that you must enter your own specific ID or number
- You must complete each step before proceeding to the next to follow the test drive script successfully
In this part of the test-drive, you will set up and open a debugging session with Code Debug interactive debugger.
To run an Code Debug test for a batch program, you need two things:
- A program that has been compiled with the DevX Enterprise Common Components Language Processor to capture the compile listing in a DDIO member.
- The JCL to run the program.
We will go through an example of how to obtain both items and then start an Code Debug test.
Setting Up
Prepare the program for Code Debug
Click the BMC drop-down menu and click Host Explorer.
First, you need to compile and link the program that you want to test using the BMC AMI Devx ECC Language Processor to store the compile listing in a DDIO file.
In the Host Explorer view, navigate to yourid.WBSAMP.JCL and expand the dataset by clicking on the expand button – ">."
Right-click on member LPCOBCL and click Submit.
This job will compile the programs with the DevX Enterprise Common Components Language Processor to capture the compile listing in a DDIO
Click OK.
Verify that the compile was successful, a CC of 4 step for CWXTCOB is acceptable.
Execute JCL
We are going to verify that the program now executes successfully.
Right-Click CWXTJCLC and Submit.
Verify that the JCL completed with a CC of 0.
Configure Launch Configuration
Right-click on CWXTJCLC again, click 'Debug As' then select Code Debug Batch Debug Session.
This will open the Debug Configuration dialog completed with the details extracted from the JCL.
Click Debug.
Code Debug requires login credentials to submit your job and attach to it.
Click OK.
You will be prompted to switch perspective.
Click Switch.
Close the Cheat Sheets* as indicated in the screenshot.
*Cheat Sheets can be a very helpful tutorial tool, but for our test drive we do not need them, so closing them gives us more screen real estate to work with.
If you need to bring up cheat sheets again, click Help then select Cheat Sheets.
Code Debug Eclipse
The Code Debug perspective has several views that are helpful during the debug session.
Add Tool bar to the Debug View.
Lets start by adding the Debug Toolbar. This will give you debugging controls in the Debug view
The Debug View
The Debug view provides details about the configuration as well as why you are stopped in the program. In this case it is because we encountered the default breakpoint.
The Breakpoints View
Any breakpoints or conditional commands issued will be displayed. The tool bar in this view allows you to delete one or all breakpoints. You also have the option to uncheck a condition or breakpoint, which will disable it. You can re-enable any breakpoints/conditions by checking the box.
The Variables View
In the Variables view the variables associated with the currently executing statement will automatically be displayed (displayed with a blue diamond). You can add variables to this view, right-click to 'Add to Watch Variables' to keep variables in this view (displayed with glasses) throughout the program execution.
Data values can be viewed and/or modified during program execution.
The Source Listing (Edit View)
What is shown is the DDIO listing that was generated during the compile. This is how you see source when we are executing your program. Code Debug places a default breakpoint on the first executable statement in the program. Code Debug commands are displayed when you right-click in this view.
The Outline View
The Outline view displays an outline of a structured file that is currently open and can be used to navigate into the program during the debug session.
Debug Scenario
In this script we will use the Monitor command to help understand what is happening in this program when it executes when "PARM-DATA" variable contains a value of '00002'.
Expand the 'PARMINFO' variable in the Variables View. Change value from '00003' to '00002'
With Code Debug you can display and modify variable, register, and storage contents.
When variable contains a value of 0002 in it causes a S0C7 abend that is difficult to diagnose.
Right Click within the Editor View to see list of available Code Debug commands.
Select 'Monitor'.
Select the Resume Icon in the Toolbar to resume execution.
Monitor and Review functionality lets you monitor(record) and review the execution path of a program. It enables you to step backward through your program to view the actual sequence of instructions.
Notice the message in the Console and the icon in the Debug view, show that Monitor is enabled.
Click the BMC AMI DevX Abend-AID Icon.
Notice that we are getting a S0C7, this is the issue we've been encountering when processing parm data with a value of '00002'. From this view we can access the Abend-AID report to get more details of the abend.
Double click the Abend-AID Tab to maximize.
As you can see from an active debug session you can access and analyze the AA report.
Double click Abend-AID tab to minimize.
With this integration you can diagnose the issue while still actively debugging the program.
The abend indicated that GRAND-TOTAL-EMP contains invalid packed data. However, this program initializes this fields at the start. It should not contain invalid values. It should contain zeroes.
One option during this session is to Toggle Breakpoint on all statements that reference the field name of GRAND-TOTAL-EMP. However, it is possible that the statement that changes the values of GRAND-TOTAL-EMP may not actually reference it.
Our best bet is to use the WHEN command.
Right-click in the Edit view to show Code Debug commands and Select 'Set When Condition'.
The 'When' command is not associated with a particular source line. The When command will suspend execution when the data value changes by default or when specified condition occurs.
Enter 'GRAND-TOTAL-EMP' in the dialog box, press "OK".
'Changes' is the default for the When condition, so we only need to enter the Variable name.
Right-click in the Edit view to show Code Debug commands and Select 'Add Watch Variables'.
Since this variable is associated with the currently executing statement, let's add it to the variables view. Notice that the variables associated with the currently executing statement are listed. However, you can always add any variable from your program to the list by clicking the 'By Name'.
Check the box for GRAND-TOTAL-EMP, press "OK".
This will retain 'GRAND-TOTAL-EMP' in the variables view.
This allows you to retain variables in the Variables view throughout the execution.
Click Review Resume Backward.
Also notice that once we began execution with Monitor on the Review toolbar is now active.
This time instead of Resume, we will use the Review Toolbar.
The When condition is shown in the Breakpoints view. Code Debug will retain any breakpoints or conditions for use in subsequent debugging sessions.
Expand Region-Comment in the Variables view.
The statement that altered Grand-Total-Emp is referencing a table array. However, the table only occurs 4 times, but the index contains a value 5. It should be any value between 1-4.
This time let's set the When condition to find how the index 'WA-EMP-REGION' is getting populated with a value of '5' instead of 1-4. First let's add the variable to the Variables View.
Right-click in the Edit view to show Code Debug commands and Select 'Add Watch Variables'.
Check the box for WA-EMP-REGION, press "OK"
Right-click in the Edit view to show Code Debug commands and Select 'Set When Condition'.
Enter 'WA-EMP-REGION' in the dialog box, click ok and Review Resume Backward.
Notice that the field is being populated by an external file. Now that we have the details, we can bring this information to the application team that supports the program that created this file
Uncheck the When conditions in the Breakpoint View and click the Resume.
Now that we know what the problem is, we can toggle off Monitor.
Unchecking the condition/breakpoint allows you to disable for reuse later or subsequent debug sessions.
Resume will bring us back to the point where the abend occurred.
Change the value of 'GRAND-TOTAL-EMP' to '0'.
This highlights how we have full control of the variables within our program in a debug session.
Congratulations! You have completed the Batch Interactive Debugging Test Drive Script.
In this script, you learned what it is like to use a modern Integrated Development Environment to debug your applications.
Restarting This Script
At any point should you need to restart this Test Drive script, follow the instructions below:
You can reuse the same Launch configuration to start the debug session.
Next Steps
Click on the link below to return to the BMC Test Drive main page and choose your next road trip!
BMC AMI TEST DRIVE