The topics below describe the Debug Tool full-screen interface, and how to use this interface to perform common debugging tasks.
Debugging your programs in full-screen mode is the easiest way to learn how to use Debug Tool, even if you plan to use batch or line modes later.
Refer to the following topics for more information related to the material discussed in this topic.
The Debug Tool session panel contains a header with information about the program you are debugging, a command line, and up to three physical windows. 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:
Each physical window can be assigned only one logical window. The physical window assumes the name of the logical window, so when you enter commands that affect the physical window (for example, the WINDOW SIZE command), you identify the physical window by providing the name of its assigned logical window. Physical windows can be closed (not displayed), but at least one physical window must remain open at any time.
The Debug Tool session panel below shows the default layout which contains three physical windows: one for the Monitor window 1 , a second for the Source window 2 , and the third for the Log window 3 .
COBOL LOCATION: DTAM01 :> 109.1
Command ===> Scroll ===> PAGE
MONITOR -+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 7
**************************** TOP OF MONITOR **********************************
----+----1----+----2----+----3----+----4----
0001 1 NUM1 0000000005
0002 2 NUM4 '1111' 1
0003 3 WK-LONG-FIELD-2 '123456790 223456790 323456790 423456790 5234
0004 56790 623456790 723456790 8234567890 9234567
0005 90 023456790 123456790 223456790 323456790 4
0006 23456790 5234567890 623456790 723456790 8234
SOURCE: DTAM01 ---1----+----2----+----3----+----4----+----5--- LINE: 107 OF 196
107 * SINGLE DATAITEM IN A STRUCTURE .
108 *------------------------------------------------------------- .
109 ADD 1 TO AA-NUM1 2 .
110 .
111 *------------------------------------------------------------- .
112 * SINGLE DATAITEM IN A STRUCTURE - QUALIFIED .
LOG 0----+----1----+----2----+----3----+----4----+----5----+---- LINE: 40 OF 43
0040 MONITOR
0041 LIST NUM4 ;
0042 MONITOR 3
0043 LIST WK-LONG-FIELD-2 ;
Refer to the following topics for more information related to the material discussed in this topic.
The first few lines of the Debug Tool session panel contain a command line and header fields that display information about the program that you are debugging.
Below is an example header for a C program.
C 1 LOCATION: MYID.SOURCE(TSTPGM1):>248 2 Command ===> 3 SCROLL ===> PAGE 4 5
Below is an example header for a COBOL program.
COBOL 1 LOCATION: XYZPROG::>SUBR:>118 2 Command ===> 3 SCROLL ===> PAGE 4 5
·
·
·
The header fields are described below.
In the C example above, execution in MYID.SOURCE(TSTPGM1) is suspended at line 248.
In the COBOL example above, execution in XYZPROG is suspended at XYZPROG::>SUBR:>118, or line 118 of subroutine SUBR.
If you are replaying recorded statements, the word "LOCATION" is replaced by PBK<LOC or PBK>LOC. The < and > symbols indicate whether the recorded statements are being replayed in the backward (<) or forward (>) direction.
If you are using the Enterprise PL/I compiler or the C/C++ compiler, the compile unit name is the entire data set name of the source. If the setting for LONGCUNAME is ON (the default) to display the CU name in long form, the name might be truncated. If your PL/I program was compiled with the following compiler and running in the following environment, the package statement or the name of the main procedure is displayed.
The value in this field is the operand applied to the SCROLL UP, SCROLL DOWN, SCROLL LEFT, and SCROLL RIGHT scrolling commands. Table 16 lists all the scrolling commands.
| Command | Description |
|---|---|
| n | Scroll by n number of lines. |
| HALF | Scroll by half a page. |
| PAGE | Scroll by a full page. |
| TOP | Scroll to the top of the data. |
| BOTTOM | Scroll to the bottom of the data. |
| MAX | Scroll to the limit of the data. |
| LEFT x | Scroll to the left by x number of characters. |
| RIGHT x | Scroll to the right by x number of characters. |
| CURSOR | Position of the cursor. |
| TO x | Scroll to line x, where x is an integer. |
1 SOURCE: MULTCU ---1----+----2----+----3----+----4----+----5----+ LINE: 70 OF 85 70 PROCEDURE DIVISION. . 71 ************************************************************** . 72 * THIS IS THE MAIN PROGRAM AREA. This program only displays . 73 * text. 3 . 74 ************************************************************** . 2 75 DISPLAY "MULTCU COBOL SOURCE STARTED." UPON CONSOLE. . 76 MOVE 25 TO PROGRAM-USHORT-BIN. . 77 MOVE -25 TO PROGRAM-SSHORT-BIN. . 4 78 PERFORM TEST-900. . 79 PERFORM TEST-1000. . 80 DISPLAY "MULTCU COBOL SOURCE ENDED." UPON CONSOLE. .
The Source window displays the source file or listing. The Source window has four parts, described below.
The suffix area is optional. To show the suffix area, enter SET SUFFIX ON. To hide the suffix area, enter SET SUFFIX OFF. You can also set it on or off with the Source Listing Suffix field in the Profile Settings panel.
The labeled header line for each window contains a scale and a line counter. If you scroll a window horizontally, the scale also scrolls to indicate the columns displayed in the window. The line counter indicates the line number at the top of a window and the total number of lines in that window. If you scroll a window vertically, the line counter reflects the top line number currently displayed in that window.
Refer to the following topics for more information related to the material discussed in this topic.
The Monitor window displays the names and values of variables selected by the SET AUTOMONITOR or MONITOR commands.
The following diagram shows the default Monitor window and highlights the parts of the Monitor window:
COBOL LOCATION: DTAM01 :> 109.1
Command ===> Scroll ===> PAGE
MONITOR -+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 7
******************************** TOP OF MONITOR *******************************
-----+----1----+----2----+- 1 --3----+----4--
0001 1 NUM1 0000000005
0002 2 NUM4 '1111' 2
0003 3 WK-LONG-FIELD-2 '123456790 223456790 323456790 423456790 5234
0004 3 56790 623456790 723456790 8234567890 9234567
0005 90 023456790 123456790 223456790 323456790 4
0006 4 23456790 5234567890 623456790 723456790 8234
0007 4 HEX-NUM1 X'ABCD 1234'
When you enter the MONITOR LIST, MONITOR QUERY, MONITOR DESCRIBE, and SET AUTOMONITOR commands, Debug Tool displays the output in the Monitor window. If this window is not open, Debug Tool opens it when you enter a MONITOR or SET AUTOMONITOR command.
While the MONITOR command can generate an unlimited amount of output, bounded only by your storage capacity, the Monitor window can display a maximum of only 1000 scrollable lines of output.
Refer to the following topics for more information related to the material discussed in this topic.
LOG 0----+----1----+----2----+----3----+----4----+----5----+----6 LINE: 6 OF 14 0007 MONITOR 0008 LIST PROGRAM-USHORT-BIN ; 0009 MONITOR 0010 LIST PROGRAM-SSHORT-BIN ; 0011 AT 75 ; 0012 AT 77 ; 0013 AT 79 ; 0014 GO ;
The Log window records and displays your interactions with Debug Tool.
At the beginning of a debug session, if you have specified any of the following files, the Log window displays messages indicating the beginning and end of any commands issued from these files:
If a global preferences file exists, the data set name of the global preferences file is displayed.
The following commands are not recorded in the Log window.
If SET INTERCEPT ON is in effect for a file, that file’s output also appears in the Log window.
You can optionally exclude STEP and GO commands from the log by specifying SET ECHO OFF.
Commands that can be used with IMMEDIATE, such as the SCROLL and WINDOW commands, are excluded from the Log window.
By default, the Log window keeps 1000 lines for display. The default value can be changed by one of the following methods:
The maximum number of lines is determined by the amount of storage available.
The labeled header line for each window contains a scale and a line counter. If you scroll a window horizontally, the scale also scrolls to indicate the columns displayed in the window. The line counter indicates the line number at the top of a window and the total number of lines in that window. If you scroll a window vertically, the line counter reflects the top line number currently displayed in that window.
The Memory window displays the contents of memory. The following figure highlights the parts of the Memory window.
MEMORY---1----+----2----+----3----+----4----+----5----+----6----+----7----+- 1 History: 24702630 2505A000 2 Base address: 265B1018 Amode: 31 +00000 265B1018 11C3D6C2 D6D34040 4011D3D6 C3C1E3C9 | .COBOL .LOCATI | +00010 265B1028 D6D57A12 D7D9D6C7 F1407A6E 40F4F44B | ON:.PROG1 :> 44. | +00020 265B1038 F1404040 40404040 40404040 40404040 | 1 | +00030 265B1048 40404040 40404040 40404040 40404040 | 6 | +00040 265B1058 40404040 40404040 40404040 40404040 | | +00050 265B1068 11C39694 94819584 117E7E7E 6E009389 | .Command.===>.li | +00060 265B1078 A2A340A2 A3969981 87854DA2 A399F16B | st storage(str1, | +00070 265B1088 F3F25D40 40404040 40404040 40404040 | 32) | 3 4 5
The following sections are collectively known as the memory dump area.
The maximum number of lines that the Memory window can display is limited to the size of the window. You can use the SCROLL DOWN and SCROLL UP commands to display additional memory.
Refer to the following topics for more information related to the material discussed in this topic.
If you have a preference as to the appearance or behavior of Debug Tool, you can set these options in a preferences file. You can modify the layout of the windows of the session panel, set PF keys to specific actions, or change the colors use in the session panel. Saving customized settings in a preferences file describes what you can specify in a preferences file and how to make Debug Tool use your preferences file.
If your site has preferences for all users to use, the system administrator can set these preferences in a global preferences file. When Debug Tool starts, it does the following steps:
Because of the order in which Debug Tool processes these files, any settings that you specify in your preferences and commands files can override settings in the global preferences file.
Debug Tool displays your source in the Source Window using a source, listing, or separate debug file, depending on how you prepared your program.
When you start Debug Tool, if your source is not displayed, see Changing which file appears in the Source window for instructions on how find and display the source.
If there is no debug data, you can display the disassembled code by entering the SET DISASSEMBLY command.
If your programs contain DB2® or CICS® code, you might need to use a different file. See Preparing a DB2 program or Preparing a CICS program for more information.
Refer to the following topics for more information related to the material discussed in this topic.
This topic describes several different ways of changing which file appears in the Source window. This topic assumes you already know the name of the source, listing, or separate debug file that you want to display. If you don't know the name of the file, see Displaying a list of compile units known to Debug Tool for suggestions on how to find the name of a file.
Before you change the file that appears in the Source window, make sure you understand how Debug Tool locates source, listing, and separate debug files by reading Appendix B. How does Debug Tool locate source, listing, or separate debug files?.
To change which file appears in the Source window, choose one of the following options:
In the Source Identification panel, you can associate the source, listing, or separate debug file that show in the Source window with their compile unit.
If you need to do this repeatedly, you can use the SET SOURCE ON commands generated in the Log window. You can save these commands in a file and reissue them with the USE command for future invocations of Debug Tool.
To point Debug Tool to several renamed files, you can use the SET DEFAULT LISTINGS command and specify the renamed files, separated by commas and enclosed in parenthesis. For example, to point Debug Tool to the files SVTRSAMP.TS99992.MYPROG, PGRSAMP.LLTEST.PROGA, and RRSAMP.CRTEST.PROGR, enter the following command:
SET DEFAULT LISTINGS (SVTRSAMP.TS99992.MYPROG, PGRSAMP.LLTEST.PROGA, RRSAMP.CRTEST.PROGR) ;
For C++ programs compiled with the DEBUG(FORMAT(DWARF)) compiler option, the information in this topic describes how to specify the location of the source file. If you compiled your program with the DEBUG(FORMAT(DWARF)) compiler option, you also need to access the .dbg file. If you move or rename this file, specify the new name or location with the EQADEBUG DD statement or code an EQAUEDAT user exit. If you are using UNIX® System Service's HFS file system, you cannot move the .dbg file.
You can enter a command or modify what is on the session panel in several areas, as shown in Figure 1 and Figure 2.
C LOCATION: MYID.SOURCE(ICFSSCU1) :> 89 Command ===> 1 Scroll ===> PAGE 2 MONITOR --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 1 OF 2 ******************************* TOP OF MONITOR ******************************** ----+----1----+----2----+----3----+----4---- 0001 1 VARBL1 10 0002 2 VARBL2 20 ****************************** BOTTOM OF MONITOR ****************************** SOURCE: ICFSSCU1 - 3 --+----2----+----3----+----4----+----5----+ LINE: 81 OF 96 81 main() . 82 { . 83 int VARBL1 = 10; . 4 84 int VARBL2 = 20; . 85 int R = 1; . 86 5 . 87 printf("--- IBFSSCC1 : BEGIN\n"); . 88 do { . 89 VARBL1++; . 90 printf("INSIDE PERFORM\n"); . 91 VARBL2 = VARBL2 - 2; . 92 R++; . LOG 6 --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 7 OF 15 0007 STEP ; 0008 AT 87 ; 0009 MONITOR 0010 LIST VARBL1 ; 0011 MONITOR 0012 LIST VARBL2 ; 0013 GO ; 7 0014 STEP ; 0015 STEP ;
COBOL LOCATION: PROG1 :> 44.1 Command ===> 1 Scroll ===> CSR 2 MONITOR -+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 2 ******************************* TOP OF MONITOR ******************************** ----+----1----+----2----+----3----+----4---- 0001 1 STR1 'ONE ' 0002 2 STR3 'THREE' ****************************** BOTTOM OF MONITOR ****************************** SOURCE: PROG1 - 3 -1----+----2----+----3----+----4----+----5----+ LINE: 43 OF 53 43 MOVE "ONE" TO STR1. MOVE "TWO" TO STR2. MOVE "THREE" TO S . 44 MOVE "FOUR" TO STR4. MOVE "FIVE" TO STR5. . 45 PERFORM UNTIL R = 9 . 4 46 MOVE "TOP" TO STR1 MOVE "BEG" TO STR2 MOVE "UP" TO STR3 . 47 ADD 1 TO VARBL1 . 48 SUBTRACT 2 FROM VARBL2 5 . 49 ADD 1 TO R . 50 MOVE "BOT" TO STR1 MOVE "END" TO STR2 MOVE "DOW" TO STR . 51 END-PERFORM. . 52 MOVE "DONE" TO STR1. MOVE "END" TO STR2. MOVE "FIN" TO ST . 53 STOP RUN. . ****************************** BOTTOM OF SOURCE ******************************* MEMOR 6 -+----2----+----3----+----4----+----5----+----6----+----7----+----8----+ History: 329D47DA 329D65CC 329D88AB 329D8000 329D90E8 8 Base address: 329D90E8 Amode: 31 +00000 329D90E8 D6D5C540 40000000 E3E6D640 40000000 | ONE ...TWO ... | +00010 329D90F8 E3C8D9C5 C5000000 00000000 00000000 | THREE........... | +00020 329D9108 00000000 00000000 00000000 00000000 | ................ | +00030 329D9118 00000000 00000000 00000000 00000000 | ................ | +00040 329D9128 00000000 00000000 00000000 00000000 | ................ | +00050 329D9138 00000000 00000000 00000000 00000000 | ................ | +00060 329D9148 00000000 00000000 00000000 00000000 | ................ | +00070 329D9158 00000000 00000000 00000000 00000000 | ................ | PF 1:ZOOM MEM 2:STEP 3:QUIT 4:SWAP 5:MEMORY 6:BREAK PF 7:UP 8:DOWN 9:GO 10:ZOOM SRC 11:ZOOM LOG 12:RETRIEVE
Refer to the following topics for more information related to the material discussed in this topic.
If you enter commands in more than one valid input area on the session panel and press Enter, the input areas are processed in the following order of precedence.
You can enter any Debug Tool command in the command field. You can also enter any TSO command by prefixing them with SYSTEM or TSO. Commands can be up to 48 SBCS characters or 23 DBCS characters in length.
If you need to enter a lengthy command, Debug Tool provides a command continuation character, the SBCS hyphen (-). When the current programming language is C and C++, you can also use the backslash (\) as a continuation character.
Debug Tool also provides automatic continuation if your command is not complete; for example, if the command was begun with a left brace ({) that has not been matched by a right brace (}). If you do need to continue your command, Debug Tool provides a MORE ===> prompt that is equivalent to another command line. You can continue to request additional command lines with continuation characters until you complete your command.
Refer to the following topics for more information related to the material discussed in this topic.
During your Debug Tool session, you can still access your base operating system using the SYSTEM command. The string following the SYSTEM command is passed on to your operating system. You can communicate with TSO in a TSO environment. For example, if you want to see a TSO catalog listing while in a debugging session, enter SYSTEM LISTC;.
When you are entering system commands, you must comply with the following:
SYSTEM ISPF;This starts ISPF and displays an ISPF panel on your host emulator screen that you can use to issue commands.
For CICS only: The SYSTEM command is not supported.
TSO is a synonym for the SYSTEM command. Truncation of the TSO command is not allowed.
You can type certain commands, known as prefix commands, in the prefix area of specific lines in the Source or Monitor window so that those commands affect only those lines. For example, you can type the AT command in the prefix area of line 8, press Enter, then Debug Tool sets a statement breakpoint only on line 8.
The following prefix commands can be entered in the prefix area of the Source window:
The following prefix commands can be entered in the prefix area of the Monitor window, including the automonitor section:
To enter a prefix command into the Source window, do the following steps:
To enter a prefix command into the Monitor window, do the following steps:
Refer to the following topics for more information related to the material discussed in this topic.
You can enter multiple commands and changes into the Memory window. Debug Tool processes the user input line by line, starting at the top of the Memory window, as described in the following list:
Certain commands are sensitive to the position of the cursor. These commands, called cursor-sensitive commands, include all those that contain the keyword CURSOR (AT CURSOR, DESCRIBE CURSOR, FIND CURSOR, LIST CURSOR, SCROLL...CURSOR, TRIGGER AT CURSOR, WINDOW...CURSOR).
To enter a cursor-sensitive command, type it on the command line, position the cursor at the location in your Source window where you want the command to take effect (for example, at the beginning of a statement or at a verb), and press Enter.
You can also issue cursor-sensitive commands by assigning them to PF keys.
Refer to the following topics for more information related to the material discussed in this topic.
The cursor-sensitive commands, as well as other full-screen tasks, can be issued more quickly by assigning the commands to PF keys. You can issue the WINDOW CLOSE, LIST, CURSOR, SCROLL TO, DESCRIBE ATTRIBUTES, RETRIEVE, FIND, WINDOW SIZE, and the scrolling commands (SCROLL UP, DOWN, LEFT, and RIGHT) this way. Using PF keys makes tasks convenient and easy.
Refer to the following topics for more information related to the material discussed in this topic.
The table below shows the initial PF key settings.
| PF key | Label | Definition | Use |
|---|---|---|---|
| PF1 | ? | ? | Getting online help for Debug Tool command syntax |
| PF2 | STEP | STEP | Stepping through or running your program |
| PF3 | QUIT | QUIT | Ending a full-screen debug session |
| PF4 | LIST | LIST | Displaying a list of compile units known to Debug Tool |
| PF4 | LIST | LIST variable_name | Displaying and monitoring the value of a variable |
| PF5 | FIND | IMMEDIATE FIND | Finding a string in a window |
| PF6 | AT/CLEAR | AT TOGGLE CURSOR | Setting breakpoints to halt your program at a line |
| PF7 | UP | IMMEDIATE UP | Scrolling through the physical windows |
| PF8 | DOWN | IMMEDIATE DOWN | Scrolling through the physical windows |
| PF9 | GO | GO | Stepping through or running your program |
| PF10 | ZOOM | IMMEDIATE ZOOM | Zooming a window to occupy the whole screen |
| PF11 | ZOOM LOG | IMMEDIATE ZOOM LOG | Zooming a window to occupy the whole screen |
| PF12 | RETRIEVE | IMMEDIATE RETRIEVE | Retrieving previous commands |
Refer to the following topics for more information related to the material discussed in this topic.
To retrieve the last command you entered, press PF12 (RETRIEVE). The retrieved command is displayed on the command line. You can make changes to the command, then press Enter to issue it.
To step backwards through previous commands, press PF12 to retrieve each command in sequence. If a retrieved command is too long to fit in the command line, only its last line is displayed.
Refer to the following topics for more information related to the material discussed in this topic.
You can use lines in the Log and Source windows to compose new commands.
To compose a command from lines in the Log or Source window, do the following steps:
Refer to the following topics for more information related to the material discussed in this topic.
You can navigate in any of the windows using the CURSOR command and the scrolling commands: SCROLL UP, DOWN, LEFT, RIGHT, TO, NEXT, TOP, and BOTTOM. You can also search for character strings using the FIND command, which scrolls you automatically to the specified string.
The window acted upon by any of these commands is determined by one of several factors. If you specify a window name (LOG, MEMORY, MONITOR, or SOURCE) when entering the command, that window is acted upon. If the command is cursor-oriented, the window containing the cursor is acted upon. If you do not specify a window name and the cursor is not in any of the windows, the window acted upon is determined by the settings of Default window and Default scroll amount under the Profile Settings panel.
Refer to the following topics for more information related to the material discussed in this topic.
To move the cursor back and forth quickly from the Monitor, Source, or Log window to the command line, use the CURSOR command. This command, and several other cursor-oriented commands, are highly effective when assigned to PF keys. After assigning the CURSOR command to a PF key, move the cursor by pressing that PF key. If the cursor is not on the command line when you issue the CURSOR command, it goes there. To return it to its previous position, press the CURSOR PF key again.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool has four logical windows, but can only display up to three physical windows at a time. You can alternate between the Memory window and the Log window by entering the WINDOW SWAP MEMORY LOG command on the command line. You can navigate through the physical windows by entering scroll commands.
Refer to the following topics for more information related to the material discussed in this topic.
You can scroll through the physical windows by using commands or PF keys. Either way, the placement of the cursor plays a key role in determining which physical window is affected by the command.
To scroll through a physical window by using commands, do the following steps:
If you scroll a window or area to the right or left, Debug Tool adjusts the scale in the window or area to indicate the columns displayed in the window. If you scroll a window up or down, the line counter reflects the top line number currently displayed in that window. In the Memory window, if you scroll up or down, all the sections of the memory dump area adjust to display the new information.
You can combine steps 2 and 3 above by using the command to indicate which physical window you want to scroll through. For example, if you want to scroll up 5 lines in the physical window that is displaying the Monitor window, you enter the command SCROLL UP 5 MONITOR.
To scroll through a physical window using PF keys, do the following steps:
If you do not move the cursor to a specific physical window, the default logical window is scrolled. To find out which logical window is the default logical window, enter the QUERY DEFAULT WINDOW command.
Refer to the following topics for more information related to the material discussed in this topic.
You can enlarge a physical window to full screen by using the WINDOW ZOOM command or a PF key. To enlarge a physical window by using the WINDOW ZOOM command, type in WINDOW ZOOM, followed by the name of the physical window you want to enlarge, then press Enter. To reduce the physical window back to its original size, enter the WINDOW ZOOM command again. For example, if you want to enlarge the physical window that is displaying the Monitor window, enter the command WINDOW ZOOM. To reduce the size of that physical window back to its original size, enter the command WINDOW ZOOM.
To enlarge a physical window by using a PF key, move the cursor into the physical window that you want to enlarge, then press the PF10 (ZOOM) key. For example, if you want to enlarge the physical window that is displaying the Source window, move your cursor somewhere into the Source window, then press the PF10 (ZOOM) key. To reduce the size of that physical window back to its original size, press the PF10 (ZOOM) key.
Refer to the following topics for more information related to the material discussed in this topic.
To display a particular line at the top of a window, use the SCROLL TO command with the statement numbers shown in the window prefix areas. Enter SCROLL TO n (where n is a line number) on the command line and press Enter.
For example, to bring line 345 to the top of the window, enter SCROLL TO 345 on the command line. The selected window is scrolled vertically so that your specified line is displayed at the top of that window.
You can search for strings in the Source, Monitor, or Log window. You can specify where to start the search, to search either forward or backward, and, for the Source window, the columns that are searched. The default window that is searched is the window specified by the SET DEFAULT WINDOW command or the Default window entry in your Profile Settings panel. The default direction for searches is forward. For the Source window, the default boundaries for columns are 1 to *, unless you specify a different set of boundaries with the SET FIND BOUNDS command.
To find a string within the default window using the default search direction, do the following steps:
If you want to repeat the previous search, hit the PF5 key.
Refer to the following topics for more information related to the material discussed in this topic.
The Debug Tool FIND command uses many of the same rules for beginning a search that the ISPF FIND command uses to begin its searches. Debug Tool begins a search in the first position after the cursor location.
If you reach the end, Debug Tool displays a message indicating you have reached the end. Repeat the FIND command by pressing the PF5 key and then the search starts from the top.
If you were searching backwards and you reach the beginning, Debug Tool displays a message indicating you have reached the beginning. Repeat the FIND command by pressing the PF5 key and the search begins from the end.
The string can contains any combination of characters, numbers, and symbols. However, if the string contains any of the following characters, it must be enclosed in quotation marks (") or apostrophes ('):
Use the following rules to determine whether to use quotation marks (") or apostrophes ('):
To find the same string in a different window, type in the command: FIND * window_name.
Type the FIND command with the string, then place the cursor in the Monitor window. Debug Tool searches the entire Monitor window, including the scrolled data in the Monitor value area, until the string is found or until the end of data is reached.
To find the same string in a different direction, enter the FIND * command with the string and the PREV or NEXT keyword. For example, the following command searches for the string "RecordDate" in the backwards direction:
FIND RecordDate PREV ;
You can specify that Debug Tool search through a limited number of columns in the Source window, which can be useful when you are searching through a very large source file and some text is organized in specific columns. You can specify the boundaries to use for the current search or for all searches. The column alignment of the source might not match the original source code. The column specifications for the FIND command are related to the scale shown in the Source window, not the original source code.
To specify the boundaries for the current search, enter the FIND command and specify the search string and the boundaries. For example, to search for "ABC" in columns 7 through 12, enter the following command:
FIND "ABC" 7 12;
To search for "VAR1" that begins in column 8 or any column after that, enter the following command:
FIND "VAR1" 8 *;
To search for "VAR1" beginning in column 1, enter the following command:
FIND "VAR1" 1;
To specify the default boundaries to use for all searches, enter the SET FIND BOUNDS command, specifying the left and right boundaries. After you enter the SET FIND BOUNDS command, every time you enter the FIND command without specifying boundaries, Debug Tool searches for the string you specified only within those boundaries. For example, to specify that you want Debug Tool to always search for text within columns 7 through 52, enter the following command:
SET FIND BOUNDS 7 52;Afterward, every time you enter the FIND command without specifying boundaries, Debug Tool searches only within columns 7 through 52.
To reset the boundaries to the default setting, which is 1 through *, enter the following command:
SET FIND BOUNDS;
Refer to the following topics for more information related to the material discussed in this topic.
To find a string in the backwards direction in a different window, enter the FIND command with the string, the PREV keyword, and the name of the window. For example, the following command searches for the string "EmployeeName" in the Log window:
FIND EmployeeName PREV LOG;
To find a COBOL paragraph name that begins in column 8, enter the following command:
FIND paraa 8;
Debug Tool will find only the string that starts in column 8.
To find a reference to a COBOL paragraph name in COBOL's Area B within columns 12 through 72, enter the following command:
FIND paraa 12 72;
Debug Tool will find only the string that starts and ends within columns 12 to 72.
After displaying different source files and scrolling, you can go back to the halted execution point by entering one of the following commands:
SET QUALIFY RESET
Q LOC
LIST %LINE
This topic describes the navigational aids available through the Memory window that are not available through other windows.
You can display the Memory window by doing one of the following options:
Refer to the following topics for more information related to the material discussed in this topic.
Every time you enter a new MEMORY command or use the G command, the current base address is moved to the right and down in the history area. The history area can hold up to eight base addresses. When the history area is full and you enter a new base address, Debug Tool removes the oldest base address (located at the bottom and right-most part of the history area) from the history area and puts the new base address on the top left. The history area is persistent in a debug session.
To use the history area to navigate through the Memory window, enter the G or g command over an address in the history area, then press Enter. Debug Tool displays the memory dump data starting with the new address. You can clear the history area by entering the CLEAR MEMORY command. You can remove an entry in the history area by typing over the entry with the R or r command.
Refer to the following topics for more information related to the material discussed in this topic.
You can use any of the following methods to specify a new base address:
If you enter the G command in the hexadecimal data columns, verify that the address is completely in one column and does not span across columns. For example, in the following screen, the hexadecimal addresses X'329E6470' appears in two locations:
MEMORY---1----+----2----+----3----+----4----+----5----+----6----+----7----+- History: 24702630 2505A000 Base address: 265B1018 Amode: 31 +00000 265B1018 40404040 40404040 40404040 40404040 | | +00010 265B1028 4040329E 64704040 40404040 40404040 | .. .. | +00020 265B1038 40404040 40404040 40404040 40404040 | | +00030 265B1048 40404040 40404040 40404040 40404040 | | +00040 265B1058 40404040 40404040 329E6470 40404040 | .... | +00050 265B1068 40404040 40404040 40404040 40404040 | | +00060 265B1078 40404040 40404040 40404040 40404040 | | +00070 265B1088 40404040 40404040 40404040 40404040 | |If you enter the G command over the second row, first column, Debug Tool tries to set the base address to X'4040329E'. If you enter the G command over the second row, second column, Debug Tool tries to set the base address to X'64704040'. If you want to set the base address to X'329E6470', do one of the following options:
A commands file is a convenient method of reproducing debug sessions or resuming interrupted sessions. Use one of the following methods to create a commands file:
When you create a commands file that might be used in an application program that was created with several different programming languages, you might want to use Debug Tool commands that are programming language neutral. The following guidelines can help you write commands that are programming language neutral:
For PL/I programs, if your commands file has sequence numbers in columns 73 through 80, you must enter the SET SEQUENCE ON command as the first command in the commands file or before you use the commands file. After you enter this command, Debug Tool does not interpret the data in columns 73 through 80 as a command. Later, if you want Debug Tool to interpret the data in columns 73 through 80 as a command, enter the command SET SEQUENCE OFF.
For C and C++ programs, if you use commands that reference blocks, the block names can differ if the same program is compiled with either the ISD or DWARF compiler option. If your program is compiled with the ISD compiler option, Debug Tool assigns block names in a sequential manner. If your program is compiled with the DWARF compiler option, Debug Tool assigns block names in a non-sequential manner. Therefore, the names might differ. If you switch compiler options, check the block names in commands you use in your commands file.
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool can record your commands and their generated output in a session log file. This allows you to record your session and use the file as a reference to help you analyze your session strategy. You can also use the log file as a command input file in a later session by specifying it as your primary commands file. This is a convenient method of reproducing debug sessions or resuming interrupted sessions.
The following appear as comments (preceded by an asterisk {*} in column 7 for COBOL programs, and enclosed in /* */ for C, C++, PL/I and assembler programs):
The default ddname associated with the Debug Tool session log file is INSPLOG. If you do not allocate a file with ddname INSPLOG, no default log file is created.
Refer to the following topics for more information related to the material discussed in this topic.
To create a permanent log of your debug session, first create a file with the following specifications:
Then, allocate the file to the DD name INSPLOG in the CLIST, JCL, or EXEC you use to run your program.
For COBOL only, if you want to subsequently use the session log file as a commands file, make the RECFM FB and the LRECL equal to 72. Debug Tool ignores everything after column 72 for file input during a COBOL debug session.
For CICS only, SET LOG OFF is the default. To start the log, you must use the SET LOG ON file command. For example, to have the log written to a data set named TSTPINE.DT.LOG , issue: SET LOG ON FILE TSTPINE.DT.LOG;.
Make sure the default of SET LOG ON is still in effect. If you have issued SET LOG OFF, output to the log file is suppressed. If Debug Tool is never given control, the log file is not used.
When the default log file (INSPLOG) is accessed during initialization, any existing file with the same name is overwritten. On MVS, if the log file is allocated with disposition of MOD, the log output is appended to the existing file. Entering the SET LOG ON FILE xxx command also appends the log output to the existing file.
If a log file was not allocated for your session, you can allocate one with the SET LOG command by entering:
SET LOG ON FILE logddn;
This causes Debug Tool to write the log to the file which is allocated to the DD name LOGDDN.
At any time during your session, you can stop information from being sent to a log file by entering:
SET LOG OFF;
To resume use of the log file, enter:
SET LOG ON;
The log file is active for the entire Debug Tool session.
Debug Tool keeps a log file in the following modes of operation: line mode, full-screen mode, and batch mode.
To record of how many times each line of your code was executed:
SET FREQUENCY ON;After you have entered the SET FREQUENCY ON command, your Source window is updated to show the current frequency count. Remember that this command starts the statistic gathering to display the actual count, so if your application has already executed a section of code, the data for these executed statements will not be available.
If you want statement counts for the entire program, issue:
GO ; LIST FREQUENCY * ;
which lists the number of times each statement is run. When you quit, the results are written to the Log file. You can issue the LIST FREQUENCY * at any time, but it will only display the frequency count for the currently active compile unit.
Refer to the following topics for more information related to the material discussed in this topic.
If you are debugging a compile unit that does not support automonitoring, you can use the SET AUTOMONITOR command to record the breakpoints encountered in that compile unit. After you enter the SET AUTOMONITOR ON command, Debug Tool records the location of each breakpoint that is encountered, as if you entered the QUERY LOCATION command.
To set or clear a line breakpoint, move the cursor over an executable line in the Source window and press PF6 (AT/CLEAR). You can temporarily turn off the breakpoint with DISABLE and turn it back on with ENABLE.
Refer to the following topics for more information related to the material discussed in this topic.
You can browse the source or set breakpoints in a load module that has not yet been loaded or in a program that is not yet active by using the following command:
SET QUALIFY CU load_spec ::> cu_spec ;
In this command, specify the name of the load module and CU in which you wish to set breakpoints. The load module is then implicitly loaded, if necessary, and a CU is created for the specified CU. The source for the specified CU is then displayed in the SOURCE window. You can then set statement breakpoints as desired.
When program execution is resumed because of a command such as GO or STEP, any implicitly loaded modules are deleted, all breakpoints in implicitly created CUs are suspended, and any implicitly created CUs are destroyed. If the CU is later created during normal program execution, the suspended breakpoints are reactivated.
If you use the SET SAVE BPS function to save and restore breakpoints, the breakpoints are saved and restored under the name of the first load module in the active enclave. Therefore, if you use the command SET QUALIFY CU to set breakpoints in programs that execute as part of different enclaves, the breakpoints that you set by using this command are not restored when run in a different enclave.
When Debug Tool processes (evaluates) a conditional expression and the data in one of the operands is invalid, the conditional expression becomes invalid. In this situation, Debug Tool stops and prompts you for a command. You have to enter the GO command to continue running your program. If you want to prevent Debug Tool from prompting you in this situation, enter the SET WARNING OFF command.
A conditional expression can become invalid for several reasons, including the following situations:
If an exception is raised during the evaluation of a conditional expression and SET WARNING is OFF, Debug Tool still stops, displays a message about the exception, and prompts you to enter a command.
The following example describes what happens when you use a field that has multiple definitions, with each definition having different attributes, as part of a conditional expression:
AT CHANGE WK-TEST-NUM
BEGIN;
IF WK-TEST-NUM = 10;
LIST 'WK-TEST-NUM IS 10';
ELSE;
GO;
END-IF;
End;AT CHANGE WK-TEST-NUM
BEGIN;
SET WARNING OFF;
IF WK-TEST-NUM = 10;
LIST 'WK-TEST-NUM IS 10';
ELSE;
BEGIN;
SET WARNING ON;
GO;
END;
END-IF;
SET WARNING ON;
END;
Now, when the value of the field WK-TEST-NUM is not 10 or it is not a numeric type, Debug Tool evaluates the conditional expression WK-TEST-NUM = 10 as false and runs the GO command. Debug Tool does not stop and prompt you for a command.
In this example, the display of warning messages about the conditional expression (WK-TEST-NUM = 10) was suppressed by entering the SET WARNING OFF command before the conditional expression was evaluated. After the conditional expression was evaluated, the display of warning messages was allowed by entering the SET WARNING ON command.
Carefully consider when you enter the SET WARNING OFF command because you might suppress the display of warning messages that might help you detect other problems in your program.
By default, when Debug Tool starts, none of your program has run yet (including C++ constructors and static object initialization).
Debug Tool defines a line as one line on the screen, commonly identified by a line number. A statement is a language construct that represents a step in a sequence of actions or a set of declarations. A statement can equal one line, it can span several lines, or there can be several statements on one line. The number of statements that Debug Tool runs when you step through your program depends on where hooks are placed.
To run your program up to the next hook, press PF2 (STEP). If you compiled your program with a combination of any of the following TEST or DEBUG compiler suboptions, STEP performs one statement:
To run your program until a breakpoint is reached, the program ends, or a condition is raised, press PF9 (GO).
The command STEP OVER runs the called function without stepping into it. If you accidentally step into a function when you meant to step over it, issue the STEP RETURN command that steps to the return point (just after the call point).
Refer to the following topics for more information related to the material discussed in this topic.
Debug Tool provides a set of commands (the PLAYBACK commands) that helps you record and replay the statements that you run while you debug your program. To record and replay statements, you need to do the following:
Each of these steps are described in more detail in the sections that follow.
The PLAYBACK ENABLE command includes a set of parameters to specify:
The PLAYBACK ENABLE command can be used to record the statements that you run for all compile units or for specific compile units. For example, you can record the statements that you run for compile units A, B, and C, where A, B, and C are existing compile units. Later, you can enter the PLAYBACK ENABLE command and specify that you want to record the statements that you run for all compile units. You can use an asterisk (*) to specify all current and future compile units.
The number of statements that Debug Tool can record depends on the following:
You cannot change the storage value after you have started recording. The more storage that you specify, the more statements that Debug Tool can record. After Debug Tool has filled all the available storage, Debug Tool puts information about the most recent statements over the oldest information. When the DATA parameter is in effect, the available storage fills more quickly.
You can use the DATA parameter with programs compiled with the SYM suboption of the TEST compiler option only if they are compiled with the following compilers:
Refer to the following topics for more information related to the material discussed in this topic.
The PLAYBACK START command notifies Debug Tool that you want to replay the statements that you recorded. This command suspends normal debugging; all breakpoints are suspended and you cannot use many Debug Tool commands. Debug Tool Reference and Messages provides a complete list of which commands you cannot use while you replay statements.
The initial direction is backward.
To replay the statements that you recorded, enter the STEP or RUNTO command. You can replay the statements you recorded until one of the following conditions is reached:
You can replay as far forward as the point where you entered the PLAYBACK START command. As you replay statements, you see only the statements that you recorded for those compile units you indicated you wanted to record. While you are replaying steps, you cannot modify variables. If the DATA parameter is in effect, you can access the contents of variables and expressions.
To change the direction that statements are replayed, enter the PLAYBACK FOWARD or PLAYBACK BACKWARD command. The initial direction is backward.
To stop replaying the statements that you recorded and resume normal debugging, enter the PLAYBACK STOP command. This command resumes normal debugging at the point where you entered the PLAYBACK START command. Debug Tool continues to record the statements that you run.
To stop recording the statements that you run and collecting additional information about your program, enter the PLAYBACK DISABLE command. This command can be used to stop recording the statements that you run in all or specific compile units. If you stop recording for one or more compile units, the data collected for those compile units is discarded. If you stop recording for all compile units, the PLAYBACK START command is no longer available.
Refer to the following topics for more information related to the material discussed in this topic.
You cannot modify the value of variables or storage while you are replaying statements.
When you replay statements, many Debug Tool commands are unavailable. Debug Tool Reference and Messages contains a complete list of all the commands that are not available.
If the DATA parameter is specified or defaulted for a COBOL compile unit that supports this parameter, you can access data defined in the following section of the DATA DIVISION:
You can also access special registers, except for the ADDRESS OF, LENGTH OF, and WHEN-COMPILED special registers. You can also access all the special registers supported by Debug Tool commands.
When you are replaying statements, many Debug Tool commands are available only if the following conditions are met:
You can use the QUERY PLAYBACK command to determine the compile units for which the DATA option is in effect.
Debug Tool Reference and Messages contains a complete list of all the commands that can be used when you specify the DATA parameter.
You can save settings, breakpoints, and monitor specifications from one debugging session and then restore them in a subsequent debugging session. You can save the following information:
If a deferred AT ENTRY breakpoint has not been encountered, it is not saved nor restored.
In most environments, Debug Tool uses specific default data set names to save these items so that it can automatically save and restore these items for you. In these environments, you must automatically restore the settings so that the SET RESTORE BPS AUTO and SET RESTORE MONITORS AUTO commands are in effect during Debug Tool initialization. There are some environments where you have to use the RESTORE command to restore these items manually.
In TSO, CICS (when you log on with your own ID), and UNIX System Services, the following default data set names are used:
In non-interactive mode (MVS batch mode without using full-screen mode through a VTAM terminal), you must include an INSPSAFE DD statement to indicate the data set that you want Debug Tool to use to save and restore the settings and an INSPBPM DD statement to indicate the data set that you want Debug Tool to use to save and restore the breakpoints and monitor and LDD specifications.
Use a sequential data set to save and restore the settings. Use a PDS or PDSE to save and restore the breakpoints and monitor and LDD specifications. We recommend that you use a PDSE to avoid having to compress the data set. Debug Tool uses a separate member to store the breakpoints, LDD data, and monitor specifications for each enclave. Debug Tool names the member the name of the initial load module in the enclave. If you want to discard all of the saved breakpoints, LDD data, and monitor specifications for an enclave, you can delete the corresponding member. However, do not alter the contents of the member.
To enable automatic saving and restoring, you must do the following steps:
SET SAVE SETTINGS AUTO; SET RESTORE SETTINGS AUTO;
SET SAVE BPS AUTO; SET RESTORE BPS AUTO; SET SAVE MONITORS AUTO; SET RESTORE MONITORS AUTO;
You must do step 4 (enabling automatic saving and restoring of settings) if you want to enable automatic restoring of breakpoints or monitor specifications.
The next time you start Debug Tool, the settings are automatically restored. If you are debugging the same program, the breakpoints and monitor specifications are also automatically restored.
Debug Tool provides a sample batch job (EQAWSVST member in hlq.SEQSAMP data set) that does these steps for you.
To disable automatic saving of breakpoints and monitors, you must ensure that the following settings are in effect:
To disable automatic saving of settings, you must ensure that the SET SAVE SETTINGS NOAUTO; setting is in effect.
To disable automatic restoring of breakpoints and monitors, you must ensure that the following settings are in effect:
To disable automatic restoring of settings, you must ensure that the SET RESTORE SETTINGS NOAUTO; setting is in effect.
If you disable the automatic saving of any of these values, the last saved data is still present in the appropriate data sets. Therefore, you can restore from these data sets. Be aware that this means you will restore values from the last time the data was saved which might not be from the last time you ran Debug Tool.
Automatic restoring is not supported in the following environments:
You can save and restore breakpoints, monitor, and LDD specifications by doing the following steps:
SET SAVE SETTINGS AUTO FILE mysetdsn;
SET SAVE BPS AUTO FILE mybpdsn; SET SAVE MONITORS AUTO;
The next time you start Debug Tool in one of these environments, you must use the following commands, in the sequence shown, at the beginning of your Debug Tool session.
SET SAVE SETTINGS AUTO FILE mysetdsn; RESTORE SETTINGS; SET SAVE BPS AUTO FILE mybpdsn; RESTORE BPS MONITORS;
You can put these commands into a user preferences file (INSPPREF).
Each time information is saved or restored, the following actions must take place:
Because each of these steps requires operating system services, the overall process can require a significant amount of elapsed time.
For saving and restoring settings, this process is done once when Debug Tool is activated and once when Debug Tool terminates. Therefore, unless Debug Tool is repeatedly activated and terminated, the process is not excessively time-consuming. However, for saving and restoring of breakpoints, monitors, or both, this process occurs once on entry to each enclave and once on termination of each enclave.
If your program consists of multiple enclaves or an enclave that is run repeatedly, this process might occur many times. In this case, if performance is a concern, you might want to consider disabling saving and restoring of breakpoints and monitors. If your program runs under CICS with DTCN and saving and restoring of breakpoints and monitors is not enabled (SET SAVE BPS NOAUTO;, SET SAVE MONITORS NOAUTO;, SET RESTORE BPS NOAUTO;, and SET RESTORE MONITORS NOAUTO; are in effect), breakpoints are saved and restored from a CICS Temporary Storage Queue which is less time-consuming than the standard method but does not preserve breakpoints across CICS restarts nor does it provide for saving and restoring of monitors.
Debug Tool can display the value of variables in the following ways:
If Debug Tool cannot display the value of a variable in its declared data type, see How Debug Tool handles characters that cannot be displayed in their declared data type.
Before you begin, determine if you want to change the format in which information is displayed. Variables that are areas and structures might be easier to read if they are arranged in a tabular format on the screen. To make changes to the format, do one of the following options:
To display the contents of a variable once, do one of the following options:
rightSide = (leftSide * leftSide) + (bottomSide * bottomSide);
When you add a variable to the Monitor window, you are monitoring the value of that variable. To add a variable to the Monitor window, do one of the following options:
MONITOR LIST variable-name;
Every time Debug Tool receives control or every time you enter a Debug Tool command that can affect the display, Debug Tool updates the value of variable-name in the Monitor window so that the Monitor window always displays the current value.
rightSide = (leftSide * leftSide) + (bottomSide * bottomSide);
Every time Debug Tool receives control or every time you enter a Debug Tool command that can affect the display, Debug Tool updates the value of leftSide in the Monitor window so that the Monitor window always displays the current value.
Refer to the following topics for more information related to the material discussed in this topic.
The command SET MONITOR DATATYPE ON displays the data type of the variables displayed in the Monitor window, including those in the automonitor section. The data type is ordinarily the type which was used in the declaration of the variable. The command SET MONITOR DATATYPE OFF disables the display of this information.
To display the value and data type of a variable in the Monitor window:
SET MONITOR DATATYPE ON;
MONITOR LIST variable-name;
Substitute the name of your variable name for variable-name. Debug Tool adds the variable to the Monitor window and displays the current value and data type of the variable.
SET AUTOMONITOR ON;
Debug Tool adds the variable or variables in the current statement to the automonitor section of the Monitor window and displays the current value and data type of the variable or variables.
SET AUTOMONITOR ON LOG;
Debug Tool adds the variable or variables to the automonitor section of the Monitor window, displays the current value and data type of the variable or variables, and saves that information in the log.
When you add a variable to the Monitor window, Debug Tool assigns the variable a reference number between 1 and 99. You can use the reference numbers to help you replace a variable in the Monitor window with another variable.
To replace a variable in the Monitor window with another variable, do the following steps:
MONITOR reference_number LIST variable-name;
You can specify only an existing reference number or a reference number that is one greater than the highest existing reference number.
As you step through a program, you might want to monitor variables that are on each statement as you run each statement. Manually adding variables to the Monitor window (as described in Adding variables to the Monitor window) before you run each statement can be time consuming. Debug Tool can automatically add the variables at each statement, before or after it is run; display the values of those variables, before or after the statement is run; then remove the variables from the Monitor window after you run the statement. To do this, use the SET AUTOMONITOR ON command.
Before you begin, make sure you understand how the SET AUTOMONITOR command works by reading How Debug Tool automatically adds variables to the Monitor window.
To add variables to the Monitor window automatically, do the following steps:
As you step through your program, Debug Tool displays the names and values of the variables in the automonitor section of the window.
Refer to the following topics for more information related to the material discussed in this topic.
To save the following information in the log file, enter the SET AUTOMONITOR ON LOG command:
The default option is NOLOG, which would not save the above information.
Each entry in the log file contains the breakpoint location within the program and the names and values of the variables in the statement. To stop saving this information in the log file and continue updating the automonitor section of the Monitor window, enter the SET AUTOMONITOR ON NOLOG command.
Refer to the following topics for more information related to the material discussed in this topic.
When you enter the SET AUTOMONITOR ON command, Debug Tool displays the line ********** AUTOMONITOR ********** at the bottom of the list of any monitored variables in the Monitor window, as shown in the following example:
COBOL LOCATION: DTAM01 :> 109.1
Command ===> Scroll ===> PAGE
MONITOR -+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 7
******************************** TOP OF MONITOR *******************************
----+----1----+----2----+----3----+----4----+
0001 1 NUM1 0000000005
0002 2 NUM4 '1111'
0003 3 WK-LONG-FIELD-2 '123456790 223456790 323456790 423456790 523
0004 456790 623456790 723456790 823456790 9234567
0005 90 023456790 123456790 223456790 323456790 4
0006 23456790 523456790 623456790 723456790 82345
0007 ********** AUTOMONITOR **********
The area below this line is called the automonitor section. Each time you enter the STEP command or a breakpoint is encountered, Debug Tool does the following tasks:
This behavior displays the value of the variables before Debug Tool runs the statement. If you want to see the value of the variables after Debug Tool runs the statement, you can enter the SET AUTOMONITOR ON PREVIOUS command. Debug Tool displays the line ********** AUTOMONITOR - PREVIOUS load-name ::> cu-name :> statement-id ********** at the bottom of the list of any monitored variables in the Monitor window. Each time you enter the STEP command or a breakpoint is encountered, Debug Tool does the following tasks:
If you want to see the value of the variables before and after Debug Tool runs the statement, you can enter the SET AUTOMONITOR ON BOTH command. Debug Tool displays the line ********** AUTOMONITOR load-name ::> cu-name :> statement-id ********** at the bottom of the list of any monitored variables in the Monitor window. Below this line, Debug Tool displays the names and values of the variables on the statement that Debug Tool runs next. Then, Debug Tool displays the line ***** Previous Statement load-name ::> cu-name :> statement-id ***** . Below this line, Debug Tool displays the names and values of the variables of the statement that Debug Tool just ran. Each time you enter the STEP command or a breakpoint is encountered, Debug Tool does the following tasks:
Refer to the following topics for more information related to the material discussed in this topic.
The example in this section assumes that the following two lines of COBOL code are to be run:
COMPUTE LOAN-AMOUNT = FUNCTION NUMVAL(LOAN-AMOUNT-IN). 1
COMPUTE INTEREST-RATE = FUNCTION NUMVAL(INTEREST-RATE-IN).
Before you run the statement in Line 1 , enter the following command:
SET AUTOMONITOR ON ;
The name and value of the variables LOAN-AMOUNT and LOAN-AMOUNT-IN are displayed in the automonitor section of the Monitor window. These values are the values of the variables before you run the statement.
Enter the STEP command. Debug Tool removes LOAN-AMOUNT and LOAN-AMOUNT-IN from the automonitor section of the Monitor window and then displays the name and value of the variables INTEREST-RATE and INTEREST-RATE-IN. These values are the values of the variables before you run the statement.
Refer to the following topics for more information related to the material discussed in this topic.
In the Monitor window, Debug Tool uses one of the following characters to indicate that a character cannot be displayed in its declared data type:
Characters that cannot be displayed in their declared data type can vary from code page to code page, but, in general, these are characters that have no corresponding symbol that can be displayed on a screen.
To be able to modify these characters, you can use the HEX and DEF prefix commands to help you verify which character you are modifying.
Refer to the following topics for more information related to the material discussed in this topic.
As described in How Debug Tool handles characters that cannot be displayed in their declared data type, if you want to modify characters that can't be displayed in their declared data type and ensure that the results are what you expected, do the following steps:
Refer to the following topics for more information related to the material discussed in this topic.
To monitor the value of the variable in columnar format, enter the SET MONITOR COLUMN ON command. The variable names that are displayed in the Monitor window are aligned to the same column and values are aligned to the same column. Debug Tool displays the Monitor value area scale under the header line for the Monitor window.
To display the value of the monitored variables wrapped in the Monitor window, enter the SET MONITOR WRAP ON command. To display the value of the monitored variables in a scrollable line, enter the SET MONITOR WRAP OFF command after you enter the SET MONITOR COLUMN ON command.
You can display the value of a variable in hexadecimal format by entering the LIST %HEX command or defining a PF key with the LIST %HEX command. For PL/I programs, to display the value of a variable in hexadecimal format, use the PL/I built-in function HEX. For more information about the PL/I HEX built-in function, see Enterprise PL/I for z/OS: Programming Guide. If you display a PL/I variable in hexadecimal format, you cannot edit the value of the variable by typing over the existing value in the Monitor window.
To display the value of a variable in hexadecimal format, enter one of the following commands, substituting variable-name with the name of your variable:
Debug Tool displays the value of the variable variable-name in hexadecimal format.
If you defined a PF key with the LIST %HEX command, do the following steps:
You cannot define a PF key with the PL/I HEX built-in function.
You can monitor the value of a variable in either the variable's declared data type or in hexadecimal format. To monitor the value of a variable in its declared data type, follow the instructions described in Adding variables to the Monitor window. If you monitor a PL/I variable in hexadecimal format by using the PL/I HEX built-in function, you cannot edit the value of the variable by typing over the existing value in the Monitor window. Instead of using the PL/I HEX built-in function, us the commands described in this topic.
To monitor the value of a variable or expression in hexadecimal format, do one of the following instructions:
MONITOR n HEX ;
Substitute n with the number in the monitor list that corresponds to the monitored expression that you would like to display in hexadecimal format.
MONITOR LIST (expression) HEX ;
Substitute expression with the name of the variable or a complex expression that you want to monitor.
Refer to the following topics for more information related to the material discussed in this topic.
You can modify the value of a variable or storage by using one of the following commands:
Each command is described in Debug Tool Reference and Messages.
Refer to the following topics for more information related to the material discussed in this topic.
To modify the value of a variable by typing over the existing value in the Monitor window, do the following steps:
Debug Tool modifies the variable or storage. The command that Debug Tool generated to modify the variable or storage is stored in the log file.
You can modify the value of a variable by typing over the existing value in the Monitor window, with the following exceptions:
If you type quotation marks (") or apostrophes (') in the Monitor value area, carefully verify that they comply with any applicable quotation rules.
If the Monitor window is closed before you enter the SET AUTOMONITOR ON command, Debug Tool opens the Monitor window and displays the name and value of the variables of statement you run in the automonitor section of the window.
If the Monitor window is open before you enter the SET AUTOMONITOR OFF command and you are watching the value of variables not monitored by SET AUTOMONITOR ON, the Monitor window remains open.
Debug Tool can display sections of memory through the Memory window. You can open the Memory window and have it display a specific section of memory by doing one of the following options:
If the Memory window is not displayed through a physical window, the base address is saved for usage later when the Memory window is displayed through a physical window.
To display the Memory window through a physical window, use the WINDOW SWAP MEMORY LOG command or PANEL LAYOUT command.
To display the Memory window through a physical window, use the WINDOW SWAP MEMORY LOG command or PANEL LAYOUT command.
Refer to the following topics for more information related to the material discussed in this topic.
You can type over the hexadecimal data area with hexadecimal characters (0-9, A-F, a-f). Debug Tool updates the memory with the value you typed in. If you modify the program instruction area of memory, Debug Tool does not do any STEP commands or stop at any AT breakpoints near the area where you modified memory. In addition, if you try to run the program, the results are unpredictable.
The character data column is the character representation of the data and is only for viewing purposes.
You can manage files while you are debugging by using the DESCRIBE ALLOCATIONS, ALLOCATE, and FREE commands. You cannot manage files while debugging CICS programs.
To view a current list of allocated files, enter the DESCRIBE ALLOCATIONS command. The following screen displays the command and sample output:
DESCRIBE ALLOCATIONS ; * Current allocations: * VOLUME CAT DISP OPEN DDNAME DSNAME * 1 --- 2 - 3 ------ 4 - 5 ----- 6 ------------------------------------------ * COD008 * SHR KEEP * EQAZSTEP BCARTER.TEST.LOAD * SMS004 * SHR KEEP SHARE.CEE210.SCEERUN * COD00B * OLD KEEP * INSPLOG BCARTER.DTOOL.LOGV * VIO NEW DELETE ISPCTL0 SYS02190.T085429.RA000.BCARTER.R0100269 * COD016 * SHR KEEP ISPEXEC BCARTER.MVS.EXEC * IPLB13 * SHR KEEP ISPF.SISPEXEC.VB * VIO NEW DELETE ISPLST1 SYS02190.T085429.RA000.BCARTER.R0100274 * IPLB13 * SHR KEEP * ISPMLIB ISPF.SISPMENU * SMS278 * SHR KEEP SHARE.ANALYZ21.SIDIMLIB * SHR89A * SHR KEEP SHARE.ISPMLIB * SMS25F * SHR KEEP * ISPPLIB SHARE.PROD.ISPPLIB * SMS891 * SHR KEEP SHARE.ISPPLIB * SMS25F * SHR KEEP SHARE.ANALYZ21.SIDIPLIB * IPLB13 * SHR KEEP ISPF.SISPPENU * IPLB13 * SHR KEEP SDSF.SISFPLIB * IPLB13 * SHR KEEP SYS1.SBPXPENU * COD002 * OLD KEEP * ISPPROF BCARTER.ISPPROF * NEW DELETE SYSIN TERMINAL * NEW DELETE SYSOUT TERMINAL * NEW DELETE SYSPRINT TERMINAL
The following list describes each column:
You can allocate files to an existing, cataloged data set by using the ALLOCATE command.
You can free an allocated file by using the FREE command.
By default, the DESCRIBE ALLOCATIONS command lists the files allocated by the current user. You can specify other parameters to list other system allocations, such as the data sets currently allocated to LINK list, LPA list, APF list, system catalogs, Parmlib, and Proclib. The Debug Tool Reference and Messages describes the parameters you must specify to list this information.
When an error message shows up in the Log window without a message ID, you can have the message ID show up as in:
EQA1807E The command element d is ambiguous.
Either modify your profile or use the SET MSGID ON command. To modify your profile, use the PANEL PROFILE command and set Show message ID numbers to YES by typing over the NO.
Refer to the following topics for more information related to the material discussed in this topic.
This topics describes what to do if you want to know which compile units are known to Debug Tool. This is helpful if you have forgotten the name of a compile unit or if the source, listing, or separate debug file has been moved or renamed since your program was compiled. Debug Tool can only display a source, listing, or separate debug file associated with known compile units.
To determine which compile units are known to Debug Tool, do one of the following options:
After you run the LIST NAMES CUS command, Debug Tool displays a list of compile units in the Log window. You can use this list to compose a SET QUALIFY CU command by typing in the words "SET QUALIFY CU" over the name of a compile unit. Then press Enter. Debug Tool displays the command constructed from the words that you typed in and the name of the compile unit. Press Enter again to run the command.
For example, after you enter the LIST NAMES CUS command, Debug Tool displays the following lines in the Log window:
USERID.MFISTART.C(CALC) USERID.MFISTART.C(PUSHPOP) USERID.MFISTART.C(READTOKN)
If you type "SET QUALIFY CU" over the last line, then press Enter, Debug Tool composes the following command into the command line: SET QUALIFY CU "USERID.MFISTART.C(READTOKN)". Press Enter and Debug Tool runs the command.
This method saves keystrokes and reduces errors in long commands.
Refer to the following topics for more information related to the material discussed in this topic.
During an interactive Debug Tool session, you can request an attention interrupt, if necessary. For example, you can stop what appears to be an unending loop, stop the display of voluminous output at your terminal, or stop the execution of the STEP command.
An attention interrupt should not be confused with the ATTENTION condition. If you set an AT OCCURRENCE or ON ATTENTION, the commands associated with that breakpoint are not run at an attention interrupt.
Language Environment TRAP and INTERRUPT run-time options should both be set to ON in order for attention interrupts that are recognized by the host operating system to be also recognized by Language Environment. The test_level suboption of the TEST run-time option should not be set to NONE.
An attention interrupt key is not supported in the following environment and debugging modes:
For MVS only: For C, when using an attention interrupt, use SET INTERCEPT ON FILE stdout to intercept messages to the terminal. This is required because messages do not go to the terminal after an attention interrupt.
For the Dynamic Debug facility only: The Dynamic Debug facility supports attention interrupts only for programs that have compiled-in hooks.
The correct key might not be marked ATTN on every keyboard. Often the following keys are used:
When you request an attention interrupt, control is given to Debug Tool:
Refer to the following topics for more information related to the material discussed in this topic.
When you have finished debugging your program, you can end your full-screen debug session by using one of the following methods:
If you are debugging a CICS non-Language Environment assembler or non-Language Environment COBOL program, QUIT ends Debug Tool and the task ends with an ABEND 4038.
If you are debugging a CICS non-Language Environment assembler or non-Language Environment COBOL program, QUIT ends Debug Tool and the task ends with an ABEND 4038.
Refer to the following topics for more information related to the material discussed in this topic.