Full-screen mode is the interface that Debug Tool provides to help you debug programs on a 3270 terminal. This topic describes the following tasks which make up a basic debugging session:
Each topic directs you to other topics that provide more information.
Each programming language has a comprehensive set of compiler options. It's important to use the correct compiler options to prepare your program for debugging. The following list describes the simplest set of compiler options to use for each programming language:
When you compile your VS COBOL II program, the following options are required: NOOPTIMIZE, NOTEST, SOURCE, MAP, XREF, and either LIST or OFFSET.
See Planning your debug session for instructions on how to choose the correct combination for your situation.
There are several methods to start Debug Tool in full-screen mode. Each method is designed to help you start Debug Tool for programs that are compiled with an assortment of compiler options and that run in a variety of run-time environments. Starting Debug Tool describes each of these methods.
In this topic, we describe the simplest and most direct method to start Debug Tool for a program that runs in Language Environment in TSO. At a TSO READY prompt, enter the following command:
CALL 'USERID1.MYLIB(MYPROGRAM)' '/TEST'
Place the slash (/) before or after the TEST run-time option, depending on the programming language you are debugging.
The following topics can give you more information about other methods of starting Debug Tool:
After you start Debug Tool, the Debug Tool screen appears:
COBOL LOCATION: EMPLOOK initialization
Command ===> Scroll ===> PAGE
MONITOR --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 0 OF 0
******************************* TOP OF MONITOR ********************************
****************************** BOTTOM OF MONITOR ******************************
SOURCE: EMPLOOK --1----+----2----+----3----+----4----+----5----+ LINE: 1 OF 349
1 ************************************************************ .
2 * * .
3 * * .
4 ************************************************************ .
5 .
6 ************************************************************ .
7 IDENTIFICATION DIVISION. .
8 ************************************************************ .
9 PROGRAM-ID. "EMPLOOK". .
LOG 0----+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 5
********************************* TOP OF LOG **********************************
0001 IBM Debug Tool Version 9 Release 1 Mod 0
0002 10/03/2008 4:11:41 PM
0003 5655-U27: Copyright IBM Corp. 1992, 2008
PF 1:? 2:STEP 3:QUIT 4:LIST 5:FIND 6:AT/CLEAR
PF 7:UP 8:DOWN 9:GO 10:ZOOM 11:ZOOM LOG 12:RETRIEVE
The default screen is divided into four sections: the session panel header and three physical windows. The sessional panel header is the top two lines of the screen, which display the header fields and a command line. The header fields describe the programming language and the location in the program. The command line is where you enter Debug Tool commands.
A physical window is the space on the screen dedicated to the display of a specific type of debugging information. The debugging information is organized into the following types, called logical windows:
The default screen displays three physical windows, with one assigned the Monitor window, the second assigned the Source window, and the third assigned the Log window. You can swap the Memory window with the Log window.
Refer to the following topics for more information related to the material discussed in this topic.
Stepping through a program means that you run a program one line at a time. After each line is run, you can observe changes in program flow and storage. These changes are displayed in the Monitor window, Source window, and Log window. Use the STEP command to step through a program.
Refer to the following topics for more information related to the material discussed in this topic.
You can run from one point in a program to another point by using one of the following methods:
Refer to the following topics for more information related to the material discussed in this topic.
In Debug Tool, breakpoints can indicate a stopping point in your program and a stopping point in time. Breakpoints can also contain activities, such as instructions to run, calculations to perform, and changes to make.
A basic breakpoint indicates a stopping point in your program. For example, to stop on line 100 of your program, enter the following command on the command line:
AT 100
In the Log window, the message AT 100 ; appears. If line 100 is not a valid place to set a breakpoint, the Log window displays a message similar to Statement 100 is not valid. The breakpoint is also indicated in the Source window by a reversing of the colors in the prefix area.
Breakpoints do more than just indicate a place to stop. Breakpoints can also contain instructions. For example, the following breakpoint instructs Debug Tool to display the contents of the variable myvar when Debug Tool reaches line 100:
AT 100 LIST myvar;
A breakpoint can contain instructions that alter the flow of the program. For example, the following breakpoint instructs Debug Tool to go to label newPlace when it reaches line 100:
AT 100 GOTO newPlace ;
A breakpoint can contain a condition, which means that Debug Tool stops at the breakpoint only if the condition is met. For example, to stop at line 100 only when the value of myvar is greater than 10, enter the following command:
AT 100 WHEN myvar > 10;
A breakpoint can contain complex instructions. In the following example, when Debug Tool reaches line 100, it alters the contents of the variable myvar if the value of the variable mybool is true:
AT 100 if (mybool == TRUE) myvar = 10 ;
The syntax of the complex instruction depends on the program language that you are debugging. The previous example assumes that you are debugging a C program. If you are debugging a COBOL program, the same example is written as follows:
AT 100 if mybool = TRUE THEN myvar = 10 ; END-IF ;
Refer to the following topics for more information related to the material discussed in this topic.
After you are familiar with setting breakpoints and running through your program, you can begin displaying the value of a variable. The value of a variable can be displayed in one of the following ways:
For one-time display, enter the following command on the command line, where x is the name of the variable:
LIST (x)
The Log window shows a message in the following format:
LIST ( x ) ; x = 10
Alternatively, you can enter the L prefix command in the prefix area of the Source window. In the following line from the Source window, type in L2 in the prefix area, then press Enter to display the value of var2:
200 var1 = var2 + var3;
Debug Tool creates the command LIST (var2), runs it, then displays the following message in the Log window:
LIST ( VAR2 ) ; VAR2 = 50
The L prefix command is available only if the source has been compiled with the following compilers:
For continuous display, enter the following command on the command line, where x is the name of the variable:
MONITOR LIST ( x )
In the Monitor window, a line appears with the name of the variable and the current value of the variable next to it. If the value of the variable is undefined, the variable is not initialized, or the variable does not exist, a message appears underneath the variable name declaring the variable unusable.
Alternatively, you can enter the M prefix command in the prefix area of the Source window. In the following line from the Source window, type in M3 in the prefix area, then press Enter to add var3 to the Monitor window:
200 var1 = var2 + var3;
Debug Tool creates the command MONITOR LIST (var3), runs it, then adds var3 to the Monitor window.
The M prefix command is available only if the source has been compiled with the following compilers:
For a combination of one-time and continuous display, enter the following command on the command line:
SET AUTOMONITOR ON ;
After a line of code is run, the Monitor window displays the name and value of each variable on the line of code. The SET AUTOMONITOR command can be used only with specific programming languages, as described in Debug Tool Reference and Messages.
Refer to the following topics for more information related to the material discussed in this topic.
Sometimes it is helpful to look at memory directly in a format similar to a dump. You can use the Memory window to view memory in this format.
The Memory window is not displayed in the default screen. To display the Memory window, use the WINDOW SWAP MEMORY LOG command. Debug Tool displays the Memory window in the location of the Log window.
After you display the Memory window, you can navigate through it using the SCROLL DOWN and SCROLL UP commands. You can modify the contents of memory by typing the new values in the hexadecimal data area.
Refer to the following topics for more information related to the material discussed in this topic.
After you see the value of a variable, you might want to change the value. If, for example, the assigned value isn't what you expect, you can change it to the desired value. You can then continue to study the flow of your program, postponing the analysis of why the variable wasn't set correctly.
Changing the value of a variable depends on the programming language that you are debugging. In Debug Tool, the rules and methods for the assignment of values to variables are the same as programming language rules and methods. For example, to assign a value to a C variable, use the C assignment rules and methods:
var = 1 ;
Refer to the following topics for more information related to the material discussed in this topic.
Use the DISABLE command to temporarily disable a breakpoint. Use the ENABLE command to re-enable the breakpoint.
Refer to the following topics for more information related to the material discussed in this topic.
When you no longer require a breakpoint, you can clear it. Clearing it removes any of the instructions associated with that breakpoint. For example, to clear a breakpoint on line 100 of your program, enter the following command on the command line:
CLEAR AT 100
The Log window displays a line that says CLEAR AT 100 ; and the prefix area reverts to its original colors. These changes indicate that the breakpoint at line 100 is gone.
Refer to the following topics for more information related to the material discussed in this topic.
You can record and subsequently replay statements that you run. When you replay statements, you can replay them in a forward direction or a backward direction. Table 4 describes the sequence in which statements are replayed when you replay them in a forward direction or a backward direction.
| PLAYBACK FORWARD sequence | PLAYBACK BACKWARD sequence | COBOL Statements |
|---|---|---|
| 1 | 9 | DISPLAY "CALC Begins." |
| 2 | 8 | MOVE 1 TO BUFFER-PTR. |
| 3 | 7 | PERFORM ACCEPT-INPUT 2 TIMES. |
| 8 | 2 | DISPLAY "CALC Ends." |
| 9 | 1 | GOBACK. |
| ACCEPT-INPUT. | ||
| 4, 6 | 4, 6 | ACCEPT INPUT-RECORD FROM A-INPUT-FILE |
| 5, 7 | 3, 5 | MOVE RECORD-HEADER TO REPROR-HEADER. |
To begin recording, enter the following command:
PLAYBACK ENABLE
Statements that you run after you enter the PLAYBACK ENABLE command are recorded.
To replay the statements that you record:
PLAYBACK BACKWARD and PLAYBACK FORWARD change the direction commands like STEP move in.
When you have finished replaying statements, enter the PLAYBACK STOP command. Debug Tool returns you to the point at which you entered the PLAYBACK START command. You can resume normal debugging. Debug Tool continues to record your statements. To replay a new set of statements, begin at step 1.
When you finish recording and replaying statements, enter the following command:
PLAYBACK DISABLE
Debug Tool no longer records any statements and discards information that you recorded. The PLAYBACK START, PLAYBACK FORWARD, PLAYBACK BACKWARD, and PLAYBACK STOP commands are no longer available.
Refer to the following topics for more information related to the material discussed in this topic.
To stop your debug session, do the following steps:
Your Debug Tool screen closes.
Refer to Debug Tool Reference and Messages for more information about the QQUIT, QUIT ABEND and QUIT DEBUG commands which can stop your debug session.
Refer to the following topics for more information related to the material discussed in this topic.