Rational Developer for System z, Version 7.6

Debugging a program in full-screen mode: introduction

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:

  1. Compiling or assembling your program with the proper compiler options
  2. Starting Debug Tool
  3. After you start Debug Tool, you will see the full-screen mode interface. The Debug Tool full screen interface describes the parts of the interface. Then you can do any of the following tasks:
  4. Stopping Debug Tool

Each topic directs you to other topics that provide more information.

Compiling or assembling your program with the proper compiler options

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:

Compiler options that you can use with C programs
The TEST and DEBUG compiler options provide suboptions to refine debugging capabilities. Use the defaults to gain maximum debugging capability.
Compiler options that you can use with C++ programs
The TEST and DEBUG compiler options provide suboptions to refine debugging capabilities. Use the defaults to gain maximum debugging capability.
Compiler options that you can use with COBOL programs
The TEST compiler option provides suboptions to refine debugging capabilities. Some suboptions are used only with a specific version of COBOL. This chapter assumes the use of suboptions available to all versions of COBOL.
Compiler options that you can use with non-Language Environment COBOL programs
When you compile your OS/VS COBOL program, the following options are required: NOTEST, SOURCE, DMAP, PMAP, VERB, XREF, NOLST, NOBATCH, NOSYMDMP, NOCOUNT.

When you compile your VS COBOL II program, the following options are required: NOOPTIMIZE, NOTEST, SOURCE, MAP, XREF, and either LIST or OFFSET.

Compiler options that you can use use with PL/I programs
The TEST compiler option provides suboptions to refine debugging capabilities. Some suboptions are used only with a specific version of PL/I. This chapter assumes the use of suboptions available to all versions of PL/I, except for PL/I for MVS or OS PL/I compilers, which must also specify the SOURCE suboption.
Assembler options that you can use with assembler programs
When you assemble your program, you must specify the ADATA option. Specifying this option generates a SYSADATA file, which the EQALANGX postprocessor needs to create a debug file.

See Planning your debug session for instructions on how to choose the correct combination for your situation.

Starting Debug Tool

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:

The Debug Tool full screen interface

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:

Monitor window
Variables and their values, which you can display by entering the SET AUTOMONITOR ON and MONITOR commands.
Source window
The source or listing file, which Debug Tool finds or you can specify where to find it.
Log window
The record of your interactions with Debug Tool and the results of those interactions.
Memory window
A section of memory, which you can display by entering the MEMORY command.

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

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.

Running your program to a specific line

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.

Setting a breakpoint

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.

Displaying the value of a variable

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:

Refer to the following topics for more information related to the material discussed in this topic.

Displaying memory through the Memory window

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.

Changing the value of a variable

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.

Skipping a breakpoint

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.

Clearing a breakpoint

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.

Recording and replaying statements

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.

Table 4. The sequence in which statements are replayed.
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:

  1. Enter the PLAYBACK START command.
  2. To move backward one statement, enter the STEP command.
  3. Repeat step 2 as many times as you can to replay another statement.
  4. To move forward (from the current statement to the next statement), enter the PLAYBACK FORWARD command.
  5. Enter the STEP command to replay another statement.
  6. Repeat step 5 as many times as you want to replay another statement.
  7. To move backward, enter the PLAYBACK BACKWARD command.

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.

Stopping Debug Tool

To stop your debug session, do the following steps:

  1. Enter the QUIT command.
  2. In response to the message to confirm your request to stop your debug session, press "Y" and then press Enter.

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.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)