Quick sample debugging session with PL/I

• Prepare the programs
• Start an interactive debugging session
• Step through code
• Trace statements
• Count statements
• Set breakpoints
• View and modify data values.

Preparing the programs

The source for the sample programs TRIMAINP, TRITSTP, TRIRPTP, and TRIDATA (the data set containing the data) is provided in the SLXTSAMP library. The common load module, test data, DDIO data set, and file list libraries should have already been created and/or verified by your site installer. Contact your installer for the names of these data sets and libraries.

If these data sets and libraries were not created, you must compile and link edit the programs using the BMC AMI Common Shared Services (CSS) PL/I language processor. You must also specify the appropriate load module on the Setup screen.

Option 1 on the Code Debug TSO Primary Menu can be used to compile and link edit the programs. See to Preparing Your Programs if you require assistance.

When you are ready to start the session, do the steps listed in Starting the Debugging Session.

Starting the debugging session

1. Type PLI64 in the Profile field on the Code Debug TSO Primary Menu to set up a profile for the session. Code Debug displays the Profile screen, and prompts you to enter a description for the new profile. Enter PLI TRIMAINP in the description area and press the END key. The Primary Menu is redisplayed.
2. Type 2 (TSO) in the command line on the Primary Menu and press Enter. The Environments Menu is displayed if this is your first time invoking a Code Debug TSO debugging session. Otherwise, the last environment test screen you used is displayed. To access the Environments Menu, type SETUP in the command line of the displayed environment test screen. Then select option 0 on the Test Setup Menu to display the Environments Menu.
3. Type 1 (STANDARD) on the Environments Menu.
4. Press Enter.
5. Type SETUP on the standard test screen.
6. Type 1 (LOADLIBS) on the Setup Menu.
7. On the Load Module Libraries screen, enter the name of the application load library that contains the TRIMAINP load module (optional).
8. Press Enter.
9. Type 2 (DDIO) on the Setup Menu.
10. On the DDIO Files screen, you may enter the DDIO data set name that contains the source listing member of TRIMAINP. In addition to the original DDIO data set name, you may also specify a Shared Directory data set name and/or an LP database data set name.
11. Press Enter.
12. Enter END or press PF3 to return to the standard environment test screen.
    Specify the name of the program and the name of the file list or the JCL containing the names of the files required by your program. Complete the screen as shown in the following figure.

Standard Test Screen 

Press Enter to begin the Code Debug TSO debugging session. The message area contains the lines Allocating Code Debug TSO Data sets, then Allocating User Data sets. On a blank screen, the message Entering Code Debug TSO Test Environment appears. 

Code Debug TSO processes the file list, allocates the necessary data sets, loads the program TRIMAINP, and displays the PL/I source listing. The message BEFORE BREAKPOINT ENCOUNTERED is displayed and the execution arrow (=====>) points to the PROCEDURE statement. This means that TRIMAINP stopped before beginning execution of the program. Also, a left/right scroll indicator (e.g., -- Before TRIMINP1 <>) appears on the execution status line. A double arrow indicates that scrolling is allowed both left and right. An example of the source display is shown in the following figure.

TRIMAINP Program in the Source Display

Stepping through the code

The first time the program is displayed, you will want to see how the program works by stepping through one statement at a time. Press PF9 (GO 1) to execute statements one-by-one. As shown in the following figure, program execution stops on statement 12, as indicated by the execution arrow.

Stepping Through Code

Press PF9 (GO 1) again. Program execution stops on statement 15, and so forth as you continue to press PF9.

Enter RETEST on the command line to obtain a fresh copy of the source.

Analyzing program logic

When you are not sure what the program is doing, you can trace the logic, highlighting each statement as it is executed with the TRACE command. Following program execution under live conditions speeds comprehension. Enter the following on the primary command line to control the tracing speed:

Then enter the following on the command line to trace all statements executed:

Each statement that is executed is highlighted. When the default of 25 statements has been reached, program execution pauses and the following message is displayed:

To look at the output from the TRACE command enter LOG on the command line to look at the session log. The session log shows which statements were executed during the trace. See the following figure.

Code Debug TSO Session Log Showing Statement Execution Tracing

Notice that the arrow on the status line indicates that you can scroll to the right.

Another way to analyze program logic is to count the number of times a statement is executed. The COUNT command is used for this purpose. For this demonstration we will count the number of times each statement is executed. First enter the following on the command line to end the tracing mode.

Then, enter:

When the program completes execution, you can scroll back through the program to look at the results of the COUNT command. The COUNT command gives immediate results by displaying a 7-digit counter field in columns 74 through 80, as shown in the following figure.

Result of Using the Count Command

Enter RETEST on the command line.

Setting breakpoints

When testing a program, you may want to stop program execution to see the value of a variable at a particular statement, check the operands in a calculation, inspect a record that may be causing a problem, and so on. With breakpoint commands, you can stop program execution before or after a statement, procedure, module, and so forth.

Breakpoint commands can be entered on the primary command line or in the line command area. For this example, move the cursor to statement number 25 at the ANALYZE_NEXT_REC procedure, then type over the statement number with the B (Before) line command. When you press Enter, a B appears in column 9 on statement 25, indicating that a before breakpoint has been set. See the following figure. This breakpoint causes program execution to pause before executing the ANALYZE_NEXT_REC procedure.

Result of Entering a Before Breakpoint

Press PF12 or enter GO to execute TRIMAINP until the breakpoint is reached. The program stops at statement 25, where the execution arrow is pointing. The execution status field on the fourth line also shows that execution is paused at Before TRIMINP1:25 as shown in the following figure.

Program Stopped at Before Breakpoint on Statement 25

Displaying data values

Whenever program execution halts, Code Debug TSO automatically displays the value of data items referenced by the current execution line. These automatic keeps are displayed in a window at the top of the screen. Each time the program stops, a new set of variables and their values are displayed.

Also, any time you stop program execution, you can use the KEEP command to continuously display the contents of any number of variables as your program executes.

For this example, you will use the KEEP command and watch the values of WORK_REC and TRIANGLE_TYPE to see if the calculations are being performed correctly. Move the cursor to statement 11 (WORK_REC) and enter KE (Keep Element) so that you can view the contents of each element. Then move the cursor to statement 10 (TRIANGLE_TYPE) and enter K (Keep). The Keep window at the top of the screen in the following figure has been expanded so that all the kept items can be displayed. See to the SET command in the Command-and-syntax-reference for additional information on setting window size. The K in column 9 differentiates an explicit keep from an automatic keep.

Displaying the Variables WORK_REC and TRIANGLE_TYPE 

Press PF12 (GO) to execute TRIMAINP. As shown in the following figure, the B (BEFORE) breakpoint at statement 25 stopped execution before executing the ANALYZE_NEXT_REC procedure. You can see that record 345 was read into WORK_REC and TRIANGLE_TYPE and contains a value of 3 indicating that the value 345 is equal to a scalene (type 3) triangle.

Data Displayed in the Keep Window

Press PF12 again. The next record 789 is read in the second time through the loop. WORK_REC is updated to reflect the change and TRIANGLE_TYPE remains the same because 789 equals a type 3 triangle. See to the following figure.

Seeing Data Change in the Keep Window

If you continue pressing PF12, you will see the value of TRIANGLE_TYPE change when the value of WORK_REC changes to a different type of triangle.

Debugging subroutines

Statement 29 shows that the program TRIMAINP calls TRITSTP and passes parameters WORK_REC and TRIANGLE-TYPE. In order to examine how TRITSTP is processing these parameters, you can set a breakpoint at the beginning of TRITSTP to gain control of the execution when the call is made. Enter the following command on the primary command line:

The colon (:) after the program name indicates that a module-level breakpoint is requested. Press PF12 (GO) to execute the program. Code Debug TSO pauses execution at the TRITSTP procedure as shown in the following figure Note the automatic keeps displayed in the Keep window.

Execution Stopped at the TRITSTP Procedure