Debug Tooluser

Debug Tool for z/OS
Debug Tool Utilities and Advanced Functions for

z/OS
User’s Guide
Version 4 Release 1
SC18-9012-00
Debug Tool for z/OS
Debug Tool Utilities and Advanced Functions for
z/OS
User’s Guide
Version 4 Release 1
SC18-9012-00
Note!
Before using this information and the product it supports, be sure to read the
general information under “Notices” on page 311.
First Edition (September 2003)

This edition applies to Debug Tool for z/OS, Version 4 Release 1 (Program Number 5655-L24), which supports the
following compilers:
v AD/Cycle C/370 Version 1 Release 2 (Program Number 5688-216)
v C/C++ for MVS/ESA Version 3 (Program Number 5655-121)
v C/C++ feature of OS/390 (Program Number 5647-A01)
v C/C++ feature of z/OS (Program Number 5694-A01)
v VS COBOL II Version 1 Release 3 and Version 1 Release 4 (Program Numbers 5688-958, 5688-023) - with
limitations
v COBOL/370 Version 1 Release 1 (Program Number 5688-197)
v COBOL for MVS & VM Version 1 Release 2 (Program Number 5688-197)
v COBOL for OS/390 & VM Version 2 (Program Number 5648-A25)
v Enterprise COBOL for z/OS and OS/390 Version 3 (Program Number 5655-G53)
v High Level Assembler for MVS & VM & VSE (Program Number 5696-234)
v OS PL/I Version 2 Release 1, Version 2 Release 2, Version 2 Release 3 (Program Numbers 5688-909, 5688-910) -
with limitations
v PL/I for MVS & VM Version 1 Release 1 (Program Number 5688-235)
v VisualAge PL/I for OS/390 Version 2 Release 2 (Program Number 5655-B22)
v Enterprise PL/I for z/OS and OS/390 Version 3 (Program Number 5655-H31)
Parts of this edition apply to Debug Tool Utilities and Advanced Functions, Version 4 Release 1 (Program Number
5655–L23).
This edition also applies to all subsequent releases and modifications until otherwise indicated in new editions or
technical newsletters.
You can order publications online at www.ibm.com/shop/publications/order, or order by phone or fax. IBM
Software Manufacturing Solutions takes publication orders between 8:30 a.m. and 7:00 p.m. Eastern Standard Time
(EST). The phone number is (800)879-2755. The fax number is (800)445-9269.
You can find out more about Debug Tool by visiting the IBM Web site for Debug Tool at:
http://www.ibm.com/software/awdtools/debugtool
© Copyright International Business Machines Corporation 1992, 2003. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
About this document . . . . . . . . . ix Chapter 4. Planning your debug
Who might use this document . . . . . . . . ix session and collecting resources . . . 21
Accessing z/OS licensed documents on the Internet ix Do you want to compile your program with hooks? 21
Using LookAt to look up message explanations. . . x Do you want to reference variables during your
How this document is organized . . . . . . . x debug session? . . . . . . . . . . . . . 22
Terms used in this document . . . . . . . . xii Do you want full debug capability or smaller
How to read syntax diagrams . . . . . . . . xiii application size and higher performance? . . . . 22
Symbols . . . . . . . . . . . . . . xiii When do you want to start Debug Tool and when
Syntax items . . . . . . . . . . . . . xiii do you want it to gain control? . . . . . . . . 22
Syntax examples . . . . . . . . . . . xiv Do you want to use Debug Tool in full-screen mode,
How to send your comments . . . . . . . . xv in batch mode, or in remote debug mode? . . . . 23
Collecting your resources . . . . . . . . . . 23
Part 1. Getting started with Debug
Tool . . . . . . . . . . . . . . . . 1 Chapter 5. Preparing a COBOL
program . . . . . . . . . . . . . . 25
Chapter 1. Debug Tool: overview . . . . 3 Compiling a COBOL program with the TEST
compiler option . . . . . . . . . . . . . 25
Debug Tool interfaces . . . . . . . . . . . 4
Compiling an OS/VS COBOL program . . . . . 27
Full-screen mode . . . . . . . . . . . . 5
Batch mode . . . . . . . . . . . . . . 5
Remote debug mode . . . . . . . . . . . 5 Chapter 6. Preparing a PL/I program . . 29
Compiling a PL/I program with the TEST compiler
Chapter 2. Debug Tool Utilities and option . . . . . . . . . . . . . . . . 29
Compiling a Enterprise PL/I program on an HFS
Advanced Functions: introduction . . . 7 file system . . . . . . . . . . . . . . . 29
Debug Tool Utilities: creating and managing setup Compiling a PL/I for MVS & VM or OS PL/I
files . . . . . . . . . . . . . . . . . 8 program . . . . . . . . . . . . . . . 30
Debug Tool Utilities: converting, compiling, and
linking . . . . . . . . . . . . . . . . 8
Debug Tool Utilities: preparing assembler programs 8
Chapter 7. Preparing a C program . . . 31
Debug Tool Utilities: conducting code coverage . . . 8 Compiling a C program with the TEST compiler
Debug Tool Utilities: preparing IMS run-time option . . . . . . . . . . . . . . . . 31
environment . . . . . . . . . . . . . . 9 Compiling a C program on an HFS file system . . 32
Starting Debug Tool Utilities . . . . . . . . . 9 Rules for the placement of hooks in functions and
nested blocks . . . . . . . . . . . . . . 33
Rules for placement of hooks in statements and
Chapter 3. Debugging a program in path points . . . . . . . . . . . . . . 33
full-screen mode: introduction . . . . 11 Compiling your C program with the #pragma
Compiling or assembling your program with the statement . . . . . . . . . . . . . . . 33
proper compiler options . . . . . . . . . . 11
Starting Debug Tool . . . . . . . . . . . 12 Chapter 8. Preparing a C++ program . . 35
Stepping through a program . . . . . . . . . 13
Compiling a C++ program with the TEST compiler
Recording and replaying statements . . . . . . 13
option . . . . . . . . . . . . . . . . 35
Running your program to a specific line . . . . . 14
Compiling a C++ program on an HFS file system . 35
Setting a breakpoint . . . . . . . . . . . 15
Rules for the placement of hooks in functions and
Displaying the value of a variable . . . . . . . 15
nested blocks . . . . . . . . . . . . . . 36
Changing the value of a variable . . . . . . . 16
Rules for the placement of hooks in statements and
Skipping a breakpoint . . . . . . . . . . . 16
path points . . . . . . . . . . . . . . 36
Clearing a breakpoint . . . . . . . . . . . 17
Stopping Debug Tool . . . . . . . . . . . 17
Chapter 9. Preparing an assembler
program . . . . . . . . . . . . . . 37
Part 2. Preparing your program for Before you begin . . . . . . . . . . . . 37
debugging . . . . . . . . . . . . 19 Assembling your program . . . . . . . . . 38
Creating the EQALANGX file . . . . . . . . 38
Assembling your program and creating
EQALANGX . . . . . . . . . . . . . . 39
© Copyright IBM Corp. 1992, 2003 iii

Link-editing your program . . . . . . . . . 39 Specifying TEST run-time option with #pragma
runopts in C and C++ . . . . . . . . . . . 67
Chapter 10. Preparing a DB2 program 41
Precompiling DB2 programs for debugging . . . . 41 Chapter 16. Starting Debug Tool from a
Compiling DB2 programs for debugging . . . . 41 program . . . . . . . . . . . . . . 69
Linking DB2 programs for debugging . . . . . 42 Starting Debug Tool with CEETEST . . . . . . 69
Binding DB2 programs for debugging . . . . . 43 Usage notes . . . . . . . . . . . . . 70
Example: using CEETEST to start Debug Tool from
Chapter 11. Preparing a DB2 stored C/C++ . . . . . . . . . . . . . . . . 71
procedures program . . . . . . . . . 45 Example: using CEETEST to start Debug Tool from
COBOL . . . . . . . . . . . . . . . . 72
Example: using CEETEST to start Debug Tool from
Chapter 12. Preparing a CICS program 47
PL/I . . . . . . . . . . . . . . . . . 73
Link-editing CEEBXITA into your program . . . . 47
Starting Debug Tool with PLITEST . . . . . . 75
Creating and storing a DTCN profile . . . . . . 47
Starting Debug Tool with the __ctest() function . . 75
Sharing DTCN repository profile items among CICS
systems . . . . . . . . . . . . . . . . 51
Chapter 17. Starting your program
Chapter 13. Preparing an IMS program 53 when starting a debug session . . . . 79
Creating setup file for your IMS program by using Starting Debug Tool under CICS . . . . . . . 79
Debug Tool Utilities . . . . . . . . . . . 54 Starting Debug Tool under MVS in TSO . . . . . 79
Creating a private message region or running a Starting Debug Tool in batch . . . . . . . . 81
BMP program . . . . . . . . . . . . 54
Setting up the run-time options for your IMS Chapter 18. Starting a full-screen
Version 8 TM program by using Debug Tool Utilities 54 debug session . . . . . . . . . . . 83
Linking IMS programs for debugging . . . . . 55
Chapter 19. Special cases for starting
Part 3. Starting Debug Tool . . . . . 57 Debug Tool . . . . . . . . . . . . . 85
Starting a debugging session in full-screen mode
Chapter 14. Starting Debug Tool from through a VTAM terminal . . . . . . . . . 85
the Debug Tool Utilities . . . . . . . 59 Starting Debug Tool from DB2 stored procedures:
troubleshooting . . . . . . . . . . . . . 85
Creating the setup file . . . . . . . . . . . 59
Starting Debug Tool under CICS . . . . . . . 86
Editing an existing setup file . . . . . . . . 59
Using DTCN to start Debug Tool for CICS programs 87
Copying information into a setup file from an
How to end your CICS debugging session . . . 87
existing JCL . . . . . . . . . . . . . . 60
Using CEEUOPT to start Debug Tool under CICS . 88
Entering file allocation statements, run-time options,
Using compiler directives to start Debug Tool under
and program parameters . . . . . . . . . . 60
CICS . . . . . . . . . . . . . . . . 88
Saving your setup file . . . . . . . . . . . 61
Using CEDF to start Debug Tool under CICS . . . 88
Starting your program . . . . . . . . . . . 62
Chapter 15. Starting Debug Tool by Part 4. Debugging your programs in

using the TEST run-time option . . . . 63 full-screen mode . . . . . . . . . 91
Special considerations while using the TEST
run-time option . . . . . . . . . . . . . 63 Chapter 20. Using full-screen mode:
Defining TEST suboptions in your program . . 63 overview . . . . . . . . . . . . . . 93
Suboptions and NOTEST . . . . . . . . . 63 Debug Tool session panel . . . . . . . . . . 93
Implicit breakpoints . . . . . . . . . . 64 Session panel header . . . . . . . . . . 94
Primary commands file and USE file . . . . . 64 Source window . . . . . . . . . . . . 96
Running in batch mode . . . . . . . . . 64 Monitor window . . . . . . . . . . . 97
Starting Debug Tool at different points . . . . 64 Log window . . . . . . . . . . . . . 98
Session log . . . . . . . . . . . . . 65 Displaying the source or listing file . . . . . . 98
Precedence of Language Environment run-time Entering commands on the session panel . . . . 100
options . . . . . . . . . . . . . . . . 65 Order in which Debug Tool accepts commands
Example: TEST run-time options . . . . . . . 66 from the session panel . . . . . . . . . 101
Specifying additional run-time options with COBOL Using the session panel command line . . . . 101
II and PL/I programs . . . . . . . . . . . 67 Issuing system commands . . . . . . . . 101
Specifying the STORAGE run-time option . . . 67 Using prefix commands on specific lines or
Specifying the TRAP(ON) run-time option . . . 67 statements . . . . . . . . . . . . . 102
iv Debug Tool Version 4 Release 1 User’s Guide

Using commands that are sensitive to the cursor Chapter 22. Debugging a PL/I program
position . . . . . . . . . . . . . . 102 in full-screen mode . . . . . . . . . 133
Using Program Function (PF) keys to enter Example: sample PL/I program for debugging . . 133
commands . . . . . . . . . . . . . 102 Halting when certain PL/I functions are called . . 136
Initial PF key settings . . . . . . . . . 103 Modifying the value of a PL/I variable . . . . . 136
Retrieving previous commands . . . . . . 103 Halting on a PL/I line only if a condition is true 137
Retrieving commands from the Log and Source Debugging PL/I when only a few parts are
windows . . . . . . . . . . . . . . 104 compiled with TEST . . . . . . . . . . . 137
Navigating through Debug Tool session panel Displaying raw storage in PL/I . . . . . . . 138
windows . . . . . . . . . . . . . . . 104 Getting a PL/I function traceback . . . . . . 138
Moving the cursor between windows . . . . 104 Tracing the run-time path for PL/I code compiled
Scrolling the windows . . . . . . . . . 105 with TEST . . . . . . . . . . . . . . 138
Scrolling to a particular line number. . . . . 105 Finding unexpected storage overwrite errors in
Finding a string in a window . . . . . . . 105 PL/I . . . . . . . . . . . . . . . . 140
Changing which source file appears in the Halting before calling an undefined program in
Source window . . . . . . . . . . . . 105 PL/I . . . . . . . . . . . . . . . . 140
Displaying the line at which execution halted 106
Recording your debug session in a log file . . . 107
Creating the log file . . . . . . . . . . 107
Chapter 23. Debugging a C program
Recording how many times each source line in full-screen mode . . . . . . . . . 141
runs . . . . . . . . . . . . . . . 108 Example: sample C program for debugging . . . 141
Recording the breakpoints encountered . . . . 108 Halting when certain functions are called in C . . 144
Setting breakpoints to halt your program at a line 109 Modifying the value of a C variable . . . . . . 144
Stepping through or running your program . . . 109 Halting on a line in C only if a condition is true 145
Recording and replaying statements . . . . . 109 Debugging C when only a few parts are compiled
Displaying and monitoring the value of a variable 112 with TEST . . . . . . . . . . . . . . 145
One-time display of the value of variables . . . 112 Capturing C output to stdout . . . . . . . . 146
Monitoring the value of variables . . . . . . 113 Calling a C function from Debug Tool . . . . . 146
Displaying values in hexadecimal format . . . 114 Displaying raw storage in C . . . . . . . . 147
Monitoring the value of variables in Debugging a C DLL . . . . . . . . . . . 147
hexadecimal format . . . . . . . . . . 114 Getting a function traceback in C . . . . . . . 147
Modifying variables . . . . . . . . . . 115 Tracing the run-time path for C code compiled
Opening and closing the Monitor window . . . 116 with TEST . . . . . . . . . . . . . . 148
Managing file allocations . . . . . . . . . 116 Finding unexpected storage overwrite errors in C 148
Displaying error numbers for messages in the Log Finding uninitialized storage errors in C . . . . 149
window . . . . . . . . . . . . . . . 117 Halting before calling a NULL C function . . . . 150
Finding a renamed source, listing, or separate
debug file . . . . . . . . . . . . . . 117 Chapter 24. Debugging a C++ program
Requesting an attention interrupt during interactive in full-screen mode . . . . . . . . . 151
sessions . . . . . . . . . . . . . . . 118 Example: sample C++ program for debugging . . 151
Ending a full-screen debug session . . . . . . 119 Halting when certain functions are called in C++ 155
Modifying the value of a C++ variable . . . . . 155
Chapter 21. Debugging a COBOL Halting on a line in C++ only if a condition is true 156
program in full-screen mode . . . . . 121 Viewing and modifying data members of the this
Example: sample COBOL program for debugging 121 pointer in C++ . . . . . . . . . . . . . 157
Halting when certain routines are called in COBOL 124 Debugging C++ when only a few parts are
Modifying the value of a COBOL variable . . . . 125 compiled with TEST . . . . . . . . . . . 157
Halting on a COBOL line only if a condition is true 126 Capturing C++ output to stdout . . . . . . . 158
Debugging COBOL when only a few parts are Calling a C++ function from Debug Tool . . . . 158
compiled with TEST . . . . . . . . . . . 127 Displaying raw storage in C++ . . . . . . . 158
Capturing COBOL I/O to the system console. . . 127 Debugging a C++ DLL . . . . . . . . . . 158
Displaying raw storage in COBOL . . . . . . 128 Getting a function traceback in C++ . . . . . . 159
Getting a COBOL routine traceback . . . . . . 128 Tracing the run-time path for C++ code compiled
Tracing the run-time path for COBOL code with TEST . . . . . . . . . . . . . . 159
compiled with TEST . . . . . . . . . . . 128 Finding unexpected storage overwrite errors in
Generating a COBOL run-time paragraph trace . . 129 C++ . . . . . . . . . . . . . . . . 160
Finding unexpected storage overwrite errors in Finding uninitialized storage errors in C++ . . . 160
COBOL . . . . . . . . . . . . . . . 130 Halting before calling a NULL C++ function . . . 161
Halting before calling an invalid program in
COBOL . . . . . . . . . . . . . . . 130
Contents v
Chapter 25. Debugging an assembler COBOL command format . . . . . . . . 188
program in full-screen mode . . . . . 163 COBOL compiler options in effect for Debug
Example: sample assembler program for debugging 163 Tool commands . . . . . . . . . . . 188
Defining a compilation unit as assembler and COBOL reserved keywords . . . . . . . . 189
loading debug data . . . . . . . . . . . 166 Using COBOL variables with Debug Tool . . . . 189
Defining a compilation unit in a different load Accessing COBOL variables . . . . . . . 189
module as assembler . . . . . . . . . . . 167 Assigning values to COBOL variables . . . . 189
Multiple compilation units in a single assembly 167 Example: assigning values to COBOL variables 189
Halting when certain assembler routines are called 168 Displaying values of COBOL variables . . . . 191
Displaying and modifying the value of assembler Using DBCS characters in COBOL . . . . . . 191
variables or storage . . . . . . . . . . . 168 %PATHCODE values for COBOL . . . . . . . 192
Halting on a line in assembler only if a condition is Declaring session variables in COBOL . . . . . 193
true . . . . . . . . . . . . . . . . 169 Debug Tool evaluation of COBOL expressions . . 193
Debugging assembler when debug data is only Displaying the results of COBOL expression
available for a few parts . . . . . . . . . . 169 evaluation . . . . . . . . . . . . . 194
Getting an assembler routine traceback . . . . . 170 Using constants in COBOL expressions . . . . 194
Finding unexpected storage overwrite errors in Using Debug Tool functions with COBOL . . . . 195
assembler . . . . . . . . . . . . . . 170 Using %HEX with COBOL . . . . . . . . 195
Using the %STORAGE function with COBOL 195
Qualifying variables and changing the point of
Chapter 26. Customizing your view in COBOL . . . . . . . . . . . . 195
full-screen session . . . . . . . . . 171 Qualifying variables in COBOL . . . . . . 195
Defining PF keys . . . . . . . . . . . . 171 Changing the point of view in COBOL . . . . 197
Defining a symbol for commands or other strings 171 Considerations when debugging a COBOL class 197
Customizing the layout of windows on the session Debugging VS COBOL II programs . . . . . . 198
panel . . . . . . . . . . . . . . . . 172 Finding the listing of a VS COBOL II program 198
Opening and closing session panel windows 173
Resizing session panel windows . . . . . . 173 Chapter 29. Debugging PL/I programs 199
Zooming a window to occupy the whole screen 173
Debug Tool subset of PL/I commands . . . . . 199
Customizing session panel colors . . . . . . . 174
PL/I language statements . . . . . . . . . 199
Customizing profile settings . . . . . . . . 175
%PATHCODE values for PL/I . . . . . . . . 200
Saving customized settings in a preferences files 177
PL/I conditions and condition handling . . . . 201
Entering commands in PL/I DBCS freeform format 202
Part 5. Debugging your programs Initializing Debug Tool when TEST(ERROR, ...)
by using Debug Tool commands . 179 run-time option is in effect . . . . . . . . . 202
Debug Tool enhancements to LIST STORAGE PL/I
command . . . . . . . . . . . . . . 202
Chapter 27. Entering Debug Tool PL/I support for Debug Tool session variables . . 202
commands . . . . . . . . . . . . 181 Accessing PL/I program variables . . . . . . 202
Using uppercase, lowercase, and DBCS in Debug Accessing PL/I structures . . . . . . . . . 203
Tool commands . . . . . . . . . . . . 181 Debug Tool evaluation of PL/I expressions . . . 204
DBCS . . . . . . . . . . . . . . . 181 Supported PL/I built-in functions . . . . . . 204
Character case and DBCS in C and C++ . . . 182 Using SET WARNING PL/I command with
Character case in COBOL and PL/I . . . . . 182 built-in functions . . . . . . . . . . . 204
Abbreviating Debug Tool keywords . . . . . . 182 Unsupported PL/I language elements . . . . . 205
Entering multiline commands in full-screen and
line mode . . . . . . . . . . . . . . 183 Chapter 30. Debugging C and C++
Entering multiline commands in a command file 183
Entering multiline commands without continuation 184
programs . . . . . . . . . . . . . 207
Using blanks in Debug Tool commands . . . . 184 Debug Tool commands that resemble C and C++
Entering comments in Debug Tool commands . . 184 commands . . . . . . . . . . . . . . 207
Using constants in Debug Tool commands. . . . 185 Using C and C++ variables with Debug Tool . . . 208
Getting online help for Debug Tool command Accessing C and C++ program variables . . . 208
syntax . . . . . . . . . . . . . . . . 185 Displaying values of C and C++ variables or
expressions . . . . . . . . . . . . . 208
Assigning values to C and C++ variables . . . 209
Chapter 28. Debugging COBOL %PATHCODE values for C and C++ . . . . . 209
programs . . . . . . . . . . . . . 187 Declaring session variables with C and C++ . . . 210
Format for a COBOL source listing and debug file 187 C and C++ expressions . . . . . . . . . . 211
Debug Tool commands that resemble COBOL Calling C and C++ functions from Debug Tool . . 212
statements . . . . . . . . . . . . . . 187 C reserved keywords . . . . . . . . . . . 213
vi Debug Tool Version 4 Release 1 User’s Guide

C operators and operands . . . . . . . . . 213 Changing the program displayed in the
Language Environment conditions and their C and disassembly view . . . . . . . . . . . . 238
C++ equivalents . . . . . . . . . . . . 214 Restrictions for the disassembly view . . . . . 239
Debug Tool evaluation of C and C++ expressions 215
Intercepting files when debugging C and C++
Part 6. Debugging in different
programs . . . . . . . . . . . . . . . 216
Scope of objects in C and C++ . . . . . . . . 218 environments . . . . . . . . . . 241
Storage classes in C and C++ . . . . . . . 219
Blocks and block identifiers for C . . . . . . 220 Chapter 33. Debugging DB2 programs 243
Blocks and block identifiers for C++ . . . . . . 220 Debugging DB2 programs in batch mode . . . . 243
Example: referencing variables and setting Debugging DB2 programs in full-screen mode . . 243
breakpoints in C and C++ blocks . . . . . . . 221
Scope and visibility of objects . . . . . . . 221 Chapter 34. Debugging DB2 stored
Blocks and block identifiers . . . . . . . 221
procedures . . . . . . . . . . . . 245
Displaying environmental information . . . . . 222
Resolving some common problems . . . . . . 245
Qualifying variables and changing the point of
view in C and C++ . . . . . . . . . . . 222
Qualifying variables in C and C++ . . . . . 223 Chapter 35. Debugging IMS programs 247
Changing the point of view in C and C++ . . . 223 Debugging IMS programs in interactive mode . . 247
Example: using qualification in C. . . . . . 224 Debugging IMS programs in batch mode . . . . 248
Stepping through C++ programs . . . . . . . 225
Setting breakpoints in C++ . . . . . . . . . 225 Chapter 36. Debugging CICS
Setting breakpoints in C++ using AT programs . . . . . . . . . . . . . 249
ENTRY/EXIT . . . . . . . . . . . . 225 Debug modes under CICS . . . . . . . . . 249
Setting breakpoints in C++ using AT CALL . . 226 Preventing Debug Tool from stopping at EXEC
Examining C++ objects . . . . . . . . . . 227 CICS RETURN . . . . . . . . . . . . . 250
Example: displaying attributes of C++ objects 227 Saving settings while debugging a
Monitoring storage in C++ . . . . . . . . . 228 pseudo-conversational program . . . . . . . 250
Example: monitoring and modifying registers Saving and restoring breakpoints . . . . . . . 250
and storage in C . . . . . . . . . . . 228 Restrictions when debugging under CICS . . . . 250
Chapter 31. Debugging an assembler Chapter 37. Debugging ISPF

program . . . . . . . . . . . . . 231 applications . . . . . . . . . . . . 253
The SET ASSEMBLER and SET DISASSEMBLY
commands . . . . . . . . . . . . . . 231
Chapter 38. Debugging programs in a
Loading an assembler program’s debug
information . . . . . . . . . . . . . . 231 production environment . . . . . . . 255
Debug Tool session panel while debugging an Fine-tuning your programs with Debug Tool . . . 255
assembler program . . . . . . . . . . . 232 Removing hooks . . . . . . . . . . . 255
Restrictions for debugging an assembler program 233 Removing statement and symbol tables. . . . 256
Restrictions for debugging an assembler MAIN Debugging without hooks, statement tables, and
program . . . . . . . . . . . . . . 233 symbol tables . . . . . . . . . . . . . 256
Restrictions for debugging with the STORAGE Debugging optimized C, C++, PL/I and older
run-time option . . . . . . . . . . . 233 COBOL programs . . . . . . . . . . . . 257
Restrictions on the use of non-Language Debugging optimized COBOL programs . . . . 258
Environment services . . . . . . . . . . 233
Restrictions for debugging self-modifying code 233 Chapter 39. Debugging UNIX System
Services programs . . . . . . . . . 261
Chapter 32. Debugging a Debugging MVS POSIX programs . . . . . . 261
disassembled program . . . . . . . 235
The SET ASSEMBLER and SET DISASSEMBLY Part 7. Debugging complex
commands . . . . . . . . . . . . . . 235
applications . . . . . . . . . . . 263
Capabilities of the disassembly view . . . . . 235
Starting the disassembly view . . . . . . . . 236
The disassembly view . . . . . . . . . . 236 Chapter 40. Debugging multilanguage
Performing single-step operations . . . . . . 237 applications . . . . . . . . . . . . 265
Setting breakpoints . . . . . . . . . . . 237 Debug Tool evaluation of HLL expressions . . . 265
Restrictions for debugging self-modifying code . . 237 Debug Tool interpretation of HLL variables and
Displaying and modifying registers . . . . . . 238 constants . . . . . . . . . . . . . . . 265
Displaying and modifying storage . . . . . . 238 HLL variables . . . . . . . . . . . . 266
Contents vii
HLL constants . . . . . . . . . . . . 266 How does Debug Tool locate source and listing
Debug Tool commands that resemble HLL files? . . . . . . . . . . . . . . . . 289
commands . . . . . . . . . . . . . . 266 How does Debug Tool locate COBOL side files? 290
Qualifying variables and changing the point of How does Debug Tool locate EQALANGX files 290
view . . . . . . . . . . . . . . . . 267
Qualifying variables . . . . . . . . . . 267 Appendix C. Examples: Preparing
Changing the point of view . . . . . . . 268 programs and modifying setup files
Handling conditions and exceptions in Debug Tool 269
Handling conditions in Debug Tool . . . . . 270
with Debug Tool Utilities . . . . . . 291
Handling exceptions within expressions (C and Creating personal data sets . . . . . . . . . 291
C++ and PL/I only) . . . . . . . . . . 271 Starting Debug Tool Utilities . . . . . . . . 292
Debugging multilanguage applications . . . . . 271 Compiling or assembling your program by using
Debugging an application fully supported by Debug Tool Utilities . . . . . . . . . . . 292
Language Environment . . . . . . . . . 271 Modifying and using a setup file . . . . . . . 295
Debugging an application partially supported Run the program in foreground . . . . . . 295
by Language Environment . . . . . . . . 272 Run the program in batch . . . . . . . . 296
Using session variables across different
languages . . . . . . . . . . . . . 272 Appendix D. Notes on debugging in
Coexistence with other debuggers . . . . . . 273 batch mode . . . . . . . . . . . . 297
Coexistence with unsupported HLL modules . . . 274
Appendix E. Notes on debugging in
Chapter 41. Debugging multithreading remote debug mode . . . . . . . . 299
programs . . . . . . . . . . . . . 275 Tip on using the IBM Distributed Debugger . . . 299
Restrictions when debugging multithreading
applications . . . . . . . . . . . . . . 275 Appendix F. Syntax of the TEST
Compiler option . . . . . . . . . . 301
Chapter 42. Debugging across Syntax for the C TEST compiler option . . . . . 301
multiple processes and enclaves . . . 277 Syntax for the C++ TEST compiler option . . . . 303
Starting Debug Tool within an enclave . . . . . 277 Syntax for the COBOL TEST compiler option . . . 304
Viewing Debug Tool windows across multiple Syntax for the PL/I and Enterprise PL/I TEST
enclaves . . . . . . . . . . . . . . . 277 compiler options . . . . . . . . . . . . 307
Using breakpoints within multiple enclaves . . . 278
Ending a Debug Tool session within multiple Notices . . . . . . . . . . . . . . 311
enclaves . . . . . . . . . . . . . . . 278 Copyright license . . . . . . . . . . . . 312
Using Debug Tool commands within multiple Programming interface information . . . . . . 312
enclaves . . . . . . . . . . . . . . . 278 Trademarks and service marks . . . . . . . 312
Chapter 43. Debugging a Bibliography . . . . . . . . . . . . 313

multiple-enclave interlanguage Debug Tool publications . . . . . . . . . . 313
communication (ILC) application . . . 281 High level language publications . . . . . . . 313
Related publications . . . . . . . . . . . 313
Softcopy publications . . . . . . . . . . . 314
Part 8. Appendixes . . . . . . . . 283
Glossary . . . . . . . . . . . . . 315
Appendix A. Data sets used by Debug
Tool . . . . . . . . . . . . . . . 285
Index . . . . . . . . . . . . . . . 321
Appendix B. How does Debug Tool
locate debug information and source
or listing files? . . . . . . . . . . . 289
viii Debug Tool Version 4 Release 1 User’s Guide

About this document
Debug Tool combines the richness of the z/OS® and OS/390® environments with
the power of Language Environment® to provide a debugger for programmers to
isolate and fix their program bugs and test their applications. Debug Tool gives
you the capability of testing programs in batch, using a nonprogrammable terminal
in full-screen mode, or using a workstation interface to remotely debug your
programs.
Who might use this document

This document is intended for programmers using Debug Tool to debug high-level
languages (HLLs) and assembler programs with Language Environment.
Throughout this document, the HLLs are referred to as C, C++, COBOL, and PL/I.
The following operating systems and subsystems are supported:

v z/OS and OS/390
– CICS®
– DB2®
– IMS™
– JES batch
– TSO
– UNIX® System Services in remote debug mode or full-screen mode through a
VTAM terminal only
– WebSphere® in remote debug mode or full-screen mode through a VTAM
terminal only
To use this document and debug a program written in one of the supported
languages, you need to know how to write, compile, and run such a program.
Accessing z/OS licensed documents on the Internet

z/OS licensed documentation is available on the Internet in PDF format at the
IBM® Resource Link™ Web site at:
http://www.ibm.com/servers/resourcelink
Licensed documents are available only to customers with a z/OS license. Access to
these documents requires an IBM Resource Link user ID and password, and a key
code. With your z/OS order you received a Memo to Licensees, (GI10-0671), that
includes this key code.
To obtain your IBM Resource Link user ID and password, log on to:
http://www.ibm.com/servers/resourcelink
To register for access to the z/OS licensed documents:

1. Sign in to Resource Link using your Resource Link user ID and password.
2. Select User Profiles located on the left-hand navigation bar.
Note: You cannot access the z/OS licensed documents unless you have registered
for access to them and received an e-mail confirmation informing you that
your request has been processed.
© Copyright IBM Corp. 1992, 2003 ix

Printed licensed documents are not available from IBM.
You can use the PDF format on either z/OS Licensed Product Library CD-ROM or
IBM Resource Link to print licensed documents.
Using LookAt to look up message explanations

LookAt is an online facility that lets you look up explanations for most messages
you encounter, as well as for some system abends and codes. Using LookAt to find
information is faster than a conventional search because in most cases LookAt goes
directly to the message explanation.
You can access LookAt from the Internet at:

http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/ or from anywhere in
z/OS or z/OS.e where you can access a TSO/E command line (for example,
TSO/E prompt, ISPF, z/OS UNIX System Services running OMVS).
The LookAt Web site also features a mobile edition of LookAt for devices such as
Pocket PCs, Palm OS, or Linux-based handhelds. So, if you have a handheld
device with wireless access and an Internet browser, you can now access LookAt
message information from almost anywhere.
To use LookAt as a TSO/E command, you must have LookAt installed on your
host system. You can obtain the LookAt code for TSO/E from a disk on your z/OS
Collection (SK3T-4269) or from the LookAt Web site’s Download link.
How this document is organized

This document is divided into areas of similar information for easy retrieval of
appropriate information. The following list describes how the information is
grouped:
v Part 1 groups together introductory information about Debug Tool. The
following list describes each chapter:
– Chapter 1 introduces Debug Tool and describes some of its features.
– Chapter 2 introduces Debug Tool Utilities and Advanced Functions and
describes some of its features.
– Chapter 3 provides instructions on how to use full-screen mode to debug a
program.
v Part 2 groups together information about how to prepare programs for
debugging. The following list describes each chapter:
– Chapter 4 describes some of the preliminary planning and resource actions to
take when you prepare your programs.
– Chapter 5 describes how to prepare a COBOL program.
– Chapter 6 describes how to prepare a PL/I programs.
– Chapter 7 describes how to prepare a C program.
– Chapter 8 describes how to prepare a C++ program
– Chapter 9 describes how to prepare an assembler program.
– Chapter 10 describes how to prepare a DB2 program.
– Chapter 11 describes how to prepare a DB2 stored procedures program.
– Chapter 12 describes how to prepare a CICS program.
– Chapter 13 describes how to prepare an IMS program.
x Debug Tool Version 4 Release 1 User’s Guide

v Part 3 groups together information that describes the different methods you can
use to start Debug Tool. The following list describes each chapter:
– Chapter 14 describes how to start Debug Tool from Debug Tool Utilities.
– Chapter 15 describes how to start Debug Tool Utilities by using the TEST
run-time option.
– Chapter 16 describes how to start Debug Tool from a program.
– Chapter 17 describes how to start your program when you start Debug Tool.
– Chapter 18 describes how to start Debug Tool in full-screen mode.
– Chapter 19 describes how to start Debug Tool from DB2 stored procedures
and CICS programs and how to start Debug Tool in full-screen mode through
a VTAM® terminal.
v Part 4 groups together information about how to debug a program in full-screen
mode and provides an example of how to debug a C, COBOL, and PL/I
program in full-screen mode. The following list describes each chapter:
– Chapter 20 provides overview information about full-screen mode.
– Chapter 21 provides a sample COBOL program to describe how to debug it
in full-screen mode.
– Chapter 22 provides a sample PL/I program to describe how to debug it in
full-screen mode.
– Chapter 23 provides a sample C program to describe how to debug it in
full-screen mode.
– Chapter 24 provides a sample C++ program to describe how to debug it in
full-screen mode.
– Chapter 25 provides a sample assembler program to describe how to debug it
in full-screen mode.
– Chapter 26 describes how to modify the appearance of a full-screen mode
debugging session.
v Part 5 groups together information about how to enter and use Debug Tool
commands.
– Chapter 27 provides information about entering mixed case commands, using
DBCS characters, abbreviating commands, entering multiline commands, and
entering comments.
– Chapter 28 describes how to use Debug Tool commands to debug COBOL
programs.
– Chapter 29 describes how to use Debug Tool commands to debug PL/I
programs.
– Chapter 30 describes how to use Debug Tool commands to debug C or C++
programs.
– Chapter 31 describes how to use Debug Tool commands to debug assembler
programs.
– Chapter 32 describes how to use Debug Tool commands to debug
disassembly programs.
v Part 6 groups together information about debugging DB2, DB2 stored
procedures, IMS, CICS, ISPF, UNIX System Services, and production-level
programs.
– Chapter 33 describes how to debug a DB2 program.
– Chapter 34 describes how to debug a DB2 stored procedure.
– Chapter 35 describes how to debug an IMS program.
– Chapter 36 describes how to debug a CICS program.
About this document xi

– Chapter 37 describes how to debug an ISPF program.
– Chapter 38 describes how to debug a production-level program.
– Chapter 39 describes how to debug a program running in the UNIX System
Services shell.
v Part 7 groups together information about how to debug programs written in
multiple language or running in multiple processes.
– Chapter 40 describes how to debug a program written in multiple languages.
– Chapter 41 describes the restrictions when you debug a multithreaded
program.
– Chapter 42 describes how to debug a program that runs across multiple
processes and enclaves.
– Chapter 43 describes how to debug a multiple-enclave interlanguage
communication (ILC) application.
v Part 8 groups together appendices. The following list describes each appendix:
– Appendix A describes the data sets that Debug Tool uses to retrieve and store
information.
– Appendix B provides an example that guides you through the process of
preparing a sample program and modifying existing setup files by using
Debug Tool Utilities.
– Appendix C describes the process Debug Tool uses to locate source, listing, or
side files.
– Appendix D provides information about debugging a program in batch mode.
– Appendix E provides information about debugging a program in remote
debug mode.
– Appendix F describes the syntax of the TEST compiler option.
The last several chapters list notices, bibliography, and glossary of terms.
Terms used in this document

Because of differing terminology among the various programming languages
supported by Debug Tool, as well as differing terminology between platforms, a
group of common terms has been established. The table below lists these terms
and their equivalency in each language.
Debug Tool C and C++ COBOL PL/I equivalent assembler

term equivalent equivalent
Compile unit C and C++ Program or class Program (or CSECT
source file PL/I source file
for Enterprise
PL/I)
Block Function or Program, nested Block CSECT
compound program, method
statement or PERFORM
group of
statements
Label Label Paragraph name Label Label
or section name
Debug Tool provides facilities that apply only to programs compiled with specific
levels of compilers. Because of this, Debug Tool for z/OS User’s Guide uses the
following terms:
xii Debug Tool Version 4 Release 1 User’s Guide

Enterprise PL/I
Refers to the Enterprise PL/I for z/OS and OS/390 and the VisualAge®
PL/I for OS/390 compilers.
assembler
Refers to assembler programs with debug information assembled by using
the High Level Assembler (HLASM).
disassembly or disassembled
Refers to high-level language programs compiled without debug
information or assembler programs without debug information. The
debugging support Debug Tool provides for these programs is through the
disassembly view.
How to read syntax diagrams

This section describes how to read syntax diagrams. It defines syntax diagram
symbols, items that may be contained within the diagrams (keywords, variables,
delimiters, operators, fragment references, operands) and provides syntax examples
that contain these items.
Syntax diagrams pictorially display the order and parts (options and arguments)
that comprise a command statement. They are read from left to right and from top
to bottom, following the main path of the horizontal line.
Symbols
The following symbols may be displayed in syntax diagrams:
Symbol Definition
─── Indicates the beginning of the syntax diagram.
─── Indicates that the syntax diagram is continued to the next line.
─── Indicates that the syntax is continued from the previous line.
─── Indicates the end of the syntax diagram.
Syntax items
Syntax diagrams contain many different items. Syntax items include:
v Keywords - a command name or any other literal information.
v Variables - variables are italicized, appear in lowercase and represent the name
of values you can supply.
v Delimiters - delimiters indicate the start or end of keywords, variables, or
operators. For example, a left parenthesis is a delimiter.
v Operators - operators include add (+), subtract (-), multiply (*), divide (/), equal
(=), and other mathematical operations that may need to be performed.
v Fragment references - a part of a syntax diagram, separated from the diagram to
show greater detail.
v Separators - a separator separates keywords, variables or operators. For example,
a comma (,) is a separator.
Keywords, variables, and operators may be displayed as required, optional, or

default. Fragments, separators, and delimiters may be displayed as required or
optional.
Item type Definition
About this document xiii

Required Required items are displayed on the main path of the horizontal
line.
Optional Optional items are displayed below the main path of the horizontal
line.
Default Default items are displayed above the main path of the horizontal
line.
Syntax examples
The following table provides syntax examples.
Table 1. Syntax examples
Item Syntax example
Required item.
KEYWORD required_item
Required items appear on the main path of the horizontal
line. You must specify these items.
Required choice.
KEYWORD required_choice1
A required choice (two or more items) appears in a required_choice2
vertical stack on the main path of the horizontal line. You
must choose one of the items in the stack.
Optional item.
KEYWORD
Optional items appear below the main path of the optional_item
horizontal line.
Optional choice.
KEYWORD
An optional choice (two or more items) appears in a optional_choice1
vertical stack below the main path of the horizontal line. optional_choice2
You may choose one of the items in the stack.
Default.
default_choice1
Default items appear above the main path of the KEYWORD
horizontal line. The remaining items (required or optional_choice2
optional) appear on (required) or below (optional) the optional_choice3
main path of the horizontal line. The following example
displays a default with optional items.
Variable.
Variables appear in lowercase italics. They represent KEYWORD variable

names or values.
xiv Debug Tool Version 4 Release 1 User’s Guide

Table 1. Syntax examples (continued)
Item Syntax example
Repeatable item.
An arrow returning to the left above the main path of the

horizontal line indicates an item that can be repeated. KEYWORD repeatable_item
A character within the arrow means you must separate
,
repeated items with that character.
KEYWORD repeatable_item
An arrow returning to the left above a group of
repeatable items indicates that one of the items can be
selected, or a single item can be repeated.
Fragment.
KEYWORD fragment
The ─┤ fragment ├─ symbol indicates that a labelled
group is described below the main syntax diagram. fragment:
Syntax is occasionally broken into fragments if the
inclusion of the fragment would overly complicate the ,required_choice1
main syntax diagram. ,default_choice
,required_choice2
,optional_choice
How to send your comments

Your feedback is important in helping us to provide accurate, high-quality
information. If you have comments about this document or any other Debug Tool
documentation, contact us in one of these ways:
v Use the Online Readers’ Comment Form at
www.ibm.com/software/awdtools/rcf/. Be sure to include the name of the
document, the publication number of the document, the version of Debug Tool,
and, if applicable, the specific location (for example, page number) of the text
that you are commenting on.
v Fill out the Readers’ Comment Form at the back of this document, and return it
by mail or give it to an IBM representative. If the form has been removed,
address your comments to:
IBM Corporation
H150/090
555 Bailey Avenue
San Jose, CA 95141-1003
USA
v Fax your comments to this U.S. number: (800)426-7773.
When you send information to IBM, you grant IBM a nonexclusive right to use or
distribute the information in any way it believes appropriate without incurring any
obligation to you.
About this document xv

xvi Debug Tool Version 4 Release 1 User’s Guide
Part 1. Getting started with Debug Tool
© Copyright IBM Corp. 1992, 2003 1

2 Debug Tool Version 4 Release 1 User’s Guide
Chapter 1. Debug Tool: overview
Debug Tool helps you test programs and examine, monitor, and control the
execution of programs written in assembler, C, C++, COBOL, or PL/I on a z/OS or
OS/390 system. Your applications can include other languages; Debug Tool
provides a disassembly view that lets you debug, at the machine code level, those
portions of your application. However, in the disassembly view, your debugging
capabilities are limited. Table 2, Table 3, and Table 4 on page 4 map out the
combinations of compiler, subsystems, and remote debuggers that Debug Tool
supports, as of print time. An updated list of supported compilers and
environments is available on the Debug Tool Web site at:
http://www.ibm.com/software/awdtools/debugtool
You can use Debug Tool to debug your programs in batch mode, interactively in
full-screen mode, or in remote debug mode using a workstation user interface
provided by the compiler product.
Table 2 maps out the Debug Tool interfaces and compilers or assemblers each
interface supports.
Table 2. Debug Tool interface type by compiler or assembler
Full-screen
Compiler or assembler Batch mode mode Remote mode
VS COBOL II V1R3 & V1R4 (with U U
limitations)
AD/Cycle COBOL/370 V1R1 U U
COBOL for MVS & VM U U U
COBOL for OS/390 & VM U U U
Enterprise COBOL for z/OS and OS/390 U U U
OS PL/I 2.1, 2.2, & 2.3 (with limitations) U U
PL/I for MVS & VM U U
Enterprise PL/I U U U
AD/Cycle C/370 V1R2 U U
C/C++ for MVS/ESA Version 3 Release 2 U U
OS/390 C/C++ feature version 1.3 and U U
earlier
OS/390 C/C++ feature version 2.4 and later U U U
z/OS C/C++ feature U U U
IBM High Level Assembler (HLASM) U U U
Table 3 maps out the Debug Tool interfaces and subsystems each interface
supports.
Table 3. Debug Tool interface type by subsystem
Full-screen
Subsystem Batch mode mode Remote mode
TSO U U U

Table 3. Debug Tool interface type by subsystem (continued)
Full-screen
Subsystem Batch mode mode Remote mode
JES batch U U* U
UNIX System Services U* U
CICS U U U
DB2 U U U
DB2 stored procedures U* U
IMS (TM and DB) with BTS TSO U U
foreground
IMS (TM and DB) with BTS batch U U* U
IMS without BTS IMS DB batch U U* U
IMS without BTS IMS TM U* U
*
Support is for full-screen mode through a VTAM terminal only.
Table 4 shows the operating system and communication protocol for each remote
debugger.
Table 4. Remote debugger by operating system and communication protocol
Operating
system and z/OS or VisualAge for WebSphere
communication VisualAge COBOL OS/390 Java, Enterprise Studio Enterprise
protocol for Windows C/C++ Edition Developer
OS/2 4.0 and U
TCP/IP
Windows NT 4.0 U U U U
and TCP/IP
Windows 2000 U U U
and TCP/IP
Windows XP and U U
TCP/IP
Windows 95 and U
TCP/IP
Related concepts
“Debug Tool interfaces”
Related tasks
Chapter 4, “Planning your debug session and collecting resources,” on page 21
Chapter 20, “Using full-screen mode: overview,” on page 93
Related references
Debug Tool for z/OS Reference and Messages
Debug Tool interfaces

The terms full-screen mode, batch mode, and remote debug mode identify the types of
debugging interfaces that Debug Tool provides.

Full-screen mode
Debug Tool provides an interactive full-screen interface on a 3270 device, with
debugging information displayed in three windows:
v A Source window in which to view your program source or listing
v A Log window, which records commands and other interactions between Debug
Tool and your program
v A Monitor window in which to monitor changes in your program
You can debug all languages supported by Debug Tool in full-screen mode.
You can debug non-TSO programs in full-screen mode by using the full-screen
mode through a VTAM terminal facility. For example, you can debug a COBOL
batch job running in MVS/JES, a DB2 Stored Procedure, an IMS transaction
running on a IMS MPP region, or an application running in UNIX System Services.
Contact your system administrator to determine if the full-screen mode through a
VTAM terminal facility is active on your system.
Related tasks
Debug Tool for z/OS Customization Guide
Batch mode
You can use Debug Tool command files to predefine series of Debug Tool
commands to be performed on a running batch application. Neither terminal input
nor user interaction is available for batch debugging of a batch application. The
results of the debugging session are saved to a log, which you can review at a later
time.
Remote debug mode

In remote debug mode, the host application starts Debug Tool, which uses a
TCP/IP connection to communicate with a remote debugger on your Windows
workstation.
Debug Tool, in conjunction with the remote debuggers provided by some compiler
products and WebSphere Studio Enterprise Developer, provides users with the
ability to debug host programs, including batch, through a graphical user interface
(GUI) on the workstation. The remote debuggers VisualAge Remote Debugger and
IBM Distributed Debugger are available through products such as:
v C/C++ Productivity Tools for OS/390
v VisualAge COBOL for Windows 3.0
v VisualAge for Java, Enterprise Edition for OS/390
v VisualAge PL/I for Windows
The Compiled language debugger is the remote debugger available through

WebSphere Studio Enterprise Developer.
Remote debug mode also provides important additional functions such as the
ability to interactively debug batch processes. For example, a COBOL batch job
running in MVS/JES, or a COBOL CICS batch transaction, can be interactively
debugged through a TCP/IP connection to a workstation equipped with a remote
debugger. You can debug the following applications:
v VisualAge PL/I for OS/390 applications
v Enterprise PL/I for z/OS and OS/390 applications
Chapter 1. Debug Tool: overview 5

v Applications running in UNIX System Services Shell
v Enterprise COBOL for z/OS and OS/390
v COBOL for MVS & VM applications
v COBOL for OS/390 & VM applications
The Debug Tool Web site contains a current list of environments supporting remote
debug mode.
For more information, visit the IBM Software Web site at:
http://www.ibm.com/software/awdtools/
Related references
“Debug Tool session panel” on page 93

Chapter 2. Debug Tool Utilities and Advanced Functions:
introduction
Debug Tool Utilities and Advanced Functions enhances Debug Tool, and the
combined strength of these products can help you debug and examine your
programs.
Debug Tool provides a tool called Debug Tool Setup Utility (DTSU) to help you
create and manage setup files which can help you run your programs. Debug Tool
Utilities and Advanced Functions adds tools to help you do the following tasks:
v Prepare your high-level language programs for debugging by helping you
convert, compile, and link.
v Prepare your assembler programs for debugging by helping you assemble, create
debug information, and link.
v Conduct analysis on your test cases to determine how thoroughly your test cases
test your programs (also called code coverage).
v Start and run your program in foreground or batch by storing and using setup
information. Setup information can be the run-time parameters, libraries, and
names of input and output data sets.
v For IMS Version 8, browse and edit the Language Environment run-time
parameters table.
v Create a batch job for private IMS message region with customized load libraries
and region attributes.
The combination of DTSU and these tools is called Debug Tool Utilities.
Debug Tool provides a rich set of commands to debug your programs. Debug Tool
Utilities and Advanced Functions enhances this set of commands by adding the
following commands:
v ALLOCATE
v CALL %FA
v DESCRIBE ALLOCATIONS
v FREE
v LOADDEBUGDATA or LDD
v PLAYBACK BACKWARD
v PLAYBACK DISABLE
v PLAYBACK ENABLE
v PLAYBACK FORWARD
v PLAYBACK START
v PLAYBACK STOP
v QUERY ASSEMBLER
v QUERY AUTOMONITOR
v QUERY ASSEMBLER
v QUERY PLAYBACK
v QUERY PLAYBACK LOCATION
v SET ASSEMBLER

v SET AUTOMONITOR
v SET PROGRAMMING LANGUAGE ASSEMBLER
Debug Tool Utilities: creating and managing setup files

Setup files can save you time when you are debugging a program that needs to be
restarted multiple times. Setup files store information needed to run your program
and start Debug Tool. You can create several setup files for each program; each
setup files can store information about starting and running your program in
different circumstances. To create and manage files, use Debug Tool Setup Utility
(DTSU), which is part of Debug Tool. You do not need Debug Tool Utilities and
Advanced Functions to use this tool.
Debug Tool Utilities: converting, compiling, and linking

Debug Tool Utilities helps you do the following tasks:
v Run the DB2 precompiler or the CICS translator.
If the program source is a sequential data set and the DB2 precompiler is
selected, make sure the DBRMLIB data set field in EQAPPCnB panel, where n=1,2,..5,
is a partitioned data set with a member name. For example,
DEBUG.TEST.DBRMLIB(PROG1).
v Set compiler options.
v Specify naming patterns for your data sets.
v Specify input data sets for copy processing.
v Convert, compile, and link-edit your programs in either TSO foreground or MVS
batch.
v Prepare the following COBOL programs for debugging:
– Programs written for OS/VS COBOL.
– Programs previously compiled with the CMPR2 compiler option.
To prepare these programs, you convert the source to the newer COBOL
standard and compile it with the newer compilers. After you debug your
program, you can do one of the following:
– Make changes to your OS/VS COBOL source and repeat the conversion and
compilation every time you want to debug your program.
– Make changes in the converted source and stop maintaining your OS/VS
COBOL source.
Debug Tool Utilities: preparing assembler programs

By using High-Level Assembler (HLASM), Debug Tool Utilities can help you
assemble and create debug information for your assembler programs. After your
assembler program is assembled and the debug information is created, you can
start Debug Tool and begin debugging your program.
Debug Tool Utilities: conducting code coverage

Determining code coverage can help you improve your test cases so they test your
program more thoroughly. Debug Tool Utilities provides you with Debug Tool
Coverage Utility, a tool to report which code statements have been run by your
test cases. Using the report, you can enhance your test cases so they run code
statements that were not run previously.

Debug Tool Utilities: preparing IMS run-time environment
You can create private IMS message regions that you can use to debug test
applications and, therefore, not interfere with other regions. For IMS Version 8, you
can modify the Language Environment run-time parameters table without
relinking the applications.
Starting Debug Tool Utilities

Debug Tool Utilities can be started in two ways. To determine which method to
use on your system, contact your system administrator.
To start Debug Tool Utilities, do one the following:

v If an option was installed to access the Debug Tool Utilities primary options
ISPF panel from an existing panel, then select that option by using instructions
from the installer.
v If the Debug Tool data sets were installed into your normal logon procedure,
enter the following command from ISPF option 6:
EQASTART common_parameters
v If Debug Tool was not installed in your ISPF environment, enter this command
from ISPF option 6:
EX ’hlq.SEQAEXEC(EQASTART)’ ’common_parameters’
The common_parameters are optional and specify any of the parameters described in
Appendix E of Coverage Utility User’s Guide and Messages. Multiple options are
separated by blanks. Note that if you specify any of these common_parameters, your
settings are remembered by EQASTART and become the default on subsequent
starts of EQASTART when you do not specify parameters.
Chapter 2. Debug Tool Utilities and Advanced Functions: introduction 9

Chapter 3. 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. To debug a program in full-screen mode, you must
compile or assemble your program with the proper options. “Compiling or
assembling your program with the proper compiler options” gives an overview of
the basic compiler or assembler tasks and directs you to other sections of this
document that provide more detail.
This chapter gives an overview of basic debugging tasks and directs you to other
sections of the document that provide more detail.
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 debug your program.
Compiler options to use with C programs
The TEST compiler option provides suboptions to refine debugging
capabilities. Use the defaults to gain maximum debugging capability.
Compiler options to use with C++ programs
capabilities. Use the defaults to gain maximum debugging capability.
Compiler options to use with COBOL programs
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 to use with PL/I programs
All PL/I programs must use the TEST suboption with the following
stipulations:
v Programs compiled with the PL/I for MVS or OS PL/I compilers must
also specify the SOURCE suboption.
v The syntax for the TEST compiler option of the Enterprise PL/I compilers
is slightly different. Refer to each programming language’s
documentation for specific details.
Assembler options to 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.
Related tasks
“Compiling a C program with the TEST compiler option” on page 31
“Compiling a C program on an HFS file system” on page 32
“Compiling your C program with the #pragma statement” on page 33
“Compiling a C++ program with the TEST compiler option” on page 35
“Compiling a C++ program on an HFS file system” on page 35
“Compiling a COBOL program with the TEST compiler option” on page 25

“Compiling a PL/I program with the TEST compiler option” on page 29
“Compiling a Enterprise PL/I program on an HFS file system” on page 29
“Compiling a PL/I for MVS & VM or OS PL/I program” on page 30
Chapter 9, “Preparing an assembler program,” on page 37
Starting Debug Tool

You have a choice of three ways to start Debug Tool in full-screen mode:
v By using Debug Tool Utilities, which helps you compile or assemble your
program and then start Debug Tool.
v When you start your program, include the TEST run-time option as part of your
command. For example:
CALL ’USERID1.MYLIB(MYPROGRM)’ ’/TEST’
Place the slash (/) before or after the TEST parameter, depending on the
programming language you are debugging.
This is the simplest and most direct way to start Debug Tool. It also starts
Debug Tool at the earliest point possible in your program.
v From within your program, insert calls to _ctest(), plitest, or ceetest to start
Debug Tool. This method is useful when you are familiar with your program
and you know where you want debugging to begin.
When you start your program with the TEST run-time option, 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 4 Release 1 Mod 0
0002 09/26/2003 10:02:39 AM
0003 5655-L24 and 5655-L23: (C) Copyright IBM Corp. 1992, 2003
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 screen is divided into four sections:

Session panel header
The top two lines of the screen are 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.

Monitor window
The second part of the screen is the Monitor window. It displays the
results of the MONITOR commands.
Source window
The third part of the screen is the Source window. The Source window
displays the source or listing file.
Log window
The fourth part of the screen is the Log window. It records your
interactions with Debug Tool and the results of those interactions.
Now that you are familiar with the Debug Tool interface, you can begin debugging
programs.
Related tasks
Chapter 15, “Starting Debug Tool by using the TEST run-time option,” on page 63
Chapter 16, “Starting Debug Tool from a program,” on page 69
“Starting Debug Tool with CEETEST” on page 69
“Starting Debug Tool with PLITEST” on page 75
“Starting Debug Tool with the __ctest() function” on page 75
“Entering commands on the session panel” on page 100
“Navigating through Debug Tool session panel windows” on page 104
“Recording and replaying statements”
Related references
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.
Related tasks
“Stepping through or running your program” on page 109
Recording and replaying statements

The commands described in this section are available only if you purchase and
install IBM Debug Tool Utilities and Advanced Functions, Version 4 Release 1
(5655–L23).
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 5 describes the sequence in which statements are replayed when you replay
them in a forward direction or a backward direction.
Table 5. The sequence in which statements are replayed.
PLAYBACK PLAYBACK
FORWARD BACKWARD
sequence sequence COBOL Statements
1 9 DISPLAY "CALC Begins."
2 8 MOVE 1 TO BUFFER-PTR.
3 7 PERFORM ACCEPT-INPUT 2 TIMES.
Chapter 3. Debugging a program in full-screen mode: introduction 13

Table 5. The sequence in which statements are replayed. (continued)
PLAYBACK PLAYBACK
FORWARD BACKWARD
sequence sequence COBOL Statements
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.
Running your program to a specific line

You can run from one point in a program to another point in several ways:
v Set a breakpoint and use the GO command. This command runs your program
from the point where it stopped to the breakpoint that you set. Any breakpoints
that are encountered cause your program to stop. The RUN command is
synonymous with the GO command.
v Use the GOTO command. This command runs your program at the point that you
specify in the GOTO command.

v Use the RUNTO command. This command runs your program to the point that
you specify in the RUNTO command. The RUNTO command is helpful when you
haven’t set a breakpoint at the point you specify in the RUNTO command.
Related references
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 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 ;
Related references
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 two ways:
v One-time display (in the Log window) is useful for quickly checking the value
of a variable.

v Continuous display (in the Monitor window) is useful for observing the value of
a variable over time.
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
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.
Related tasks
“Displaying values of C and C++ variables or expressions” on page 208
“Displaying values of COBOL variables” on page 191
“Displaying and monitoring the value of a variable” on page 112
Related references
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 ;
Related tasks
“Assigning values to C and C++ variables” on page 209
“Assigning values to COBOL variables” on page 189
Skipping a breakpoint
Use the DISABLE command to temporarily disable a breakpoint. Use the ENABLE
command to re-enable the breakpoint.
Related references

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.
Related references
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 for z/OS Reference and Messages for more information on the
QQUIT and QUIT ABEND commands which can stop your debug session.
Related references

Part 2. Preparing your program for debugging

Chapter 4. Planning your debug session and collecting
resources
Before you begin debugging, you should plan how you want to conduct your
debug session and then collect the resources you need to implement your plan. To
help you create your plan, consider following questions:
v Do you want to compile your program with hooks?
v Do you want to reference variables during your debug session?
v Do you want full debug capability or smaller application size and higher
performance?
v When do you want to start Debug Tool and when do you want it to gain
control?
v Do you want to use Debug Tool in full-screen mode, in batch mode, or in
remote debug mode?
The sections in this chapter provide answers to these questions which can help you
determine how you want to conduct your debug session.
Related concepts
“Debug Tool interfaces” on page 4
Chapter 2, “Debug Tool Utilities and Advanced Functions: introduction,” on page 7
Related tasks
Chapter 5, “Preparing a COBOL program,” on page 25
Chapter 6, “Preparing a PL/I program,” on page 29
Chapter 7, “Preparing a C program,” on page 31
Chapter 8, “Preparing a C++ program,” on page 35
Chapter 10, “Preparing a DB2 program,” on page 41
Chapter 11, “Preparing a DB2 stored procedures program,” on page 45
Chapter 12, “Preparing a CICS program,” on page 47
Chapter 13, “Preparing an IMS program,” on page 53
Chapter 38, “Debugging programs in a production environment,” on page 255
Do you want to compile your program with hooks?

Hooks enable you to set breakpoints. Hooks are instructions that can be inserted
into a program by a compiler at compile time. Hooks can be placed at the
entrances and exits of blocks, at statement boundaries, and at points in the
program where program flow might change between statement boundaries (called
path points). If you compile a program with the TEST compiler option and specify
any suboption except NONE, the compiler inserts hooks into your program.
If you use one of the following compilers, you can compile your programs without
hooks:
v Enterprise COBOL for z/OS and OS/390, Version 3
v COBOL for OS/390 & VM, Version 2 Release 2
v COBOL for OS/390 & VM, Version 2 Release 1, with APAR PQ40298

To debug these programs, you must use the Dynamic Debug facility. The Dynamic
Debug facility enables you to set breakpoints in a program that does not have
hooks. The hooks are inserted at run time whenever you set a breakpoint.
Do you want to reference variables during your debug session?

If yes, you need to instruct the compiler to create a symbol table. The symbol table
contains descriptions of variables, their attributes, and their location in storage.
Debug Tool uses these descriptions when it references variables. The symbol tables
can be stored in the object file of the program or in a separate debug file. You can
save symbol tables in a separate debug file if you compile your programs with one
of the following compilers:
v COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ40298
Saving symbol tables in a separate debug file can reduce the size of the load
module for your program.
Do you want full debug capability or smaller application size and

higher performance?
Removing hooks, statement tables, or symbol tables can increase the performance
of your application and decrease its size. However, debug capabilities are
diminished.
To decrease the size of your application, increase performance, and retain most
debug capabilities, you can compile COBOL programs with the
TEST(NONE,SYM,SEPARATE) compiler option, which is available with one of the
The Dynamic Debug facility must be activated. To determine if the Dynamic

Debug facility is active, contact your system administrator. If your programs are
running on OS/390, Version 2 Release 10, or z/OS, Version 1 Release 1, you need
to install Language Environment APAR PQ46488.
When do you want to start Debug Tool and when do you want it to
gain control?
You have a choice of ways to start Debug Tool, as well as ways to let it gain
control of your program.
You can start Debug Tool in one of the following ways:

v You can use Debug Tool Setup Utility, which you can access by using Debug
Tool Utilities. Debug Tool Setup Utility can help you prepare your programs and
start Debug Tool.
v You can use the TEST run-time option. This option gives you the choice of
starting Debug Tool at any of these times:
– Before you run your program

– When a high-level language (HLL) condition occurs while your program is
running
– When an attention interrupt occurs
Also, Language Environment, as well as certain HLLs, provides a run-time
service that you can call while your program is executing, at the location of your
choice.
After Debug Tool starts, it gains control of your program and suspends execution
so that you can take actions such as checking the value of a variable or examining
the contents of storage.
Do you want to use Debug Tool in full-screen mode, in batch mode, or

in remote debug mode?
Decide which interface you want to use when debugging your program. The
interface that you choose affects how you start your program, how you start
Debug Tool, and how you interact with Debug Tool.
Collecting your resources

After you determine how you want to conduct your debug session, collect the
resources you need to prepare and debug your programs. The minimum
requirement is the source file to compile or assemble your program and access to
the compiler or assembler to prepare your program. The following list describes
additional resources you might need, depending on the type of program you are
debugging:
To debug a program that is optimized
If you are debugging a COBOL program that is optimized, you need to
save the debug information in a separate debug file and you need to use
the Dynamic Debug facility. You also need to use the compilers that
support the SEPARATE suboption of the TEST compiler option.
To debug a program without hooks
If you are debugging a program without hooks, you need the Dynamic
Debug facility to debug your program.
To debug a program without debug information
If you are debugging a program without debug information, you need to
use the disassembly view and have a hardcopy of the listing available.
To debug an assembler program with debug information
If you are debugging an assembler program that has debug information,
you need to create the EQALANGX file.
Chapter 4. Planning your debug session and collecting resources 23

Chapter 5. Preparing a COBOL program
Before you debug a program, ensure that the program complies with the
requirements described in this book:
v All the data sets required to debug your program comply with the guidelines
described in this book.
v All the libraries that your program needs are available.
v Your program is compiled with the appropriate compiler options.
When a program is under development, compile the program with the TEST(ALL)
compiler option to get all of Debug Tool’s capabilities. If you use one of the
following compilers, you can compile COBOL programs with the
TEST(NONE,SYM,SEPARATE) compiler option and retain all of Debug Tool’s
capabilities:
v COBOL for OS/390 & VM, Version 1 with APAR PQ40298
Appendix C, “Examples: Preparing programs and modifying setup files with

Debug Tool Utilities,” on page 291 describes how to prepare a sample COBOL
program and start Debug Tool by using Debug Tool Utilities.
Compiling a COBOL program with the TEST compiler option

The suboptions you specify when you compile your COBOL program with the
TEST compiler option affect the size and performance of your program and the
debugging capabilities available. Before debugging your COBOL program with
Debug Tool, you must compile it with the COBOL TEST compiler option.
Depending on the suboptions you specify, the compiler does the following:
v Creates the symbol tables.
v Creates debugging information.
v Inserts hooks at selected points in your program.
Debug Tool uses the symbol tables to obtain information about program variables.
Programs compiled with one of the following compilers and with the SEPARATE
suboption store debugging information and symbol tables in a separate file.
The file, called a separate debug file, must be a nontemporary file and must also
be available during the debug session. If you move or rename the separate debug
file, use the SET SOURCE or SET DEFAULT LISTINGS command to specify the new
location or name of the files.
Debug Tool uses hooks to gain control of your program at selected points during
its execution. These points can be at the entrances and exits of blocks, at statement
boundaries, and at points in the program where program flow might change
between statement boundaries (called path points), such as before and after a CALL

statement. The hooks do not modify your source. The hooks are inserted into your
program during one of the following times:
v At compile time, when you specify the TEST compiler option with any suboption
except NONE.
v At run time, if you compiled your program with the NONE suboption of the TEST
compiler option and you are using Dynamic Debug. The hooks are inserted
when you set a breakpoint.
To debug programs compiled with the TEST(NONE) compiler option (which does not
insert hooks into the program), you must activate the Dynamic Debug facility and
use one of the following compilers:
If these programs reside in read-only storage, the Authorized Debug facility must
be activated. Contact your system administrator to verify that the Dynamic Debug
and Authorized Debug facilities are activated.
If these programs are running on OS/390, Version 2 Release 10, or z/OS, Version 1
Release 1, you need to install Language Environment APAR PQ46488.
When you use the COBOL TEST compiler option:

v If you specify NUMBER with TEST, make sure the sequence fields in your source
code all contain numeric characters.
v Usually, when you specify TEST in combination with any other suboptions
(except NONE), the compiler options NOOPTIMIZE and OBJECT automatically go into
effect, preventing you from debugging optimized programs. However, if you
specify TEST(NONE,SYM) and compile with one of the following compilers, you
can specify OPT, allowing you to debug optimized programs:
– Enterprise COBOL for z/OS and OS/390, Version 3 Release 2
– Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR
PQ63235
– COBOL for OS/390 & VM, Version 2 with APAR PQ63234
v The TEST compiler option and the DEBUG run-time option are mutually exclusive,
with DEBUG taking precedence. If you specify both the WITH DEBUGGING MODE
clause in your SOURCE-COMPUTER paragraph and the USE FOR DEBUGGING statement
in your code, TEST is deactivated. The TEST compiler option appears in the list of
options, but a diagnostic message is issued telling you that because of the
conflict, TEST is not in effect.
v If you want to use the DATA suboption of the PLAYBACK ENABLE command, you
must specify the SYM suboption of the TEST compiler option when you compile
your program.
v For VS COBOL II programs, in addition to the TEST compiler option, you must
specify:
– the SOURCE compiler option. This option is required to generate a listing file.
– the RESIDENT compiler option. This option is required by Language
Environment to ensure that the necessary Debug Tool routines are loaded
dynamically at run time.
In addition, you must link your program with the Language Environment
SCEELKED library and not the VS COBOL II COB2LIB library.

Related references
Compiling an OS/VS COBOL program

Programs compiled with the OS/VS COBOL compiler can be debugged by
converting them to the 1985 COBOL Standard level and compiling them with the
Enterprise COBOL for z/OS and OS/390 or COBOL for OS/390 & VM compiler.
This conversion and compilation can be done with the Convert and Compile
option provided in Debug Tool Utilities. To use Debug Tool Utilities, you must
purchase and install Debug Tool Utilities and Advanced Functions, Version 4
Release (5655–L23).
The Convert and Compile option enables you to do the following:

1. Convert your OS/VS COBOL source by using COBOL and CICS Command
Level Conversion Aid (CCCA).
2. Compile new source with either the Enterprise COBOL for z/OS and OS/390
or COBOL for OS/390 & VM.
3. Debug the object module by using Debug Tool.
After you convert and debug your program, you can do one of the following:
v Continue to use the OS/VS COBOL compiler. Every time you want to debug
your program, you need to use the Convert and Compile option.
v Use the new source that was produced by the Convert and Compile option. You
can compile it and debug it without using the Convert and Compile option.
The Convert and Compile option can use any level of COBOL source program as
input, including VS COBOL II, COBOL for MVS & VM, and COBOL for OS/390 &
VM programs that were previously compiled with the CMPR2 compiler option.
Chapter 5. Preparing a COBOL program 27

Chapter 6. Preparing a PL/I program
described in this book.
When a program is under development, you should compile the program with the
TEST(ALL) compiler option to get all of Debug Tool’s capabilities.

Debug Tool Utilities,” on page 291 describes how to prepare a sample PL/I
Compiling a PL/I program with the TEST compiler option

The PL/I compiler provides support for Debug Tool under control of the TEST
compiler option and its suboptions for the placement of hooks and symbol tables.
The suboptions BLOCK, STMT, PATH, ALL, and NONE regulate the points at which the
compiler inserts hooks. These hooks allow Debug Tool to gain control at select
points in a program during execution. The suboptions SYM or NOSYM control the
insertion of symbol tables into the program’s object file. Debug Tool uses the
symbol tables to obtain information about program variables.
Related references
Compiling a Enterprise PL/I program on an HFS file system

If you are compiling and launching Enterprise PL/I programs on an HFS file
system, you must do one of the following:
v Compile and launch the programs from the same location, or
v specify the full path name when you compile the programs.
By default, the Enterprise PL/I compiler stores the relative path and file names in
the object file. When you start a debug session, if the source is not in the same
location as where the program is launched, Debug Tool does not locate the source.
To avoid this problem, specify the full path name for the source when you compile
the program. For example, if you execute the following series of commands, Debug
Tool does not find the source:
1. Change to the directory where your program resides and compile the program.
cd /u/myid/mypgm
pli -g "//TEST.LOAD(HELLO)" hello.pli
2. Exit UNIX System Services and return to the TSO READY prompt.
3. Launch the program with the TEST run-time option.
call TEST.LOAD(HELLO) ’test/’
The source because is located in another directory (/u/myid/mypgm). Debug Tool
does find the source if you change the compile command to:

pli -g "//TEST.LOAD(HELLO)" /u/myid/mypgm/hello.pli
The same restriction applies to programs that you compile to run in a CICS
environment.
Compiling a PL/I for MVS & VM or OS PL/I program

For OS PL/I programs, you must specify the SOURCE compiler option in addition to
the TEST compiler option. The SOURCE compiler option is required to generate a
listing file. In addition, you must link your program with the Language
Environment SCEELKED library; do not use the OS PL/I PLIBASE or SIBMBASE library.
To be able to view your listing while debugging in full-screen mode, PL/I for MVS
& VM and OS PL/I programs must be compiled using the SOURCE compiler option.
You must also direct the listing to a nontemporary file that is available during the
debug session. During a debug session, Debug Tool displays the first file it finds
named userid.pgmname.list in the Source window. If Debug Tool cannot find the
listing at this location, use the SET SOURCE command to associate your source
listing with the program you are debugging.

Chapter 7. Preparing a C program
described in this book. The source must be in a single file and not a
concatenation of files.
When a program is under development, you can get the full capability of Debug
Tool by compiling your program with the TEST(ALL) compiler option.

Debug Tool Utilities,” on page 291 describes how to prepare a sample C program
and start Debug Tool by using Debug Tool Utilities.
Compiling a C program with the TEST compiler option

Before you test your C program with Debug Tool, you must compile it with the C
TEST compiler option:
v The suboptions BLOCK, LINE, and PATH regulate the points where the compiler
inserts program hooks. When you set breakpoints, they are associated with the
hooks that are used to instruct Debug Tool where to gain control of your
program.
v The suboption SYM regulates the inclusion of symbol tables into the object output
of the compiler. Debug Tool uses the symbol tables to obtain information about
the variables in the program.
When you use the C TEST compiler option, be aware that:

v The C TEST compiler option generates hooks at entry and exit points for
functions.
v The C TEST compiler option implicitly specifies the GONUMBER compiler option,
which causes the compiler to generate line number tables that correspond to the
input source file. You can explicitly remove this option by specifying NOGONUMBER.
When the TEST and NOGONUMBER options are specified together, Debug Tool does
not display the current execution line as you step through your code.
v Programs that are compiled with both the TEST compiler option and either the
OPT(1) or OPT(2) compiler option do not have hooks at line, block, and path
points, or generate a symbol table, regardless of the TEST suboptions specified.
Only hooks for function entry and exit points are generated for optimized
programs.
v You can specify any number of TEST suboptions, including conflicting suboptions
(for example, both PATH and NOPATH). The last suboptions that are specified take
effect. For example, if you specify TEST(BLOCK, NOBLOCK, BLOCK, NOLINE, LINE),
what takes effect is TEST(BLOCK, LINE) because BLOCK and LINE are specified last.
v No duplicate hooks are generated even if two similar TEST suboptions are
specified. For example, if you specify TEST(BLOCK, PATH), the BLOCK suboption
causes the generation of hooks at entry and exit points. The PATH suboption also
causes the generation of hooks at entry and exit points. However, only one hook
is generated at each entry and exit point.

You can specify any combination of the C TEST suboptions in any order. The
default suboptions are BLOCK, LINE, PATH, and SYM.
If you build your application using the c89 orc++, do the following steps:
1. Compile your source code as usual, but specify the –g option to generate
debugging information. The –g option is equivalent to the TEST compiler option
under TSO or MVS batch. For example, to compile the C source file fred.c
from the u/mike/app directory, specify:
cd /u/mike/app
c89 –g –o "//PROJ.LOAD(FRED)" fred.c
Note: The double quotes in the command line above are required.
2. Set up your TSO environment, as described above.
3. Debug the program under TSO by entering the following:
FRED TEST ENVAR('PWD=/u/mike/app') / asis
Note: The single quotes in the command line above are required.
ENVAR('PWD=/u/mike/app') sets the environment variable PWD to the path
from where the source files were compiled. Debug Tool uses this
information to determine from where it should read the source files.
If you are debugging your application in the UNIX System Services Shell, you
must debug in remote debug mode or in full-screen mode through a VTAM
terminal. The workstation component of remote debuggers is available through
several products, including C and C++ Productivity Tools for OS/390 and
VisualAge COBOL.
Related references
Compiling a C program on an HFS file system

If you are compiling and launching programs on an HFS file system, you must do
one of the following:
v Compile and launch the programs from the same location.
v Specify the full path name when you compile the programs.
By default, the C compiler stores the relative path and file names in the object file.
When you start a debug session, if the source is not in the same location as where
the program is launched, Debug Tool does not find the source. To avoid this
problem, specify the full path name of the source when you compile the program.
For example, if you execute the following series of commands, Debug Tool does
not find the source:
cd /u/myid/mypgm
c89 -g -o "//TEST.LOAD(HELLO)" hello.c
The source is located in another directory (/u/myid/mypgm). Debug Tool finds the
source if you change the compile command to:
c89 -g -o "//TEST.LOAD(HELLO)" /u/myid/mypgm/hello.c

environment.
Rules for the placement of hooks in functions and nested blocks

The following rules apply to the placement of hooks for getting in and out of
functions and nested blocks:
v The hook for function entry is placed before any initialization or statements for
the function.
v The hook for function exit is placed just before actual function return.
v The hook for nested block entry is placed before any statements or initialization
for the block.
v The hook for nested block exit is placed after all statements for the block.
Rules for placement of hooks in statements and path points

The following rules apply to the placement of hooks for statements and path
points:
v Label hooks are placed before the code and all other statement or path point
hooks for the statement.
v The statement hook is placed before the code and path point hook for the
statement.
v A path point hook for a statement is placed before the code for the statement.
Related tasks
“Compiling your C program with the #pragma statement”
Related references
z/OS C/C++ User’s Guide
Compiling your C program with the #pragma statement

The TEST/NOTEST compiler option can be specified either when you compile your
program or directly in your program, using a #pragma.
This #pragma must appear before any executable code in your program.
The following example generates symbol table information, symbol information for
nested blocks, and hooks at line numbers:
#pragma options (test(SYM,BLOCK,LINE))
This is equivalent to TEST(SYM,BLOCK,LINE,PATH).
You can also use a #pragma to specify run-time options.
Related tasks
C/C++ Language Reference
Chapter 7. Preparing a C program 33

Chapter 8. Preparing a C++ program
described in this book. This includes that the source must be in a single file and
not a concatenation of files.
When a program is under development, you should compile the program with the
TEST(ALL) compiler option to get all of Debug Tool’s capabilities.

Debug Tool Utilities,” on page 291 describes how to prepare a sample C++
Compiling a C++ program with the TEST compiler option

Before testing your C++ program with Debug Tool, you must compile it with the
C++ TEST compiler option. This causes the compiler to generate information about
your program that Debug Tool needs to help you debug your program.
Related references
Compiling a C++ program on an HFS file system

If you are compiling and launching programs on an HFS file system, you must do
one of the following:
v Compile and launch the programs from the same location, or
v specify the full path name when you compile the programs.
By default, the C++ compiler stores the relative path and file names in the object
file. When you start a debug session, if the source is not in the same location as
where the program is launched, Debug Tool does not locate the source. To avoid
this problem, specify the full path name of the source when you compile the
program. For example, if you execute the following series of commands, Debug
Tool does not find the source:
cd /u/myid/mypgm
c++ -g -o "//TEST.LOAD(HELLO)" hello.cpp
The source is located in another directory (/u/myid/mypgm). Debug Tool finds the
source if you change the compile command to:
c++ -g -o "//TEST.LOAD(HELLO)" /u/myid/mypgm/hello.cpp

environment.
Rules for the placement of hooks in functions and nested blocks

The following rules apply to the placement of hooks for functions and nested
blocks:
v The hook for function entry is placed before any initialization or statements for
the function.
v The hook for function exit is placed just before actual function return.
v The hook for nested block entry is placed before any statements or initialization
for the block.
v The hook for nested block exit is placed after all statements for the block.
Rules for the placement of hooks in statements and path points

The following rules apply to the placement of hooks for statements and path
points:
v Label hooks are placed before the code and all other statement or path point
hooks for the statement.
v The statement hook is placed before the code and path point hook for the
statement.
v A path point hook for a statement is placed before the code for the statement.
Related tasks
Related references

Chapter 9. Preparing an assembler program
This chapter describes how to prepare an assembler program that you can debug
with Debug Tool’s full capabilities. To prepare an assembler program, you must do
the following steps:
1. Assemble your program with the proper options.
2. Create the EQALANGX file.
3. Link-edit your program.
If you use Debug Tool Utilities to prepare your assembler program, you can do
steps 1 and 2 in one step.
You must have Debug Tool Utilities and Advanced Functions installed on your
system to prepare and debug assembler programs.
You cannot debug an assembler program in remote debug mode.
Before you begin

The assembler program that you want to debug must meet the following two
requirements:
v The assembler program must run in Language Environment.
v The assembler program must meet one of the following requirements:
– It must be a Language Environment-conforming program.
– It must be a non-conforming program as described in the “Non-Language
Environment-conforming Assembler” section of the OS/390 Language
Environment for OS/390 & VM Programming Guide.
When you debug an assembler program, you can use most of the Debug Tool
commands. There are three differences between debugging an assembler program
and debugging programs written in other programming languages supported by
Debug Tool:
v After you assemble your program, you must create a debug information file,
also called the EQALANGX file. Debug Tool uses this file to obtain information
about your assembler program.
v Debug Tool assumes all compile units are written in some high-level language
(HLL). You must inform Debug Tool that a compile unit is an assembler compile
unit and instruct Debug Tool to load the assembler compile unit’s debug
information. Do this by entering the LOADDEBUGDATA (or LDD) command.
v Assembler does not have language elements you can use to write expressions.
Debug Tool provides an assembler-like language elements you can use to write
expressions for Debug Tool commands that require an expression. See Debug Tool
for z/OS Reference and Messages a description of the syntax of the assembler-like
language.
After you verify that your assembler program meets these requirements, prepare
your assembler program as instructed in Chapter 9, “Preparing an assembler
program.”

Debug Tool Utilities,” on page 291 describes how to prepare a sample assembler
Assembling your program

If you assemble your program without using Debug Tool Utilities, you must use
the High Level Assembler (HLASM) and specify a SYSADATA DD statement and
the ADATA option. This causes the assembler to create a SYSADATA file. The
SYSADATA file is required to generate the debug information (the EQALANGX file)
used by Debug Tool.
Creating the EQALANGX file

To create the EQALANGX files without using Debug Tool Utilities, use JCL similar
to the following:
//XTRACT EXEC PGM=EQALANGX,REGION=32M,
// PARM=’(ASM ERROR’
//STEPLIB DD DISP=SHR,DSN=hlq.SEQAMOD
//SYSADATA DD DISP=SHR,DSN=yourid.sysadata
//IDILANGX DD DISP=OLD,DSN=yourid.EQALANGX
The following list describes the variables used in this example:

PARM=
(ASM
Indicates that an assembler module is being processed.
ERROR
This parameter is optional. If you specify it, additional information is
displayed when an error is detected.
hlq.SEQAMOD
The name of the data set containing the Debug Tool load modules. If the
Debug Tool load modules are in a system linklib data set, you can omit the
following line:
//STEPLIB DD DISP=SHR,DSN=hlq.SEQAMOD
yourid.sysadata
The name of the data set containing the SYSADATA output from the assembler.
If this is a partitioned data set, the member name must be specified. For
information about the characteristics of this data set, see HLASM Programmer’s
Guide.
yourid.EQALANGX
The name of the data set where the EQALANGX debug file is to be placed.
This data set must have variable block record format (RECFM=VB) and a logical
record length of 1562 (LRECL=1562).
Debug Tool searches for the EQALANGX debug file in a partitioned data set
with the name yourid.EQALANGX and a member name that matches the name of
the first CSECT in the assembly. If you want the member name of the
EQALANGX debug file to match the first CSECT in the assembly, you do not
need to specify a member name on the DD statement.

Assembling your program and creating EQALANGX
You can assemble your program and create the EQALANGX file at the same time by
using Debug Tool Utilities. Do the following:
1. Start Debug Tool Utilities. The Debug Tool Utilities panel is displayed.
2. Select option 1, ″Program Preparation″ . The Debug Tool Program Preparation
panel is displayed.
3. Select option 5, ″Assemble″. The Debug Tool Program Preparation - High
Level Assembler panel is displayed. In this panel, specify the name of the
source file and the assemble options that are used by High Level Assembler
(HLASM) to assemble the program.
If option 5 is not available, contact your system administrator.
4. Press Enter. The High Level Assembler - Verify Selections panel is
displayed. Verify that the information on the panel is correct and then press
Enter.
5. If any of the output data sets you specified do not existed, you are asked to
verify the options used to create them.
6. If you specified that the processing be completed by batch, the JCL created to
run the batch job is displayed. Verify that the JCL is correct, type Submit in the
command line, press Enter and then press PF3.
7. After the processing is completed, the High Level Assembler - View Outputs
panel is displayed. This panel displays the return code of each process
completed and enables you to view, edit, or browse the input and output data
sets.
To read more information about a field in any panel, place the cursor in the input
field and press PF1. To read more information about a panel, place the cursor
anywhere on the panel that is not an input field and press PF1.
After you assemble your program and create the EQALANGX file, you can link-edit
your program.
Link-editing your program

You can link-edit your program by using your normal link-edit procedures or you
can use Debug Tool Utilities by doing the following:
1. From the Debug Tool Program Preparation panel, select option L, ″Link Edit″.
The Debug Tool Program Preparation - Link Edit panel is displayed. In this
panel, specify the input data sets and link edit options that you need the linker
to use.
2. Press Enter. The Link Edit - Verify Selections panel is displayed. Verify that
the information on the panel is correct and then press Enter.
3. If any of the output data sets you specified do not exist, you are asked to verify
the options used to create them. Press Enter after you verify the options.
4. If you specified that the processing be completed by batch, the JCL created to
run the batch job is displayed. Verify that the JCL is correct and press PF3.
5. After the processing is completed, the Link Edit - View Outputs panel is
displayed. This panel displays the return code of each process completed and
enables you to view, edit, or browse the input and output data sets.
To read more information about a field in any panel, place the cursor in the input
field and press PF1. To read more information about a panel, place the cursor
anywhere on the panel that is not an input field and press PF1.
Chapter 9. Preparing an assembler program 39
After you link-edit your program, you can run your program and start Debug
Tool.

Chapter 10. Preparing a DB2 program
There are no special coding techniques for any DB2 programs you might want to
debug using Debug Tool.
To communicate with DB2, you should:

v Delimit SQL statements with EXEC SQL and END-EXEC statements
v Declare SQLCA in working storage
v Declare the host variables
v Code the appropriate SQL statements
v Test the DB2 return codes
Program preparation includes the DB2 precompiler, the compiler, the prelinker, the
linkage editor, and DB2 bind. The following files must be retained in a permanent
data set for Debug Tool to read when you debug your program:
v For COBOL and PL/I, the program listing.
v For COBOL, the separate debug file.
v For C, C++, VisualAge PL/I and Enterprise PL/I, the program source file.
Note: For C and C++, it is the input to the compiler (the output from the DB2
precompiler) that needs to be retained.
Related references
DB2 UDB for OS/390 Application Programming and SQL Guide
Precompiling DB2 programs for debugging

Before your program can be compiled, the SQL statements must be prepared using
the DB2 precompiler. No special preparations are needed in the precompile step to
use Debug Tool.
When debugging a program containing SQL, keep the following in mind:

v The SQL preprocessor replaces all the SQL statements in the program with host
language code. The modified source output from the preprocessor contains the
original SQL statements in comment form. For this reason, the source or listing
view displayed during a debugging session can look very different from the
original source.
v The host language code inserted by the SQL preprocessor starts the SQL access
module for your program. You can halt program execution at each call to a SQL
module and immediately following each call to a SQL module, but the called
modules cannot be debugged.
Related references
Compiling DB2 programs for debugging

You must use the output from the DB2 precompiler as input to the compiler.
Before using Debug Tool, you must prepare your program by compiling at least
one part of it with the TEST compiler option.

Important: Ensure that your source (if you are working with C and C++ language),
separate debug file (if you are working with Enterprise COBOL), or listing (if you
are working with COBOL or PL/I) is stored in a permanent data set that is
available to Debug Tool.
Related tasks
Related references
Appendix F, “Syntax of the TEST Compiler option,” on page 301
Linking DB2 programs for debugging

To debug DB2 programs, you must link the output from the compiler into your
program load library. You can include the user run-time options module,
CEEUOPT, by doing the following:
1. Find the user run-time options program CEEUOPT in the Language
Environment SCEESAMP library.
2. Change the NOTEST parameter into the desired TEST parameter. For example:
old: NOTEST=(ALL,*,PROMPT,INSPPREF),
new: TEST=(,*,;,*),
For remote debug mode only

TEST=(,,,VACTCPIP&&9.24.104.79:*)
Note: Double ampersand is required.
For full-screen mode through a VTAM terminal only

Test=(,,,MFI%TCP00001:)
3. Assemble the CEEUOPT program and keep the object code.
4. Link-edit the CEEUOPT object code with any program to start Debug Tool.
The modified assembler program, CEEUOPT, is shown below.

*/****************************************************************/
*/* LICENSED MATERIALS - PROPERTY OF IBM */
*/* */
*/* 5694-A01 */
*/* */
*/* (C) COPYRIGHT IBM CORP. 1991, 2001 */
*/* */
*/* US GOVERNMENT USERS RESTRICTED RIGHTS - USE, */
*/* DUPLICATION OR DISCLOSURE RESTRICTED BY GSA ADP */
*/* SCHEDULE CONTRACT WITH IBM CORP. */
*/* */
*/* STATUS = HLE7705 */
*/****************************************************************/
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
CEEXOPT TEST=(,*,;,*)
END

The user run-time options program can be assembled with predefined TEST
run-time options to establish defaults for one or more applications. Link-editing an
application with this program results in the default options when that application
is started.
If your system programmer has not already done so, include all the proper
libraries in the SYSLIB concatenation. For example, the ISPLOAD library for
ISPLINK calls, and the DB2 DSNLOAD library for the DB2 interface modules
(DSNxxxx).
Related tasks
Binding DB2 programs for debugging

Before you can run your DB2 program, you must run a DB2 bind in order to bind
your program with the relevant DBRM output from the precompiler step. No
special requirements are needed for Debug Tool.
Chapter 10. Preparing a DB2 program 43

Chapter 11. Preparing a DB2 stored procedures program
The DB2 administrator must define the address space where the stored procedure
runs. This can be a DB2 Address Space or a Workload Manager (WLM) Address
Space. This address space is assigned a name which is used to define the stored
procedure to DB2. In the JCL for the DB2 or WLM address space, verify that the
following data sets are defined in the STEPLIB concatenation and have the
appropriate RACF Read authorization for programs to access them:
v LOADLIB for the stored procedure
v SEQAMOD for Debug Tool
v SCEERUN for Language Environment
After updating the JCL, the DB2 administrator must recycle the DB2 or WLM
address space so that these updates take effect.
In order to debug a stored procedure, it must be compiled with the TEST compiler
option and run with the TEST run-time option. If the stored procedure is defined as
Type=SUB, CEEUOPTS is ignored by Language Environment.
The TEST runtime options must be defined to the RUNOPTS field of the DB2 catalog
by using the appropriate DB2 SQL commands. In the following examples, the
stored procedure is a COBOL program called SPROC1 of Type SUB that runs in a
WLM address space called WLMENV1. The stored procedures are debugged in
remote mode.
v For DB2 Version 5, the stored procedure is defined as follows:
insert into sysibm.sysprocedures
(procedure, authid, luname, loadmod, linkage, collid,
language, asutime, stayresident, ibmreqd,
runopts,
parmlist, result_sets, wlm_env,
pgm_type, external_security, commit_on_return)
values(’SPROC1’, ’ ’, ’ ’, ’SPROC1’, ’ ’, ’ ’,
’COBOL’, 0, ’ ’, ’N’,
’TEST(,,,VADTCPIP&9.112.27.21%8001:*)’,
’ ’, 0, ’WLMENV1’,
’S’, ’N’, ’N’);
v For DB2 Version 6, the stored procedure is defined as follows:
create procedure sproc1
language cobol
external name sproc1
parameter style general
wlm environment wlmenv1
run options ’TEST(,,,VADTCPIP&9.112.27.99%8001:*)’
program type sub;
To verify that the stored procedure is defined correctly, use the SQL SELECT
command on the appropriate DB2 table.
v For DB2 Version 5:
select * from sysibm.sysprocedures;
select * from sysibm.sysroutines;
If the definition is not correct, use the appropriate SQL command to modify the
stored procedure.
update sysibm.sysroutines
set runopts=’TEST(,,,VADTCPIP&9.112.27.21%8000:*)’
where specificname=’SPROC1’;
alter procedure sproc1 run options ’TEST(,,,VADTCPIP&9.112.27.21%8000:*)’;
Related references

Chapter 12. Preparing a CICS program
To prepare a CICS program for debugging, you must do the following tasks:
1. Complete the program preparation tasks for assembler, C, C++, COBOL, or
PL/I, as described in the sections listed under Related tasks.
2. Link-edit CEEBXITA into the CICS program that you want to debug. This step is
optional for COBOL programs compiled with VS COBOL II compilers or later.
3. Create and store a profile that specifies the combination of resource IDs that
you want to debug.
4. Run your program.
Related tasks
Link-editing CEEBXITA into your program

To link-edit CEEBXITA (the DTCN-customized Language Environment user exit) into
the CICS program that you want to debug, do one of the following alternatives:
v If your site does not use this user exit, link-edit member EQADCCXT, which
contains the CSECT CEEBXITA, from library hlq.SEQAMOD into your main
program.
v If your site does use CEEBXITA, request the name and location of the DTCN
customized exit from your CICS system administrator and link that exit into
your main program.
After you link-edit your program, use the DTCN transaction to create a profile that
specifies the combination of resource IDs that you want to debug. See “Creating
and storing a DTCN profile.”
Creating and storing a DTCN profile

The DTCN transaction stores one profile for each DTCN terminal in a repository.
Each profile is retained in the repository until one of the following events occurs:
v The profile is explicitly deleted by the terminal that entered it.
v DTCN detects that the terminal which created the profile has been disconnected.
v The CICS region is terminated.
To create and store a DTCN profile, do the following steps:

1. Log on to a CICS terminal and enter the transaction ID DTCN. The DTCN
transaction displays the main DTCN screen, Debug Tool CICS Control -
Primary Menu, shown below.

DTCN Debug Tool CICS Control - Primary Menu S07CICPN
Select the combination of resources to debug (see Help for more information)
Terminal Id ==> 0039

Transaction Id ==>
Program Id(s) ==> ==> ==> ==>
==> ==> ==> ==>
User Id ==>
NetName ==>
Select type and ID of debug display device
Session Type ==> MFI MFI, TCP, WSD

Port Number ==> TCP Port
Display Id ==> 0039
Generated String: TEST(ALL,’*’,PROMPT,’MFI%0039:*’)
Repository String: No string currently saved in repository
PF1=HELP 2=GHELP 3=EXIT 4=SAVE 6=DELETE 7=SHOW 9=OPTIONS
Some of the entry fields are filled in with default values that start Debug Tool,
in full-screen mode, for tasks running on this terminal. If you do not want to
change the defaults, you can skip the next two steps and proceed to step 4 on
page 49. If you want to change the settings on this panel, continue to the next
step.
2. Specify the combination of resource IDs that you want to debug.
Terminal Id
Specify the CICS terminal to debug. By default, this ID is set to the
terminal that is currently running DTCN.
Transaction Id
Specify the CICS transaction to debug. If you specify a transaction ID
without any other resource, Debug Tool is started every time that
transaction is run, including times when other users run the
transaction.
Program Id(s)
Specify the CICS program or programs to debug. If you specify a
program ID without any other resource, Debug Tool is started every
time the program is run, including times when other users run the
program.
User Id
Specify the CICS user ID to debug. All programs that are run by this
user will start Debug Tool.
NetName
Specify the four character name of a CICS terminal or a CICS system
that you want to use to run your debugging session. This name is used
by VTAM to identify the CICS terminal or system.
3. Specify the type of debugging and the ID of the display device.
Session Type
Select one of the following options:
MFI Indicates that Debug Tool initializes on a 3270 type of terminal.
TCP Indicates that you want to interact with Debug Tool from your

workstation using TCP/IP and the VisualAge Remote Debugger
or the IBM Distributed Debugger, which is shipped with most
VisualAge compiler products.
WSD Indicates that you want to interact with Debug Tool from your
workstation using TCP/IP and the Compiled language
debugger, which is shipped with WebSphere Studio Enterprise
Developer.
Port Number
Specifies the logical connector between the CICS terminal and TCP/IP.
Display Id
Identifies the target destination for Debug Tool information. Depending
on the session type that you’ve selected, the display ID is one of the
following:
v If you selected MFI, the display ID is a CICS 3270 terminal ID. This
ID is set by default to the terminal ID that is currently running
DTCN, but you can change this to direct MFI screens to a different
CICS terminal.
v If you selected TCP or WSD, enter either the IP address or host name
of the workstation that will display the debug screens. For the debug
session to start, the appropriate software must be running on that
workstation.
4. Specify the debugging options by pressing PF9 to display the secondary
options menu, shown below.
DTCN Debug Tool CICS Control - Menu 2 S07CICPD
Select Debug Tool options

Test Option ==> TEST Test/Notest
Test Level ==> ALL All/Error/None
Commands File ==> *
Prompt Level ==> PROMPT
Preference File ==> *
Any other valid Language Environment options

==>
PF1=HELP 2=GHELP 3=RETURN
Some of the entry fields are filled in with default values that start Debug Tool,
in full-screen mode, for tasks running on this terminal. If you do not want to
change the defaults, you can skip the rest of this step and proceed to step 5 on
page 50. If you want to change the settings on this panel, continue with this
step.
Test Option
TEST/NOTEST specifies the conditions under which Debug Tool assumes
control during the initialization of your application.
Test Level
ALL/ERROR/NONE specifies what conditions need to be met for Debug
Tool to gain control.
Command File
A valid fully qualified data set name that specifies the primary
commands file for this run.

Note: Do not enclose the name of the data set in single or double
quotes.
Prompt Level
Specifies whether Debug Tool is started at Language Environment
initialization.
Preference File
A valid fully qualified data set name that specifies the preference file to
be used. Do not enclose the name of the data set in single or double
quotes.
Any other valid Language Environment Options
You can change any Language Environment option that your site has
defined as overrideable except the STACK option. For additional
information about Language Environment options, see z/OS Language
Environment Programming Reference or contact your CICS system
programmer.
5. Press PF3 to return to the main DTCN panel.
6. Press PF4 to save the profile. DTCN performs data verification on the data that
you entered in the DTCN panel. When DTCN discovers an error, it places the
cursor in the erroneous field and displays a message. You can use
context-sensitive help (PF1) to find what is wrong with the input.
Now, any tasks that run in the CICS system and match the resource IDs that you
specified in the previous steps will start Debug Tool.
To display all of the active DTCN profiles in the CICS region, press PF7. The
Debug Tool CICS Control - All Sessions screen displays, shown below.
DTCN Debug Tool CICS Control - All Sessions S07CICPL
Overtype "_" with a "D" to delete a profile.
Owner Term Tran User Netname Applid Options String
_ 0070 0070 TRN1 USER1 0072 S07CICPL TEST(ALL,’*’,PROMPT,’MFI%0070

Program(s) CIC9060 CS9060 CBLAC?3 *9361
PF1=HELP 2=GHELP 3=RETURN 7=BACK 8=FORWARD
The column titles are defined below:

Owner
The ID of the terminal that created the profile by using DTCN.
Term The value that was entered on the main DTCN screen in the Terminal Id
field.
Tran The value that was entered on the main DTCN screen in the Transaction
Id field.
User The value that was entered on the main DTCN screen in the User Id field.

Netname
The value the entered on the main DTCN screen in the Netname field.
Applid
The application identifier associated with this profile.
Options String
The value of Repository String field on the main DTCN screen; it’s created
based on the values that the user enters in the other fields.
Program(s)
The values that were entered on the main DTCN screen in the Program Ids
field.
DTCN also reads the Language Environment NOTEST option supplied to the CICS
region in CEECOPT or CEEROPT. You can supply suboptions, such as the name of
a preference file, with the NOTEST option to supply additional defaults to DTCN.
Sharing DTCN repository profile items among CICS systems

The DTCN repository is a CICS temporary storage queue, named EQADTCN2. If
you want to share the repository among CICS systems, define the queue as
REMOTE in your CICS temporary storage tables (TST). This setting stores a profile
item in one CICS system, and makes it readable to another system.

Chapter 13. Preparing an IMS program
If you have Debug Tool Utilities and Advanced Functions installed on your system,
you can use Debug Tool Utilities to help you prepare and start your IMS
programs. Do the following tasks to prepare your IMS program:
1. Compile and link your IMS program by using the Program Preparation tool in
Debug Tool Utilities. Your program must be compiled with the TEST compiler
option. Appendix C, “Examples: Preparing programs and modifying setup files
with Debug Tool Utilities,” on page 291 describes how to compile and link
sample programs provided by Debug Tool. You can study these examples to
guide you through the compilation and linking process of your program.
For IMS Transaction Manager (TM) programs running in IMS Version 8, you do
not have to link the CEEUOPT load module to obtain information about the
TEST run-time options. You can specify the transaction settings and TEST
run-time options to use to run your program by using the Manage IMS
Programs tool in Debug Tool Utilities. See “Setting up the run-time options for
your IMS Version 8 TM program by using Debug Tool Utilities” on page 54 for
more information on how to do this task.
For IMS batch programs, you must link the CEEUOPT load module to obtain
information about the TEST run-time options. See “Linking IMS programs for
debugging” on page 55 for more information on how to do this task.
2. Create and customize a setup file for your IMS Batch Messaging Process (BMP)
program by using the Manage IMS Programs tool in Debug Tool Utilities. The
setup file contains information about how to create a custom region and it has
STEPLIB concatenation statements that reference the data sets for your IMS
program’s load module and the Debug Tool load module. See “Creating setup
file for your IMS program by using Debug Tool Utilities” on page 54 for more
information on how to do this task.
You can also create and customize a setup file for creating a private message
region that you can use to test your IMS Message Processing Program (MPP)
program. Creating a private message region with class X allows you to test
your IMS program run by transaction X and reduce the risk of interfering with
other regions being used by other IMS programs. See “Creating setup file for
your IMS program by using Debug Tool Utilities” on page 54 for more
information on how to do this task.
If you do not have Debug Tool Utilities and Advanced Functions installed on your
system, you can continue to compile, link, and start your IMS program by using
your site procedures. Remember the following points:
v Your program must be compiled with the TEST compiler option. Use the default
options to gain maximum debugging facilities.
v Ensure that your source (if you are working with C, C++, or Enterprise PL/I),
listing (if you are working with COBOL or PL/I), or separate debug file (if you
are working with COBOL) is stored in a permanent data set that is available to
Debug Tool.
v Ensure that you do the tasks described in “Linking IMS programs for
debugging” on page 55.
For IMS TM programs running in IMS Version 8, you do not have to link the
CEEUOPT load module to obtain information about the TEST run-time options.
You can specify the transaction settings and TEST run-time options to use to run

your program by using IMS Version 8 commands. See IMS Version 8 Command
Reference for more information on how to do this task
Creating setup file for your IMS program by using Debug Tool Utilities
To create a setup file for your IMS program by using Debug Tool Utilities, do the
following steps:
1. Start Debug Tool Utilities. If you do not know how to start Debug Tool
Utilities, see “Starting Debug Tool Utilities” on page 9.
2. In the Debug Tool Utilities panel (EQA@PRIM), type 4 in the Option line and
press Enter.
3. In the Manage IMS Programs panel (EQAPRIS), type 2 in the Option line and
press Enter.
4. In the Manage Message Regions - Edit Setup File panel (EQAPFORA), type in
the information to create a new setup file or edit an existing setup file. Press
Enter.
Creating a private message region or running a BMP program

After you specify the setup information required to run your IMS program, you
can specify the information needed to create a private message region you can use
to test your IMS program or specify how to run a BMP program. To specify this
setup information, do the following steps:
1. Starting at the Manage IMS Programs panel (EQAPRIS), type 2 in the Option
line and press Enter.
2. In the Manage Message Regions - Edit Setup File panel (EQAPFORA), type in
the information to create a new setup file or edit an existing setup file. Press
Enter.
3. In the Edit Setup File panel (EQAPFORI), type in information about the private
message region you want to create or the BMP program you want to run.
4. After you type in the specifications, you can submit your job for processing by
pressing PF10.
Setting up the run-time options for your IMS Version 8 TM program by

using Debug Tool Utilities
To specify the transaction settings and TEST run-time options for your IMS
program, do the following:
1. From the main Debug Tool Utilities panel (EQA@PRIM), type 4 in the Option
line and press Enter.
2. In the Manage IMS Programs panel (EQAPRIS), type 1 in the Option line and
press Enter.
3. In the Manage LE Runtime Options in IMS panel (EQAPRI), type in the
IMSPlex ID and optional qualifiers. Debug Tool Utilities uses this information
to search through the IMS LE run-time parameter repository and find the
entries that most closely match the information you typed in. You can use wild
cards (* and %) to increase the chances of a match. After you type in your
search criteria, press Enter.
4. In the Edit LE Runtime Options Entries in IMS panel (EQAPRIM), a table
displays all the entries found in the IMS LE run-time parameter repository that
most closely match your search criteria. You can do the following tasks in this
panel:
v Delete an entry.

v Add a new entry.
v Edit an existing entry.
v Copy an existing entry.
For more information about a command or field, press PF1 to display a help
panel.
5. After you finish making your changes, press PF3 to save your changes and
close the panel that is displayed. If necessary, press the PF3 repeatedly to close
other panels until you reach the Manage IMS Programs panel (EQAPRIS).
Linking IMS programs for debugging

When you link your IMS TM Version 8 program, you can manage the TEST
run-time options without linking in a copy of CEEUOPT. For instructions on
managing the TEST run-time options, see “Setting up the run-time options for your
IMS Version 8 TM program by using Debug Tool Utilities” on page 54.
When you link your IMS batch program or IMS TM Version 7 or earlier program,
you must include a run-time options module in your program link. They must be
coded and assembled in a user-defined run-time option module. For instructions
on how to create the CEEUOPT run-time options module using the CEEXOPT macro,
follow the steps in “Linking DB2 programs for debugging” on page 42.
For COBOL programs using IMS, include the IMS interface module DFSLI000 from
the IMS RESLIB library.
Chapter 13. Preparing an IMS program 55

Part 3. Starting Debug Tool

Chapter 14. Starting Debug Tool from the Debug Tool Utilities
The ’Manage and Use Debug Tool Setup Files’ function (also called Debug Tool
Setup Utilities or DTSU) in Debug Tool Utilities helps you manage setup files
which store the following information:
v file allocation statements
v run-time options
v program parameters
v the name of your program
Then you use the setup files to run your program in foreground or batch. The
Debug Tool Setup Utility (DTSU) RUN command performs the file allocations and
then starts the program with the specified options and parameters in the
foreground. The DTSU SUBMIT command submits a batch job to start the program.
Related tasks
“Creating the setup file”
“Editing an existing setup file”
“Saving your setup file” on page 61
“Starting your program” on page 62
Creating the setup file

You can have several setup files, but you must create them one at a time. To create
a setup file, do the following:
1. From the Debug Tool Utilities panel, select the Manage and Use Debug Tool
Setup Files option.
2. In the Debug Tool Foreground – Edit Setup File panel, type the name of the
new setup file in the Setup File Library or Other Data Set Name field. Do not
specify a member name if you are creating a sequential data set. If you are
creating a setup file for a DB2 program, select the Initialize New setup file for
DB2 field. Press Enter.
3. A panel similar to the ISPF 3.2 ″Allocate New Data Set″ panel appears. You can
modify the default allocation parameters. Enter the END command or press PF3
to continue.
4. The Edit – Edit Setup File panel appears. You can enter file allocation
statements, run-time options, and program parameters.
Related tasks
“Entering file allocation statements, run-time options, and program parameters” on page 60
Editing an existing setup file

You can have several setup files, but you can edit only one at a time. To edit an
existing setup file, do the following:
1. From the Debug Tool Utilities panel, select the Manage and Use Debug Tool
Setup Files option.
2. In the Debug Tool Foreground – Edit Setup File panel, type the name of the
existing setup file in the Setup File Library or Other Data Set Name field.
Press Enter to continue.

3. The Edit – Edit Setup File panel appears. You can modify file allocation
statements, run-time options, and program parameters.
Related tasks
“Entering file allocation statements, run-time options, and program parameters”
Copying information into a setup file from an existing JCL

You can enter the COPY command to copy information from another setup file or
JCL data set into the current setup file.
Entering file allocation statements, run-time options, and program

parameters
The top part of the Edit–Setup File panel contains the name of the program (load
module) that you want to run and the run-time parameter string. If the setup file
is for a DB2 program, the panel also contains fields for the DB2 System identifier
and the DB2 plan. The bottom part of the Edit–Setup File panel contains the file
allocation statements. This part of the panel is similar to an ISPF edit panel. You
can insert new lines, copy (repeat) a line, delete a line, and type over information
on a line.
To modify the name of the load module, type the name in the Load Module Name
field.
To modify the parameter string:

1. Select the format of the parameter string.
2. Enter the parameter string in one of the following ways:
v Type the parameter string in the Enter / to modify parameters field.
v Type a slash (″/″) before the Enter / to modify parameters field and press
Enter. The Debug Tool Foreground - Modify Parameter String panel appears.
This panel helps you define the TEST run-time option and its suboptions. You
can also enter any Language Environment run-time options and other
program parameters. After you have entered all your options, press PF3.
DTSU creates the parameter string from the options that you specified and
puts it in the Enter / to modify parameters field.
In the file allocation section of the panel, each line represents an element of a DD
name allocation or concatenation. The statements can be modified, copied, deleted,
and reordered.
To modify a statement, do one of the following:

v Modify the statement directly on the Edit – Edit Setup File panel:
1. Move your cursor to the statement you want to modify.
2. Type the new information over the existing information.
3. Press Enter.
v Modify the statement by using a select command:
1. Move your cursor to the statement you want to modify.
2. Type one of the following select commands.
– SA - Specify allocation information
– SD - Specify DCB information
– SS - Specify SMS information

– SP - Specify protection information
– SO - Specify sysout information
– SX - Specify all DD information by column display
– SZ - Specify all DD information by section display
3. Press Enter.
To copy a statement, do the following steps:

1. Move your cursor to the Cmd field of the statement you want to copy.
2. Type R and press Enter. The statement is copied into a new line immediately
following the current line.
To delete a statement, do the following steps:

1. Move your cursor to the Cmd field of the statement you want to delete.
2. Type D and press Enter. The statement is deleted.
To reorder statements in a concatenation, do the following steps:

1. Move your cursor to the sequence number field of a statement you want to
move and enter the new sequence number.
To insert a new line, do the following steps:

1. Move your cursor to the Cmd field of the line right above the line you want a
new statement inserted.
2. Type I and press Enter.
3. Move your cursor to the new line and type in the new information or use one
of the Select commands.
The Edit and Browse line commands allow you to modify or view the contents of
the data set name specified for DD and SYSIN DD types.
You can use the DDNAME STEPLIB to specify the load module search order.
For additional help, move the cursor to any field and enter the HELP command or
press PF1.
Related tasks
“Saving your setup file”
Saving your setup file

To save your information, enter the SAVE command. To save your information in a
second data set and continue editing in the second data set, enter the SAVE AS
command.
To save your setup file and exit the Edit–Edit Setup File panel, enter the END
command or press PF3.
To exit the Edit–Edit Setup File panel without saving any changes to your setup
file, enter the CANCEL command or press PF12.
Related tasks
“Starting your program” on page 62
Chapter 14. Starting Debug Tool from the Debug Tool Utilities 61
Starting your program
To perform the allocations and run the program with the specified parameter
string, enter the RUN command or press PF4.
To generate JCL from the information in the setup file and then submit to the batch
job, enter the SUBMIT command or press PF10.

Chapter 15. Starting Debug Tool by using the TEST run-time
option
To specify how Debug Tool gains control of your application and begins a debug
session, you can use the TEST run-time option. The simplest form of the TEST
option is TEST with no suboption; however, suboptions provide you with more
flexibility. There are four types of suboptions available, summarized below.
test_level
Determines what high-level language conditions raised by your program
cause Debug Tool to gain control of your program
commands_file
Determines which primary commands file is used as the initial source of
commands
prompt_level
Determines whether an initial commands list is unconditionally executed
during program initialization
preferences_file
Specifies the session parameter and a file that you can use to specify
default settings for your debugging environment, such as customizing the
settings on the Debug Tool Profile panel
Related tasks
Related references
“Special considerations while using the TEST run-time option”
Special considerations while using the TEST run-time option

When you use the TEST run-time option, there are several implications to consider,
which are described in this section.
Defining TEST suboptions in your program

In C, C++ or PL/I, you can define TEST with suboptions using a #pragma runopts
or PLIXOPT string, then specify TEST with no suboptions at run time. This causes
the suboptions specified in the #pragma runopts or PLIXOPT string to take effect.
You can change the TEST/NOTEST run-time options at any time with the SET TEST
command.
Suboptions and NOTEST

Some suboptions are disabled with NOTEST, but are still allowed. This means you
can start your program using the NOTEST option and specify suboptions you might
want to take effect later in your debug session. The program begins to run without
Debug Tool taking control.
To enable the suboptions you specified with NOTEST, start Debug Tool during your
program’s run time using a library service call such as CEETEST, PLITEST, or the
__ctest() function.

Implicit breakpoints
If the test level in effect causes Debug Tool to gain control at a condition or at a
particular program location, an implicit breakpoint with no associated action is
assumed. This occurs even though you have not previously defined a breakpoint
for that condition or location using an initial command string or a primary
commands file. Control is given to your terminal or to your primary commands
file.
Primary commands file and USE file

The primary commands file acts as a surrogate terminal. Once it is accessed as a
source of commands, it continues to act in this capacity until all commands have
been executed or the application has ended. This differs from the USE file in that,
if a USE file contains a command that returns control to the program (such as STEP
or GO), all subsequent commands are discarded. However, USE files started from
within a primary commands file take on the characteristics of the primary
commands file and can be executed until complete.
The initial command list, whether it consists of a command string included in the
run-time options or a primary commands file, can contain a USE command to get
commands from a secondary file. If started from the primary commands file, a
USE file takes on the characteristics of the primary commands file.
Running in batch mode

In batch mode, when the end of your commands file is reached, a GO command is
run at each request for a command until the program terminates. If another
command is requested after program termination, a QUIT command is forced.
Starting Debug Tool at different points

If Debug Tool is started during program initialization, invocation occurs before the
main prolog has completed. At that time, no program blocks are active and
references to variables in the main procedure cannot be made, compile units
cannot be called, and GOTO cannot be used. However, references to static variables
can be made.
If you enter STEP at this point, before entering any other commands, both program
and Language Environment initialization will complete and give you access to all
variables. You can also enter all valid commands.
If Debug Tool is started while your program is running (for example, using a
CEETEST call), it might not be able to find all compile units associated with your
application. Compile units located in load modules that are not currently active are
not known to Debug Tool, even if they were run prior to Debug Tool’s
initialization.
Debug Tool also does not know about compile units that were not compiled with
the TEST compiler option, even if they are active, nor does Debug Tool know about
compile units written in unsupported languages.
For example, suppose load module mod1 contains compile units cu1 and cu2, both
compiled with the TEST option. The compile unit cu1 calls cux, contained in load
module mod2, which returns after it completes processing. The compile unit cu2
contains a call to the CEETEST library service. When the call to CEETEST initializes
Debug Tool, only cu1 and cu2 are known to it. Debug Tool does not recognize cux.

The initial command string is performed only once, when Debug Tool is first
initialized in the process.
Commands in the preferences file are performed only once, when Debug Tool is
first initialized in the process.
Session log
The session log stores the commands entered and the results of the execution of
those commands. The session log saves the results of the execution of the
commands as comments. This allows you to use the session log as a commands
file.
Related tasks
“Link-editing CEEBXITA into your program” on page 47
Related references
Precedence of Language Environment run-time options

The Language Environment run-time options have the following order of
precedence (from highest to lowest):
1. Installation options in the CEEDOPT file that were specified as nonoverrideable
with the NONOVR attribute.
2. Options specified by the Language Environment assembler user exit. In the
CICS environment, Debug Tool uses the DTCN transaction and the customized
Language Environment user exit EQADCCXT, which is link-edited with the
application. In the IMS Version 8 environment, IMS retrieves the options that
most closely match the options in its Language Environment run-time options
table. You can edit this table by using Debug Tool Utilities.
3. Options specified at the invocation of your application, using the TEST run-time
option, unless accepting run-time options is disabled by Language Environment
(EXECOPS/NOEXECOPS).
4. Options specified within the source program (with #pragma or PLIXOPT) or
application options specified with CEEUOPT and link-edited with your
application.
If the object module for the source program is input to the linkage editor before
the CEEUOPT object module, then these options override CEEUOPT defaults.
You can force the order in which objects modules are input by using linkage
editor control statements.
5. Region-wide CICS or IMS options defined within CEEROPT.
6. Option defaults specified at installation in CEEDOPT.
7. IBM-supplied defaults.
Suboptions are processed in the following order:

1. Commands entered at the command line override any defaults or suboptions
specified at run time.
2. Commands executed from a preferences file override the command string and
any defaults or suboptions specified at run time.
3. Commands from a commands file override default suboptions, suboptions
specified at run time, commands in a command string, and commands in a
preferences file.
Chapter 15. Starting Debug Tool by using the TEST run-time option 65
Related references
z/OS Language Environment Programming Guide
Example: TEST run-time options

The following examples of using the TEST run-time option are provided to
illustrate run-time options available for your programs. They do not illustrate
complete commands. The complete syntax of the TEST run-time option can be
found in the Debug Tool for z/OS Reference and Messages.
NOTEST Debug Tool is not started at program initialization. Note that a call to
CEETEST, PLITEST, or __ctest() causes Debug Tool to be started during the
program’s execution.
NOTEST(ALL,MYCMDS,*,*)
Debug Tool is not started at program initialization. Note that a call to
CEETEST, PLITEST, or __ctest() causes Debug Tool to be started during the
program’s execution. After Debug Tool is started, the suboptions specified
become effective and the commands in the file allocated to DD name of
MYCMDS are processed.
TEST Specifying TEST with no suboptions causes a check for other possible
definitions of the suboption. For example, C and C++ allow default
suboptions to be selected at compile time using #pragma runopts. Similarly,
PL/I offers the PLIXOPT string. Language Environment provides the macro
CEEXOPT. Using this macro, you can specify installation and
program-specific defaults.
If no other definitions for the suboptions exist, the IBM-supplied default
suboptions are (ALL, *, PROMPT, INSPREF).
TEST(ALL,*,*,*)
Debug Tool is not started initially; however, any condition or an attention
in your program causes Debug Tool to be started, as does a call to CEETEST,
PLITEST, or __ctest(). Neither a primary commands file nor preferences
file is used.
TEST(NONE,,*,*)
Debug Tool is not started initially and begins by running in a "production
mode", that is, with minimal effect on the processing of the program.
However, Debug Tool can be started using CEETEST, PLITEST, or __ctest().
TEST(ALL,test.scenario,PROMPT,prefer)
Debug Tool is started at the end of environment initialization, but before
the main program prolog has completed. The ddname prefer is processed
as the preferences file, and subsequent commands are found in data set
test.scenario. If all commands in the commands file are processed and
you issue a STEP command when prompted, or a STEP command is
executed in the commands file, the main block completes initialization
(that is, its AUTOMATIC storage is obtained and initial values are set). If
Debug Tool is reentered later for any reason, it continues to obtain
commands from test.scenario repeating this process until end-of-file is
reached. At this point, commands are obtained from your terminal.
TEST(ALL,,,MFI%F000:)
For CICS dual terminal and CICS batch, Debug Tool is started on the
terminal F000 at the end of the environment initialization.
TEST(ALL,,,MFI%TCP00001:)
For environments other than CICS, Debug Tool is started on the terminal

associated with the VTAM LU TCP00001. This terminal must be known to
VTAM and not in session when Debug Tool is started.
Remote debug mode
If you are working in remote debug mode, that is, you are debugging your
host application from your workstation, the following examples apply:
TEST(,,,VADTCPIP&machine.somewhere.something.com:*)
TEST(,,,VADTCPIP&9.24.104.79:*)
NOTEST(,,,VACTCPIP&9.24.111.55:*)
Related references
Specifying additional run-time options with COBOL II and PL/I

programs
There are two additional run-time options that you might need to specify to debug
COBOL and PL/I programs: STORAGE and TRAP(ON).
Specifying the STORAGE run-time option

The STORAGE run-time option controls the initial content of storage when allocated
and freed, and the amount of storage that is reserved for the ″out-of-storage″
condition. When you specify one of the parameters in the STORAGE run-time option,
all allocated storage processed by the parameter is initialized to that value. If your
program does not have self-initialized variables, you must specify the STORAGE
run-time option.
Specifying the TRAP(ON) run-time option

The TRAP(ON) run-time option is used to fully enable the Language Environment
condition handler that passes exceptions to the Debug Tool. Along with the TEST
option, it must be used if you want the Debug Tool to take control automatically
when an exception occurs. You must also use the TRAP(ON) run-time option if you
want to use the GO BYPASS command and to debug handlers you have written.
Using TRAP(OFF) with the Debug Tool causes unpredictable results to occur,
including the operating system cancelling your application and Debug Tool when a
condition, abend, or interrupt is encountered.
Note: This option replaces the OS PL/I and VS COBOL II STAE/NOSTAE options.
Specifying TEST run-time option with #pragma runopts in C and C++

The TEST run-time option can be specified either when you start your program, or
directly in your source by using this #pragma:
#pragma runopts (test(suboption,suboption...))
This #pragma must appear before the first statement in your source file. For
example, if you specified the following in the source:
#pragma runopts (notest(all,*,prompt))
then entered TEST on the command line, the result would be

TEST(ALL,*,PROMPT).
TEST overrides the NOTEST option specified in the #pragma and, because TEST does
not contain any suboptions of its own, the suboptions ALL, *, and PROMPT remain in
effect.
Chapter 15. Starting Debug Tool by using the TEST run-time option 67
If you link together two or more compile units with differing #pragmas, the options
specified with the first compile are honored. With multiple enclaves, the options
specified with the first enclave (or compile unit) started in each new process are
honored.
If you specify options on the command line and in a #pragma, any options entered
on the command line override those specified in the #pragma unless you specify
NOEXECOPS. Specifying NOEXECOPS, either in a #pragma or with the EXECOPS compiler
option, prevents any command line options from taking effect.
Related tasks

Chapter 16. Starting Debug Tool from a program
Debug Tool can also be started directly from within your program using one of the
following methods:
v Language Environment provides the callable service CEETEST that is started from
Language Environment-enabled languages.
v For C or C++ programs, you can use a __ctest() function call or include a
#pragma runopts specification in your program.
Note: The __ctest() function is not supported in CICS.

v For PL/I programs, you can use a call to PLITEST or by including a PLIXOPT
string that specifies the correct TEST run-time suboptions to start Debug Tool.
To start Debug Tool using these alternatives, you still need to be aware of the TEST
suboptions specified using NOTEST, CEEUOPT, or other "indirect" settings.
“Example: using CEETEST to start Debug Tool from C/C++” on page 71

“Example: using CEETEST to start Debug Tool from COBOL” on page 72
“Example: using CEETEST to start Debug Tool from PL/I” on page 73
Related tasks
“Starting Debug Tool with CEETEST”
“Starting Debug Tool with PLITEST” on page 75
“Starting Debug Tool with the __ctest() function” on page 75
“Using CEEUOPT to start Debug Tool under CICS” on page 88
Related references
“Special considerations while using the TEST run-time option” on page 63
Starting Debug Tool with CEETEST

Using CEETEST, you can start Debug Tool from within your program and send it a
string of commands. If no command string is specified, or the command string is
insufficient, Debug Tool prompts you for commands from your terminal or reads
them from the commands file. In addition, you have the option of receiving a
feedback code that tells you whether the invocation procedure was successful.
If you don’t want to compile your program with hooks, you can use CEETEST calls
to start Debug Tool at strategic points in your program. If you decide to use this
method, you still need to compile your application so that symbolic information is
created.
Using CEETEST when Debug Tool is already initialized results in a reentry that is
similar to a breakpoint.
The syntax for CEETEST is:
For C and C++
void CEETEST ( , ) ;
string_of_commands fc

For COBOL
CALL "CEETEST" USING string_of_commands , fc ;
For PL/I
CALL CEETEST ( * , * ) ;
string_of_commands fc
string_of_commands (input)
Halfword-length prefixed string containing a Debug Tool command list,
string_of_commands is optional.
If Debug Tool is available, the commands in the list are passed to the debugger
and carried out.
If string_of_commands is omitted, Debug Tool prompts for commands in
interactive mode.
For Debug Tool, remember to use the continuation character if your command
exceeds 72 characters.
fc (output)
A 12-byte feedback code, optional in some languages, that indicates the result of
this service.
CEE000
Severity = 0
Msg_No = Not Applicable
Message = Service completed successfully
CEE2F2
Severity = 3
Msg_No = 2530
Message = A debugger was not available
Note: The CEE2F2 feedback code can also be obtained by MVS/JES batch
applications. For example, either the Debug Tool environment was
corrupted or the debug event handler could not be loaded.
Language Environment provides a callable service called CEEDCOD to help you

decode the fields in the feedback code. Requesting the return of the feedback code
is recommended.
For C and C++ and COBOL, if Debug Tool was started through CALL CEETEST, the
GOTO command is only allowed after Debug Tool has returned control to your
program via STEP or GO.
Usage notes
C and C++
Include leawi.h header file.
COBOL
Include CEEIGZCT. CEEIGZCT is in the Language Environment SCEESAMP
data set.

PL/I Include CEEIBMAW and CEEIBMCT. CEEIBMAW is in the Language Environment
SCEESAMP data set.
Batch and CICS nonterminal processes
We strongly recommend that you use feedback codes (fc) when using
CEETEST to initiate Debug Tool from a batch process or a CICS nonterminal
task; otherwise, results are unpredictable.
“Example: using CEETEST to start Debug Tool from C/C++”

“Example: using CEETEST to start Debug Tool from COBOL” on page 72
“Example: using CEETEST to start Debug Tool from PL/I” on page 73
Related tasks
“Entering multiline commands in full-screen and line mode” on page 183
Related references
Example: using CEETEST to start Debug Tool from C/C++

The following examples show how to use the Language Environment callable
service CEETEST to start Debug Tool from C or C++ programs.
Example 1
In this example, an empty command string is passed to Debug Tool and a
pointer to the Language Environment feedback code is returned. If no
other TEST run-time options have been compiled into the program, the call
to CEETEST starts Debug Tool with all defaults in effect. After it gains
control, Debug Tool prompts you for commands.
#include <leawi.h>
#include <string.h>
#include <stdio.h>
int main(void) {
_VSTRING commands;
_FEEDBACK fc;
strcpy(commands.string, "");
commands.length = strlen(commands.string);
CEETEST(&commands, &fc);
}
Example 2
In this example, a string of valid Debug Tool commands is passed to
Debug Tool and a pointer to Language Environment feedback code is
returned. The call to CEETEST starts Debug Tool and the command string is
processed. At statement 23, the values of x and y are displayed in the Log,
and execution of the program resumes. Barring further interrupts, Debug
Tool regains control at program termination and prompts you for
commands. The command LIST(z) is discarded when the command GO is
executed.
Note: If you include a STEP or GO in your command string, all commands

after that are not processed. The command string operates like a
commands file.
#include <leawi.h>
#include <string.h>
#include <stdio.h>
Chapter 16. Starting Debug Tool from a program 71

int main(void) {
_VSTRING commands;
_FEEDBACK fc;
strcpy(commands.string, "AT LINE 23; {LIST(x); LIST(y);} GO; LIST(z)");

commands.length
. = strlen(commands.string);
.
.
CEETEST(&commands,
. &fc);
.
.
}
Example 3
In this example, a string of valid Debug Tool commands is passed to
Debug Tool and a pointer to the feedback code is returned. If the call to
CEETEST fails, an informational message is printed.
If the call to CEETEST succeeds, Debug Tool is started and the command
string is processed. At statement 30, the values of x and y are displayed in
the Log, and execution of the program resumes. Barring further interrupts,
Debug Tool regains control at program termination and prompts you for
commands.
#include <leawi.h>
#include <string.h>
#include <stdio.h>
#define SUCCESS "\0\0\0\0"
int main (void) {
int x,y,z;
_VSTRING commands;
_FEEDBACK fc;
strcpy(commands.string,"AT LINE 30 { LIST(x); LIST(y); } GO;");

commands.length = strlen(commands.string);
.
.
.
CEETEST(&commands,&fc);
.
.
.
if (memcmp(&fc,SUCCESS,4) != 0) {
printf("CEETEST failed with message number %d\n",fc.tok_msgno);
return(2999);
}
}
Example: using CEETEST to start Debug Tool from COBOL

service CEETEST to start Debug Tool from COBOL programs.
Example 1
A command string is passed to Debug Tool at its invocation and the
feedback code is returned. After it gains control, Debug Tool becomes
active and prompts you for commands or reads them from a commands
file.
01 FC.
02 CONDITION-TOKEN-VALUE.
COPY CEEIGZCT.
03 CASE-1-CONDITION-ID.
04 SEVERITY PIC S9(4) BINARY.
04 MSG-NO PIC S9(4) BINARY.
03 CASE-2-CONDITION-ID
REDEFINES CASE-1-CONDITION-ID.
04 CLASS-CODE PIC S9(4) BINARY.

04 CAUSE-CODE PIC S9(4) BINARY.
03 CASE-SEV-CTL PIC X.
03 FACILITY-ID PIC XXX.
02 I-S-INFO PIC S9(9) BINARY.
77 Debugger PIC x(7) Value 'CEETEST'.
01 Parms.
05 AA PIC S9(4) BINARY Value 14.
05 BB PIC x(14) Value 'SET SCREEN ON;'.
CALL Debugger USING Parms FC.

Example 2
A string of commands is passed to Debug Tool when it is started. After it
gains control, Debug Tool sets a breakpoint at statement 23, runs the LIST
commands and returns control to the program by running the GO
command. The command string is already defined and assigned to the
variable COMMAND-STRING by the following declaration in the DATA
DIVISION of your program:
01 COMMAND-STRING.
05 AA PIC 99 Value 60 USAGE IS COMPUTATIONAL.
05 BB PIC x(60) Value 'AT STATEMENT 23; LIST (x); LIST (y); GO;'.
The result of the call is returned in the feedback code, using a variable
defined as:
01 FC.
02 CONDITION-TOKEN-VALUE.
COPY CEEIGZCT.
03 CASE-1-CONDITION-ID.
04 SEVERITY PIC S9(4) BINARY.
04 MSG-NO PIC S9(4) BINARY.
03 CASE-2-CONDITION-ID
REDEFINES CASE-1-CONDITION-ID.
04 CLASS-CODE PIC S9(4) BINARY.
04 CAUSE-CODE PIC S9(4) BINARY.
03 CASE-SEV-CTL PIC X.
03 FACILITY-ID PIC XXX.
02 I-S-INFO PIC S9(9) BINARY.
in the DATA DIVISION of your program. You are not prompted for
commands.
CALL "CEETEST" USING COMMAND-STRING FC.
Example: using CEETEST to start Debug Tool from PL/I

service CEETEST to start Debug Tool from PL/I programs.
Example 1
No command string is passed to Debug Tool at its invocation and no
active and prompts you for commands or reads them from a commands
file.
CALL CEETEST(*,*); /* omit arguments */
Example 2
A command string is passed to Debug Tool at its invocation and the
active and executes the command string. Barring any further interruptions,
the program runs to completion, where Debug Tool prompts for further
commands.

DCL ch char(50)
init('AT STATEMENT 10 DO; LIST(x); LIST(y); END; GO;');
DCL 1 fb,
5 Severity Fixed bin(15),
5 MsgNo Fixed bin(15),
5 flags,
8 Case bit(2),
8 Sev bit(3),
8 Ctrl bit(3),
5 FacID Char(3),
5 I_S_info Fixed bin(31);
DCL CEETEST ENTRY ( CHAR(*) VAR OPTIONAL,

1 optional ,
254 real fixed bin(15), /* MsgSev */
254 real fixed bin(15), /* MSGNUM */
254 /* Flags */,
255 bit(2), /* Flags_Case */
255 bit(3), /* Flags_Severity */
255 bit(3), /* Flags_Control */
254 char(3), /* Facility_ID */
254 fixed bin(31) ) /* I_S_Info */
options(assembler) ;
CALL CEETEST(ch, fb);

Example 3
This example assumes that you use predefined function prototypes and
macros by including CEEIBMAW, and predefined feedback code constants and
macros by including CEEIBMCT.
A command string is passed to Debug Tool that sets a breakpoint on every
tenth executed statement. Once a breakpoint is reached, Debug Tool
displays the current location information and continues the execution.
After the CEETEST call, the feedback code is checked for proper execution.
Note: The feedback code returned is either CEE000 or CEE2F2. There is no

way to check the result of the execution of the command passed.
%INCLUDE CEEIBMAW;
%INCLUDE CEEIBMCT;
DCL 01 FC FEEDBACK;
/* if CEEIBMCT is NOT included, the following DECLARES need to be

provided: ---------- comment start -------------
Declare CEEIBMCT Character(8) Based;

Declare ADDR Builtin;
%DCL FBCHECK ENTRY;
%FBCHECK: PROC( fbtoken, condition ) RETURNS( CHAR );
DECLARE
fbtoken CHAR;
condition CHAR;
RETURN('(ADDR('||fbtoken||')–>CEEIBMCT = '||condition||')');
%END FBCHECK;
%ACT FBCHECK;
---------- comment end --------------- */
Call CEETEST('AT Every 10 STATEMENT * Do; Q Loc; Go; End;'||

'List AT;', FC);
If ¬FBCHECK(FC, CEE000)
Then Put Skip List('––––> ERROR! in CEETEST call', FC.MsgNo);

Starting Debug Tool with PLITEST
For PL/I programs, the preferred method of Starting Debug Tool is to use the
built-in subroutine PLITEST. It can be used in exactly the same way as CEETEST,
except that you do not need to include CEEIBMAW or CEEIBMCT, or perform
declarations.
The syntax is:
CALL PLITEST ;
( character_string_expression )
character_string_expression
Specifies a list of Debug Tool commands. If necessary, this is converted to a
fixed-length string.
Notes:
1. If Debug Tool executes a command in a CALL PLITEST command string that
causes control to return to the program (GO for example), any commands
remaining to be executed in the command string are discarded.
2. If you don’t want to compile your program with hooks, you can use CALL
PLITEST statements as hooks and insert them at strategic points in your
program. If you decide to use this method, you still need to compile your
application so that symbolic information is created.
The following examples show how to use PLITEST to start Debug Tool for PL/I.
Example 1
No argument is passed to Debug Tool when it is started. After gaining
control, Debug Tool prompts you for commands.
CALL PLITEST;
Example 2
A string of commands is passed to Debug Tool when it is started. After
gaining control, Debug Tool sets a breakpoint at statement 23, and returns
control to the program. You are not prompted for commands. In addition,
the List Y; command is discarded because of the execution of the GO
command.
CALL PLITEST('At statement 23 Do; List X; End; Go; List Y;');
Example 3
Variable ch is declared as a character string and initialized as a string of
commands. The string of commands is passed to Debug Tool when it is
started. After it runs the commands, Debug Tool prompts you for more
commands.
DCL ch Char(45) Init('At Statement 23 Do; List x; End;');
CALL PLITEST(ch);
Starting Debug Tool with the __ctest() function

You can also use the C and C++ library routine __ctest() or ctest() to start
Debug Tool. Add:
#include <ctest.h>
to your program to use the ctest() function.

Note: If you do not include ctest.h in your source or if you compile using the
option LANGLVL(ANSI), you must use __ctest() function. The __ctest()
function is not supported in CICS.
When a list of commands is specified with __ctest(), Debug Tool runs the
commands in that list. If you specify a null argument, Debug Tool gets commands
by reading from the supplied commands file or by prompting you. If control
returns to your application before all commands in the command list are run, the
remainder of the command list is ignored. Debug Tool will continue reading from
the specified commands file or prompt for more input.
If you do not want to compile your program with hooks, you can use __ctest()
function calls to start Debug Tool at strategic points in your program. If you decide
to use this method, you still need to compile your application so that symbolic
information is created.
Using __ctest() when Debug Tool is already initialized results in a reentry that is
similar to a breakpoint.
The syntax for this option is:
(1)
int __ctest ( char *char_str_exp ) ;
Notes:
1 The syntax for ctest() and __ctest() is the same.
char_str_exp
Specifies a list of Debug Tool commands.
The following examples show how to use the __ctest() function for C and C++.
Example 1
A null argument is passed to Debug Tool when it is started. After it gains
control, Debug Tool prompts you for commands (or reads commands from
the primary commands file, if specified).
__ctest(NULL);
Example 2
A string of commands is passed to Debug Tool when it is started. At
statement 23, Debug Tool lists x and y, then returns control to the program.
You are not prompted for commands. In this case, the command list z; is
never executed because of the execution of the command GO.
__ctest("at line 23 {"
" list x;"
" list y;"
"}"
"go;"
"list z;");
Example 3
Variable ch is declared as a pointer to character string and initialized as a
string of commands. The string of commands is passed to Debug Tool
when it is started. After it runs the string of commands, Debug Tool
prompts you for more commands.

char
. *ch = "at line 23 list x;";
.
.
__ctest(ch);
Example 4
A string of commands is passed to Debug Tool when it is started. After
Debug Tool gains control, you are not prompted for commands. Debug
Tool runs the commands in the command string and returns control to the
program by way of the GO command.
#include <stdio.h>
#include <string.h>
char *ch = "at line 23 printf(\"x.y is %d\n\", x.y); go;";

char buffer[35.132];
strcpy(buffer, "at change x.y;");
__ctest(strcat(buffer, ch));

Chapter 17. Starting your program when starting a debug
session
After you decide what level of testing you want to employ during your debug
session, you can start your program using the proper TEST run-time option for
your language. If you are using Debug Tool, this requires no special procedures,
although there are certain considerations depending on the environment where
you are debugging your program. Before you begin your session, make sure all
Debug Tool and program libraries are available and that all necessary Debug Tool
files, such as the session log file, the primary commands file, the preferences file,
and any desired USE files are defined and created. If the program you want to
debug is authorized, ensure that the Debug Tool load library SEQAMOD is
authorized and placed in the MVS LNKLST concatenation.
Related tasks
“Starting Debug Tool under CICS”
“Starting Debug Tool under MVS in TSO”
“Starting Debug Tool in batch” on page 81
Starting Debug Tool under CICS

To use Debug Tool under CICS, you need to ensure that all of the required
installation and configuration steps for CICS Transaction Server, Language
Environment, and Debug Tool have been completed. For more information, refer to
the installation and customization guides for each product.
You can start Debug Tool in four ways:

Single terminal mode
Debug Tool displays its screens on the same terminal as the application.
This can be set up using DTCN, CEETEST, pragma, or CEEUOPT(TEST).
Dual terminal mode
Debug Tool displays its screens on a different terminal than the one used
by the application. This can be set up with DTCN or CEDF.
Batch mode
Debug Tool does not have a terminal, but uses a commands file for input
and writes output to the log. This can be set up using DTCN, CEETEST,
pragma, or CEEUOPT(TEST).
Remote debug mode
Debug Tool works with a remote debugger to display results on a
graphical user interface. This can be set up using DTCN, CEETEST, pragma, or
CEEUOPT(TEST).
Related tasks
Chapter 36, “Debugging CICS programs,” on page 249
Starting Debug Tool under MVS in TSO

You have two choices to start Debug Tool under MVS in TSO:

v You can follow the instructions outlined in this section. The instructions describe
how to allocate all the files you need to start your debug session and how to
start your program with the proper parameters.
v Use the Debug Tool Setup Utility (DTSU). DTSU helps you allocate all the files
you need to start your debug session, and can start your program or submit
your batch job. For more information about DTSU, refer to Chapter 14, “Starting
Debug Tool from the Debug Tool Utilities,” on page 59.
To begin a debug session, ensure your program has been compiled with the TEST
compiler option, and take the following steps:
1. Make sure all Debug Tool data sets are available. This might involve defining
them as part of a STEPLIB library.
Note: High-level qualifiers and load library names will be specific to your
installation. Ask the person who installed Debug Tool what the data sets
are called. The names will probably end in SEQAMOD. These data sets
might already be in the linklist or included in your TSO logon
procedure, in which case you don’t need to do anything to access them.
The installation options will determine whether or not this step is needed.
2. Allocate all other data sets containing files your program needs.
3. If you want a session log file, allocate one. This is a file that keeps a record of
your debug session and can be used as a commands file during subsequent
sessions. Do not allocate the session log file to a terminal. For example, do not
use ALLOC FI(INSPLOG) DA(*).
4. Start your program with the TEST run-time option, specifying the appropriate
suboptions, or include a call to CEETEST, PLITEST, or __ctest() in the program’s
source.
The following two example CLISTs show how you might allocate the Debug Tool
load library data set (SEQAMOD) if it is not in the linklist or TSO logon
procedure:
PROC 0 TEST
TSOLIB ACTIVATE DA(’EQAW.SEQAMOD’)
END
and
PROC 0 TEST
TSOLIB DEACTIVATE
FREE FILE(SEQAMOD)
ALLOCATE DA(’EQAW.SEQAMOD’) FILE(SEQAMOD) SHR REUSE
TSOLIB ACTIVATE FILE(SEQAMOD)
END
If you store either example CLIST in MYID.CLIST(DTSETUP), you can execute the
CLIST by entering the following at the TSO READY prompt:
EXEC ’MYID.CLIST(DTSETUP)’
The CLIST will execute and the appropriate Debug Tool data set will be allocated.
After allocating all necessary program data sets, the command line is used to
allocate the preferences file setup.pref and the session log file session.log as
shown in the following example:
ALLOCATE FILE(insppref) DATASET(setup.pref) REUSE
ALLOCATE FILE(insplog) DATASET(session.log) REUSE
CALL 'USERID1.MYLIB(TSTSCRPT)' '/TEST'

No primary commands file is created. The TEST run-time option is entered from the
command line during invocation of the COBOL program tstscrpt. Default
run-time suboptions are assumed, as well as the Language Environment default
run-time options for your installation.
The following CLIST fragment shows how to define Debug Tool-related files and
start the C program prog1 with the TEST run-time option:
ALLOC FI(inspsafe) DA(debug.save) REUSE
ALLOC FI(insplog) DA(debug.log) REUSE
ALLOC FI(insppref) DA(debug.preferen) REUSE
CALL 'MYID.MYQUAL.LOAD(PROG1)' +
' TRAP(ON) TEST(,*,;,insppref)/'
Files include the session log file, debug.log; the preferences file, debug.preferen;
and the settings file, debug.save, a Debug Tool file that saves Debug Tool settings
for use in future debug sessions. Its Debug Tool-supplied default ddname is
inspsafe. All necessary data sets must exist prior to Starting this CLIST.
Starting your program from a terminal that works only in line mode results in a
line-mode session of Debug Tool. If you want to debug in line mode and you have
a 3270-compatible terminal that is capable of sustaining a full-screen session, you
must specify SET SCREEN OFF. You can specify this with the TEST run-time option
by including the command in a preferences file, or by specifying it as a command
string (for example, TEST(,*,"SET SCREEN OFF",insppref)).
To start Debug Tool from a terminal other than the terminal currently controlling
your TSO session, use the VTAM_LU_id parameter to specify the LU id of a VTAM
terminal. The VTAM terminal you specify controls your debugging session as long
as you remain in full-screen mode. If you enter line mode, control reverts to your
TSO terminal until you re-enter full-screen mode using the SET SCREEN ON
command.
Related tasks
“Recording your debug session in a log file” on page 107
Related references
Starting Debug Tool in batch

You have two choices to start Debug Tool in batch mode:
v You can follow the instructions outlined in this section. This includes modifying
your JCL to include the appropriate Debug Tool data sets and TEST runtime
options.
v Use the Debug Tool Setup Utility (DTSU). DTSU can generate JCL that includes
the appropriate Debug Tool data sets and TEST runtime options, and can submit
your batch job. For more information about DTSU, refer to Chapter 14, “Starting
Debug Tool from the Debug Tool Utilities,” on page 59.
Before starting Debug Tool in batch mode, ensure that you have compiled your
program with the TEST compiler option. Next, modify the JCL to run your batch
program to include the appropriate Debug Tool data sets and to specify the TEST
run-time option. Finally, run the modified JCL.
Chapter 17. Starting your program when starting a debug session 81

Sample JCL for a batch debug session for the COBOL program, EMPLRUN, is
provided below. The job card and data set names need to be modified to suit your
installation.
//DEBUGJCL JOB <appropriate JOB card information>
//* ****************************************************************
//* JCL to run a batch Debug Tool session
//* Program EMPLRUN was previously compiled with the COBOL
//* compiler TEST option
//* ****************************************************************
//STEP1 EXEC PGM=EMPLRUN,
// PARM=’/TEST(,INSPIN,,)’
//*
//* Include the Debug Tool SEQAMOD data set
//*
//STEPLIB DD DISP=SHR,DSN=userid.TEST.LOAD
// DD DISP=SHR,DSN=EQAW.SEQAMOD
//*
//* Specify a commands file with DDNAME matching the one
//* specified in the /TEST runtime option above
//* This example shows inline data but a data set could be
//* specified like: //INSPIN DD DISP=SHR,DSN=userid.TEST.INSPIN
//*
//INSPIN DD *
STEP;
AT *
PERFORM
QUERY LOCATION;
GO;
END-PERFORM;
GO;
QUIT;
/*
//*
//* Specify a log file for the debug session
//* Log file can be a data set with LRECL >= 42 and <= 256
//* For COBOL only, use LRECL <= 72 if you are planning to
//* use the log file as a commands file in subsequent Debug
//* Tool sessions. You can specify the log file like:
//* //INSPLOG DD DISP=SHR,DSN=userid.TEST.INSPLOG
//*
//INSPLOG DD SYSOUT=*,DCB=(LRECL=72,RECFM=FB,BLKSIZE=7200)
//SYSPRINT DD SYSOUT=*
//SYSUDUMP DD DUMMY
//SYSOUT DD SYSOUT=*
/*
//
You can debug an MVS batch job in full-screen mode. Use the MFI option to
specify the LU name of a VTAM terminal that interacts with Debug Tool. In the
previous example, change the EXEC statement to specify the LU name of the VTAM
terminal. For example:
//STEP1 EXEC PGM=EMPLRUN,
// PARM=’/TEST(,INSPIN,,MFI%ABC00001:)’
Related tasks
Appendix D, “Notes on debugging in batch mode,” on page 297
Chapter 27, “Entering Debug Tool commands,” on page 181
Appendix E, “Notes on debugging in remote debug mode,” on page 299

Chapter 18. Starting a full-screen debug session
You can start Debug Tool by using the Language Environment TEST run-time
option in one of the following ways:
v Using the Debug Tool Setup Utility (DTSU). DTSU helps you allocate files and
can start your program. The methods listed below describe how you manually
perform the same tasks.
v For TSO, if your system programmer has not installed Debug Tool in the
standard search path, you need to include the Debug Tool library in your
STEPLIB concatenation. Start your program with the TEST run-time option as
shown in the following examples:
– For C, C++, and PL/I:
CALL ’USERID1.MYLIB(MYPROG)’ ’TEST/prog arg list’
– For COBOL:
CALL ’USERID1.MYLIB(MYPROG)’ ’prog arg list/TEST’
Contact your systems programmer if you do not know the name of the Debug
Tool library on your system.
To control Debug Tool from a separate terminal, specify the VTAM LU identifier
of the separate terminal in the TEST parameter, as in the following example:
’TEST(,,,MFI%TCP00001:)/’`
v For MVS batch, if your system programmer has not installed Debug Tool in the
standard search path, you need to include the Debug Tool library in your
STEPLIB concatenation . Start your program with the TEST run-time option
specifying the VTAM LU identifier of a terminal, as in the following example
’TEST(,,,MFI%TCP00001:)/’
v For CICS, make sure Debug Tool is installed in your CICS region. Enter DTCN
to start the Debug Tool control transaction. Press PF4 to save the default
debugging profile. Press PF3 to exit from the DTCN transaction. Enter the name
of the transaction you want to debug.
Related tasks
Chapter 14, “Starting Debug Tool from the Debug Tool Utilities,” on page 59
“Ending a full-screen debug session” on page 119
Related references

Chapter 19. Special cases for starting Debug Tool
You can start Debug Tool to debug batch programs in full-screen mode, from
programs that run in CICS, and from DB2 stored procedures.
Starting a debugging session in full-screen mode through a VTAM

terminal
You can debug batch programs interactively by using a full-screen mode
debugging session through a VTAM terminal. Before you start this debugging
session, contact your system administrator to verify that your system was
customized to support this type of debugging session.
To start a debugging session in full-screen mode through a VTAM terminal, do the

following:
1. Start two terminal emulators. Connect the second terminal emulator to a
terminal LU that can handle a full-screen mode debugging session through a
VTAM terminal.
2. On the first terminal emulator, log on to TSO.
3. Note the LU name of the second terminal emulator. If the second terminal
emulator displays a session manager screen, exit from the session manager.
4. Edit the PARM string of your batch job so that you specify the TEST run time
parameter as follows:
TEST(,,,MFI%luname:*)
Place a slash (/) before or after the parameter, depending on your

programming language. luname is the VTAM LU name of the second terminal
emulator.
5. Submit the batch job.
6. On the second emulator session, a full-screen mode debugging session is
displayed. Interact with it in the same way you with any other full-screen
mode debugging session.
After the debugging session has ended, repeat steps 5 and 6 to create another
full-screen mode debugging session.
Starting Debug Tool from DB2 stored procedures: troubleshooting

The examples used in this section are based on examples introduced in Chapter 11,
“Preparing a DB2 stored procedures program,” on page 45.
If the remote debugger does not start when the stored procedure calls it, verify
that the TCP/IP address is defined correctly in the DB2 catalog. When the stored
procedure is called, the remote debugger source window is refreshed with the
source or listing of the stored procedure.
To verify that the stored procedure has started, enter the following DB2 Display
command, where xxxx is the name of the stored procedure:
Display Procedure(xxxx)

If the stored procedure is not started, enter the following DB2 command:
Start procedure(xxxx)
For DB2 Version 6, to switch from remote debug mode to full-screen mode through
a VTAM terminal, change the definition of the stored procedure as follows, where
TCP00095 is the VTAM LU name:
alter procedure SPROC1 run options ’TEST(,,,MFI%TCP00095:)’
Related tasks
Starting Debug Tool under CICS

There are several different mechanisms available to start Debug Tool under CICS.
Each mechanism has a different advantage and are listed below:
v DTCN, a full-screen CICS transaction that allows you to dynamically modify
any Language Environment TEST/NOTEST run-time option with which your
application was originally link-edited. You can also use DTCN to modify other
Language Environment run-time options that are not specific to Debug Tool.
DTCN is the recommended mechanism for starting Debug Tool sessions. See
Chapter 12, “Preparing a CICS program,” on page 47 to learn how to set up
profiles by using DTCN.
v Language Environment CEEUOPT module link-edited into your application,
containing an appropriate TEST option, which tells Language Environment to
start Debug Tool every time the application is run.
This mechanism can be useful during initial testing of new code when you will
want to run Debug Tool frequently.
v A compiler directive within the application, such as #pragma runopts(test) (for
C and C++) or CALL CEETEST.
These directives can be useful when you need to run multiple debug sessions for
a piece of code that is deep inside a multiple enclave or multiple CU
application. The application runs without Debug Tool until it encounters the
directive, at which time Debug Tool is started at the precise point that you
specify. With CALL CEETEST, you can even make the invocation of Debug Tool
conditional, depending on variables that the application can test.
v CICS CEDF utility where you can start a debug session in Dual Terminal mode
alongside CEDF, using a special option on the CEDF command.
This mechanism does not require you to change the application link-edit options
or code, so it can be useful if you need to debug programs that have been
compiled with the TEST option, but do not have invocation mechanisms built
into them.
If your program uses several of these methods, the order of precedence is

determined by Language Environment. For more information about the order of
precedence for Language Environment run-time options, see z/OS Language
Environment Programming Guide.
Related tasks
“Using CEDF to start Debug Tool under CICS” on page 88
Related references
“Debug modes under CICS” on page 249

Using DTCN to start Debug Tool for CICS programs
DTCN is a menu-driven tool that allows you to specify when to activate Debug
Tool for CICS programs. You can do this by entering your debugging requirements
into the DTCN panels from your CICS terminal. DTCN then saves these
debugging requirements in its repository. When a CICS program starts, Debug Tool
is started if the task environment matches a repository item.
DTCN profiles contain the identifiers (IDs) of CICS resources to debug. These
resource IDs can be Terminal, Transaction, Program, or User.
To debug a CICS program by using DTCN to start Debug Tool, update the
link-edit step to include the EQADCCXT member from the Debug Tool library
**.SEQAMOD into the program’s main load module.
When CICS programs are started, Language Environment runs the EQADCCXT user
exit that you used to link-edit into the program. EQADCCXT uses a highly efficient
look-up mechanism to decide whether the Terminal ID, Transaction ID, Program
ID, and User ID for the task match a repository profile item. EQADCCXT selects the
best matching profile (the one with the greatest number of resource IDs that match
the active task). If two items have an equal number of matching resource IDs, the
older item is selected.
For example, consider the following two profile items:

v First, Item 1 is saved, specifying resource ID program PROG1
v Later, Item 2 is saved, specifying resource ID user ID USER1
When PROG1 is run by USER1, profile item 1 is used.
If this situation occurs, an error message is sent to the system console, suggesting
that DTCN users should specify additional resource qualification. So, in the above
case, each profile item should be set up with both user ID and program ID.
DTCN not only provides the capability to specify what to debug by specifying
debug resource IDs, DTCN also provides the capability to specify how the debug
session will run, for example, whether a mainframe (MFI) or workstation (VAD)
debug session is desired.
When a DTCN profile is active for a full-screen mode debugging session, Debug
Tool preserves in the profile all of the breakpoint information for that session.
When the DTCN profile is deleted, the breakpoint information is deleted. After you
save the profile in the repository, DTCN shows the saved TEST string in the
display field Repository String. When you are satisfied with the saved profile,
press PF3 to exit DTCN.
How to end your CICS debugging session

After you have finished debugging your program, use DTCN again to turn off
your debug profile by pressing PF6 to delete your debug profile and then pressing
PF3 to exit. You do not need to remove EQADCCXT from the load module; in fact, it’s
a good idea to leave it there for the next time you want to start Debug Tool.
Related tasks
Chapter 19. Special cases for starting Debug Tool 87

Using CEEUOPT to start Debug Tool under CICS
To request that Language Environment start Debug Tool every time the application
is run, assemble a CEEUOPT module with an appropriate TEST run-time option. It
is a good idea to link-edit the CEEUOPT module into a library and just add an
INCLUDE LibraryDDname(CEEUOPT-MemberName) statement to the link-edit options
when you link your application. Once the application program has been placed in
the load library (and NEWCOPY'd if required), whenever it is run Debug Tool will
be started.
Debug Tool runs in the mode defined in the TEST run-time option you supplied,
normally Single Terminal mode, although you could provide a primary commands
file and a log file and not use a terminal at all.
To start Debug Tool, simply run the application. Don’t forget to remove the
CEEUOPT containing your TEST run-time option when you have finished
debugging your program.
Related tasks
Using compiler directives to start Debug Tool under CICS

When compile-directives are processed by your program, Debug Tool will be
started in single terminal mode (this method supports only single terminal mode).
Related tasks
“Starting Debug Tool with CEETEST” on page 69
Using CEDF to start Debug Tool under CICS

No specific preparation is required to use CEDF to start Debug Tool other than
compiling the application with the appropriate compiler options and saving the
source/listing.
CEDF has an ″,I″ option that starts Debug Tool. This option starts both EDF and
Debug Tool in Dual Terminal mode. In Dual Terminal mode, EDF and Debug Tool
screens are displayed on the terminal where you issue the CEDF command;
application screens are displayed on the application terminal.
Note: You need to know the id of each terminal. One way to get this information
is by using the CEOT transaction. The output will include Ter(xxxx), where
xxxx is the terminal id.
To start Debug Tool, enter the CEDF transaction as follows:

CEDF xxxx,ON,I
where xxxx is the terminal on which you want to start the transaction to be
debugged. This terminal is where the application is started. It performs 3270
application I/O, while a Debug Tool session is started at the terminal where CEDF
is started.
CICS will return a message verifying the terminal id of the second terminal. Then,
on the xxxx terminal, enter:
TRAN

where TRAN is the id for the transaction being debugged.
Once the command is entered, Debug Tool will be started for all Language
Environment-enabled programs that are running on the terminal where Debug
Tool is started. Debug Tool will continue to be active on this terminal, even if you
turn off EDF.
For example, to begin a Debug Tool session using terminal T304 as the debugging
terminal and T305 as the terminal where you want to run your application, start
the CEDF transaction as follows on T304:
CEDF T305,ON,I
Then, on terminal T305, enter the name of the transaction you are debugging:
TRAN
When you run your application on T305, Debug Tool is started on T304. Terminal
T305 displays only application output, that is, a specific CICS command to write to
the screen.
Chapter 19. Special cases for starting Debug Tool 89

Part 4. Debugging your programs in full-screen mode

Chapter 20. Using full-screen mode: overview
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.
Note: The PF key definitions used in these topics are the default settings.
Related tasks
Chapter 18, “Starting a full-screen debug session,” on page 83
“Ending a full-screen debug session” on page 119
“Navigating through Debug Tool session panel windows” on page 104
“Recording your debug session in a log file” on page 107
“Setting breakpoints to halt your program at a line” on page 109
“Stepping through or running your program” on page 109
“Displaying error numbers for messages in the Log window” on page 117
“Finding a renamed source, listing, or separate debug file” on page 117
“Requesting an attention interrupt during interactive sessions” on page 118
Chapter 23, “Debugging a C program in full-screen mode,” on page 141
Chapter 24, “Debugging a C++ program in full-screen mode,” on page 151
Chapter 21, “Debugging a COBOL program in full-screen mode,” on page 121
Chapter 22, “Debugging a PL/I program in full-screen mode,” on page 133
Debug Tool session panel

The Debug Tool session panel contains a header with information about the
program you are debugging, a command line, and up to three windows.
Source window
Displays your program source code
Log window
Records your commands and Debug Tools responses
Monitor window
Continuously displays the value of monitored variables and other items,
depending on the command used
The Debug Tool session panel below shows the default layout for the Monitor
window 1, the Source window 2, and the Log window 3.

COBOL LOCATION: IBTUFS4 :> 100.1
MONITOR --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 1 OF 3
******************************* TOP OF MONITOR ********************************
0001 1 77 IBTUFS4:>VARBL2 21
0002 2 77 IBTUFS4:>VARBL1 11 1
0003 3 77 IBTUFS4:>X 1
SOURCE: IBTUFS4 --1----+----2----+----3----+----4----+----5---- LINE: 98 OF 118
98 ADD 1 TO VARBL1 .
99 2 ADD 1 TO VARBL2 .
100 CALL "SUBPRO1" USING BY CONTENT PARAM1 .
101 ADD 1 TO X .
102 END-PERFORM. .
LOG 0----+----1----+----2----+----3----+----4----+----5----+---- LINE: 13 OF 19
0013 The command element MONITOR is invalid.
0014 MONITOR
0015 LIST VARBL2 ;
0016 MONITOR 3
0017 LIST VARBL1 ;
0018 MONITOR
0019 LIST X ;
Related tasks
“Customizing the layout of windows on the session panel” on page 172
Related references
“Session panel header”
“Monitor window” on page 97
“Source window” on page 96
“Log window” on page 98
Session panel header

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.

1 Assemble, C, COBOL, Disassem, or PL/I
The name of the current programming language. This language is not
necessarily the programming language of the code in the Source window.
The language that is displayed in this field determines the syntax rules
that you must follow for entering commands.

Note: Debug Tool does not differentiate between C and C++ programs. If
there is a C++ program in the Source window, only C is displayed
in this field.
2 LOCATION
The program unit name and statement where execution is suspended,
usually in the form compile unit:>nnnnnn.
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.
3 COMMAND
The input area for the next Debug Tool command. You can enter any valid
Debug Tool command here.
4 SCROLL
The number of lines or columns that you want to scroll when you enter a
SCROLL command without an amount specified. To hide this field, enter the
SET SCROLL DISPLAY OFF command. To modify the scroll amount, use the
SET DEFAULT SCROLL command.
The value in this field is the operand applied to the SCROLL UP, SCROLL
DOWN, SCROLL LEFT, and SCROLL RIGHT scrolling commands. Table 6 lists all
the scrolling commands.
Table 6. 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.
5 Message areas

Information and error messages are displayed in the space immediately
below the command line.
Chapter 20. Using full-screen mode: overview 95

Source window
1SOURCE: 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.
1 Header area
Identifies the window, shows the compile unit name, and shows the
current position in the source or listing.
2 Prefix area
Occupies the left-most eight columns of the Source window. Contains
statement numbers or line numbers you can use when referring to the
statements in your program. You can use the prefix area to set, display, and
remove breakpoints with the prefix commands AT, CLEAR, ENABLE, DISABLE,
QUERY, and SHOW.
3 Source display area
Shows the source code (for a C and C++ program), the source listing (for a
COBOL or PL/I program), a pseudo assembler listing (for an assembler
program), or the disassembly view (for programs without debug
information) for the currently qualified program unit. If the current
executable statement is in the source display area, it is highlighted.
4 Suffix area
A narrow, variable-width column at the right of the screen that Debug Tool
uses to display frequency counts. It is only as wide as the largest count it
must display.
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.
Related tasks
“Using prefix commands on specific lines or statements” on page 102
“Customizing profile settings” on page 175

Monitor window
COBOL LOCATION: MULTCU :> 75.1
MONITOR --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 1 OF 2
******************************* TOP OF MONITOR ********************************
0001 1 01 MULTCU:>PROGRAM-USHORT-BIN 00000
0002 2 01 MULTCU:>PROGRAM-SSHORT-BIN +00000
Use the Monitor window to continuously display output from the MONITOR LIST,
MONITOR QUERY, MONITOR DESCRIBE, and SET AUTOMONITOR commands. If this window
is not open, Debug Tool opens it when you enter a MONITOR or SET AUTOMONITOR
command. Its contents are refreshed whenever Debug Tool receives control and
after every Debug Tool command that can affect the display.
When you issue a MONITOR command, it is assigned a reference number between 1

and 99, then added to the monitor list. You can specify the monitor number;
however, you must either replace an existing monitor number or use the next
sequential number.
When you issue the SET AUTOMONITOR ON command, the following line is displayed
at the bottom of the list of monitored variables:
********** AUTOMONITOR **********
Variables that are added to the Monitor window as a result of the SET AUTOMONITOR
command are displayed underneath this line.
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.
If a window is not wide enough to show all the output it contains, you can either
issue SCROLL RIGHT (to scroll the window to the right) or ZOOM (to make it fill the
screen).
window.
You can update the values of monitored variables by typing new values over the
displayed values.
Related tasks
“Scrolling the windows” on page 105

Log window
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. All
commands that are valid in line mode, and their responses, are automatically
appended to the Log window. The following commands are not recorded in the
Log window.
PANEL
FIND
CURSOR
RETRIEVE
SCROLL
WINDOW
IMMEDIATE
QUERY prefix command
SHOW prefix command
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. To change this value,
enter SET LOG KEEP n, where n is the number of lines you want kept for display.
The maximum number of lines is determined by the amount of storage available.
window.
Displaying the source or listing file

Debug Tool displays your source file in the Source Window using a source, listing,
or separate debug file, depending on the compiler. If there is no debug data, you
can display the disassembled code by entering the SET DISASSEMBLY command.
To be able to view your COBOL source code while debugging in full-screen or

remote debug mode, you must direct the source or listing to a nontemporary file
that is available during the debug session. If you are debugging a Enterprise
COBOL for z/OS and OS/390 or COBOL for OS/390 & VM program and specified

the SEPARATE suboption of the compiler option, the listing does not need to be
saved but the separate debug file must be a nontemporary file. The separate debug
file must also be available during the debug session. If you move or rename these
nontemporary files, use the SET SOURCE or SET DEFAULT LISTINGS command to
specify the new location or name of the files.
To be able to view your PL/I listing while debugging in full-screen or remote

debug mode, PL/I for MVS™ & VM and OS PL/I programs must be compiled
using the PL/I SOURCE compiler option. You must also direct the listing to a
nontemporary file that is available during the debug session. During a debug
session, Debug Tool displays the first file it finds named userid.pgmname.list in
the Source window. If Debug Tool cannot find the listing at this location, use the
SET SOURCE command to associate your source listing with the program you are
debugging.
When you start Debug Tool, if your source or listing is not displayed, press PF4.
This puts you in the Source Identification panel. The Source Identification panel
indicates the name of the source, listing or separate debug file that was intended to
be used by Debug Tool. With this name, you can verify if the file exists or if you
have authorization to access it. If your file is stored at a different place, do one of
the following:
v Use the SET SOURCE command with the new name of the source, listing, or
debug file; or
v use the SET DEFAULT LISTINGS command with the new name of the source,
listing or debug file (provided they are stored in a PDS); or
v type over the Listing/Source file field in the Source Identification panel with the
new name for the source, listing, or separate debug file.
Related references
Appendix B, “How does Debug Tool locate debug information and source or
listing files?,” on page 289

Entering commands on the session panel
You can enter a command or modify what is on the session panel in seven areas,
as shown below.
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 ********************************
0001 1 VARBL1 10
0002 2 VARBL2 20
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 ;
1 Command line

You can enter any valid Debug Tool command on the command line.
2 Scroll area
You can redefine the default amount you want to scroll by typing the
desired value over the value currently displayed.
3 Compile unit name area
You can change the qualification by typing the desired qualification over
the value currently displayed. For example, to change the current
qualification from ICFSSCU1, as shown in the Source window header, to
ICFSSCU2, type ICFSSCU2 over ICFSSCU1 and press Enter.
4 Prefix area
You can enter only Debug Tool prefix commands in the prefix area, located
in the left margin of the Source window.
5 Source window
You can modify any lines in the Source window and place them on the
command line.
6 Window id area
You can change your window configuration by typing the name of the
window you want to display over the name of the window that is
currently being displayed.
7 Log window
You can modify any lines in the log and have Debug Tool place them on
the command line.

Related tasks
“Using the session panel command line”
“Issuing system commands”
“Using prefix commands on specific lines or statements” on page 102
“Using commands that are sensitive to the cursor position” on page 102
“Using Program Function (PF) keys to enter commands” on page 102
“Retrieving previous commands” on page 103
“Retrieving commands from the Log and Source windows” on page 104
Related references
“Order in which Debug Tool accepts commands from the session panel”
“Initial PF key settings” on page 103
Order in which Debug Tool accepts commands from the

session panel
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.
1. Prefix area
2. Command line
3. Compile unit name area
4. Scroll area
5. Window id area
6. Source/Log window
Using the session panel command line

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 back slash (\) 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.
Related tasks
Chapter 27, “Entering Debug Tool commands,” on page 181
Issuing system commands

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:
v A command is required after the SYSTEM keyword. Do not enter any required
parameters. Debug Tool prompts you.

v If you are debugging in batch and need system services, you can include
commands and their requisite parameters in a CLIST and substitute the CLIST
name in place of the command.
v If you want to enter several TSO commands, you can include them in a USE file,
a procedure, or other commands list. Or you can enter:
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.
Using prefix commands on specific lines or statements

Certain commands, known as prefix commands, can be typed over the prefix area in
the Source window, and then processed by pressing Enter. These commands (AT,
CLEAR, DISABLE, ENABLE, QUERY, and SHOW) pertain only to the line or lines of code
before which they are typed. For example, the AT command typed in the prefix
area of a specific line sets a statement breakpoint only at that line.
You can use prefix commands to specify the particular verb or statement in the line
where you want the command to apply. For example, AT typed in the prefix area of
a line sets a statement breakpoint at the first relative statement in that line, while
AT 3 sets a statement breakpoint at the third relative statement in that line. Typing
DISABLE 3 in the prefix area and pressing Enter disables that breakpoint.
Using commands that are sensitive to the cursor position

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.
Note: Do not confuse cursor-sensitive commands with the CURSOR command,

which returns the cursor to its last saved position.
Related tasks
“Defining PF keys” on page 171
Using Program Function (PF) keys to enter commands

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.

Related tasks
“Using commands that are sensitive to the cursor position” on page 102
Related references
“Initial PF key settings”
Initial PF key settings

The table below shows the initial PF key settings.
PF key Label Definition Use

PF1 ? ? “Getting online help for Debug Tool
command syntax” on page 185
PF2 STEP STEP “Stepping through or running your
program” on page 109
PF3 QUIT QUIT “Ending a full-screen debug session”
on page 119
PF4 LIST LIST “Finding a renamed source, listing, or
separate debug file” on page 117
PF4 LIST LIST variable_name “Displaying and monitoring the value
of a variable” on page 112
PF5 FIND IMMEDIATE FIND “Finding a string in a window” on
page 105
PF6 AT/CLEAR AT TOGGLE CURSOR “Setting breakpoints to halt your
program at a line” on page 109
PF7 UP IMMEDIATE UP “Scrolling the windows” on page 105
PF8 DOWN IMMEDIATE DOWN “Scrolling the windows” on page 105
PF9 GO GO “Stepping through or running your
program” on page 109
PF10 ZOOM IMMEDIATE ZOOM “Zooming a window to occupy the
whole screen” on page 173
PF11 ZOOM LOG IMMEDIATE ZOOM LOG “Zooming a window to occupy the
whole screen” on page 173
PF12 RETRIEVE IMMEDIATE RETRIEVE “Retrieving previous commands”
Related tasks
Retrieving previous commands

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.
Related tasks

Retrieving commands from the Log and Source windows
You can retrieve lines from the Log and Source windows and use them as new
commands.
To retrieve a line, move the cursor to the desired line, modify it (for example,
delete any comment characters) and press Enter. The input line appears on the
command line. You can further modify the command, then press Enter to issue it.
When retrieving long or multiple Debug Tool commands, a pop-up window is

displayed, with the command as typed in so far. However, trailing blanks on the
last line are removed. To expand the pop-up window, place the cursor below it and
press Enter.
Related tasks
“Retrieving previous commands” on page 103
Navigating through Debug Tool session panel windows

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, 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.
Related tasks
“Moving the cursor between windows”
“Scrolling the windows” on page 105
“Scrolling to a particular line number” on page 105
“Finding a string in a window” on page 105
“Changing which source file appears in the Source window” on page 105
“Displaying the line at which execution halted” on page 106
Moving the cursor between windows

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.
Related tasks

Scrolling the windows
If the cursor is on the command line, you can scroll the Source window by
pressing PF7 (UP) or PF8 (DOWN). To scroll through other windows, place the cursor
in the desired window before pressing PF7 or PF8.
You can toggle one of the Source, Log or Monitor windows to full screen
(temporarily not displaying the others) by moving the cursor into the window you
want to zoom and pressing PF10 (ZOOM). To toggle back, press PF10 again. PF11
(ZOOM LOG) toggles the Log window the same way without the cursor needing to be
in the Log window.
You can scroll any of the windows vertically and horizontally by issuing the
SCROLL UP, DOWN, LEFT, and RIGHT commands (the SCROLL keyword is optional). You
can use the command line to specify which window to scroll. For example, to
scroll the monitor window up 5 lines, enter SCROLL UP 5 MONITOR.
Alternately, you can use the position of the cursor to indicate the window you
want to scroll; if the cursor is in a window, that window is scrolled. If you do not
specify the window, the default window (determined by the setting of the DEFAULT
WINDOW command) is scrolled. You can change the default window by changing the
settings of Default window and Default scroll amount under the Profile Settings
panel.
Related tasks
“Scrolling to a particular line number”
Scrolling to a particular line number

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.
Finding a string in a window

To find the next occurrence of a string within a window:
1. On the command line, type the string you want to find, enclosed in double
quotes (assembler, C, C++, COBOL, or disassembly) or single quotes
(assembler, disassembly, or PL/I), but do not press Enter.
2. Move the cursor into the window to be searched.
3. Press PF5 (FIND).
To repeat the search in whatever window the cursor is in, press PF5 again.
Changing which source file appears in the Source window

To change which source file appears in the Source window, type over the name
after SOURCE:, which is in the Header area of the Source window, with the desired
name. The new name must be the name of a compile unit (CU) that is known to
Debug Tool. To determine which CUs are known to Debug Tool, enter the LIST
NAMES CUS command. By default, the LIST NAMES CUS command does not display

the names of disassembled CUs. If you are debugging an assembler or disassembly
program and want the LIST NAMES CUS to display the names of the disassembled
CUs, enter the SET DISASSEMBLY ON or SET ASSEMBLER ON command before you
enter the LIST NAMES CUS command.
Alternately, you can enter the command:

LIST NAMES CUS
and a list of compile units will be written to the Log window, as shown below.
USERID.MFISTART.C(CALC)
USERID.MFISTART.C(PUSHPOP)
USERID.MFISTART.C(READTOKN)
You can type over or insert characters on one of these lines in the Log window and
press Enter to display the modified text on the command line, for example:
SET QUALIFY CU "USERID.MFISTART.C(READTOKN)"
and then press Enter to issue the command. Typing over a line in the Log window
and issuing them as commands is a way to save keystrokes and reduce errors in
long commands.
Another way to change which source file appears in the Source window is to press
PF4 (LIST) with the cursor on the command line. This displays the Source
Identification Panel, where associations are made between listings or source files
shown in the Source window and their compile units. Type over the Listings/Source
File field with the new name.
For C and C++ only

For C and C++ compile units, Debug Tool requires a file containing the source
code. By default, when Debug Tool encounters a new C and C++ compile unit, it
looks for the source code in a file whose name is the one that was used in the
compile step.
For COBOL and PL/I only

For COBOL and PL/I compile units, Debug Tool requires a file containing the
compiler listing. By default, when Debug Tool encounters a new VS COBOL II or a
non-Enterprise PL/I compile unit, it looks for the listing in a file named
userid.cuname.LIST. For Enterprise PL/I, Debug Tool looks for the listing in the
data set specified in the load module. For COBOL/370™ and COBOL for MVS &
VM, Debug Tool looks for the listing in the data set specified during the compile
step. For Enterprise COBOL for z/OS and OS/390 and COBOL for OS/390 & VM,
there are two possible places Debug Tool looks for compiler listing:
v Debug Tool look for the listing in the data set specified during the compile step.
v If your program is compiled with the SEPARATE suboption of the TEST compiler
option, Debug Tool looks for the compiler listing in the separate debug file.
Related tasks
“Finding a renamed source, listing, or separate debug file” on page 117
Displaying the line at which execution halted

After displaying different source files and scrolling, you can go back to the halted
execution point by entering one of the following commands:
v SET QUALIFY RESET
v Q LOC
v LIST %LINE

Recording your debug session in a log file
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 and C++ or PL/I programs):
v All command output
v Commands from USE files
v Commands specified on a __ctest() function call
v Commands specified on a CALL CEETEST statement
v Commands specified on a CALL PLITEST statement
v Commands specified in the run-time TEST command string suboption
v QUIT commands
v Debug Tool messages about the program execution (intercepted console
messages, exceptions, etc.)
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.
Related tasks
“Creating the log file”
“Recording how many times each source line runs” on page 108
Creating the log file

To create a permanent log of your debug session, first create a file with the
following specifications:
v A logical record length between 32 and 256. If the log file has a logical record
length outside the limits, Debug Tool issues a message and does not use the file.
v The record format and block size have no restrictions.
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 LRECL less than or 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.
Note: A sequential file is recommended for a session log since Debug Tool writes
to the log file.
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.
Recording how many times each source line runs

To record of how many times each line of your code was executed:
1. Allocate the INSPLOG file if you want to keep a permanent record of the
results.
2. Issue the command:
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.
Related tasks
“Creating the log file” on page 107
Recording the breakpoints encountered

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.

Setting breakpoints to halt your program at a line
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.
Related tasks
“Halting on a line in C only if a condition is true” on page 145
“Halting on a line in C++ only if a condition is true” on page 156
“Halting on a COBOL line only if a condition is true” on page 126
“Halting on a PL/I line only if a condition is true” on page 137
Stepping through or running your program

By default, when Debug Tool starts, none of your program has run yet (including
C++ constructors and static object initialization).
To run your program up to the next hook, press PF2 (STEP). If you compiled with
TEST for C or C++, TEST(ALL,SYM) for COBOL or PL/I, or TEST(NONE,SYM) for
Enterprise COBOL for z/OS and OS/390 or COBOL for OS/390 & VM with
Dynamic Debug installed, STEP performs one statement.
To run your program until a breakpoint is reached, the program ends, or a

condition is raised, press PF9 (GO).
Note: A condition being raised is determined by the setting of the TEST run-time
suboption test_level.
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).
Related tasks
Recording and replaying statements

The commands described in this section are available only if you purchase and
install IBM Debug Tool Utilities and Advanced Functions, Version 4 Release 1
(5655-L23).
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:
1. Record the statements that you run (PLAYBACK ENABLE command). If you specify
the DATA parameter or the DATA parameter is defaulted, additional information
about your program is recorded.
2. Prepare to replay statements (PLAYBACK START command).
3. Replay the statements that you recorded (STEP or RUNTO command).
4. Change the direction that the statements are replayed (PLAYBACK FORWARD
command).
5. Stop replaying statements (PLAYBACK STOP command).

6. Stop recording the statements that you run (PLAYBACK DISABLE command). All
data for the compile units specified or implied on the PLAYBACK DISABLE
command is discarded.
Each of these steps are described in more detail in the sections that follow.
Recording the statements that you run

The PLAYBACK ENABLE command includes a set of parameters to specify:
v Which compile units to record
v The maximum amount of storage to use to record the statements that you run
v Whether to record the following additional information about your program:
– The value of variables.
– The value of registers.
– Information about the files you use: open, close, last operation performed on
the files, how the files were opened.
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:
v The amount of storage specified or defaulted.
v The number of changes made to the variables.
v The number of changes made to files.
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
and are running with the following Language Environment run time and APARs
installed:
v Compilers:
– Enterprise COBOL for z/OS and OS/390, Version 3 Release 2
– Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR
PQ63235
– COBOL for OS/390 & VM, Version 2 with APAR PQ63234
v Language Environment APARs:
– z/OS Version 1 Release 4, with APAR PQ65176
– z/OS, Version 1 Release 3, with APAR PQ65175
– z/OS, Version 1 Release 2, with APAR PQ65174 and APAR PQ52626
– z/OS, Version 1 Release 1, with APAR PQ62947 and APAR PQ52626
– OS/390, Version 2 Release 10, with APAR PQ62947 and APAR PQ52626

Related tasks
“Stop the recording”
Preparing to replay the statements that you recorded

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 for z/OS Reference and Messages provides a complete list of which
commands you cannot use while you replay statements.
The initial direction is backward.
Replaying the statements that you recorded

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:
v If you are replaying in the backward direction, you reach the point where you
entered the PLAYBACK ENABLEcommand. If you are replaying in the forward
direction, you reach the point where you entered the PLAYBACK START command.
command.
v You reach the point where there are no more statements to replay, because you
have run out of storage.
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.
Changing the direction that statements are replayed

To change the direction that statements are replayed, enter the PLAYBACK FOWARD or
PLAYBACK BACKWARD command. The initial direction is backward.
Stop the replaying

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.
Stop the recording

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.
Related references
Restrictions on recording and replaying statements

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 for z/OS Reference and Messages contains a complete list of all the commands
that are not available.

Restrictions on accessing COBOL data
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:
v FILE SECTION
v WORKING-STORAGE SECTION
v LOCAL-STORAGE SECTION
v LINKAGE SECTION
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:
v The DATA parameter must be specified or defaulted for the compile unit.
v The compile unit must be compiled with a compiler that supports the DATA
parameter.
You can use the QUERY PLAYBACK command to determine the compile units for
which the DATA option is in effect.
Debug Tool for z/OS Reference and Messages contains a complete list of all the
commands that can be used when you specify the DATA parameter.
Displaying and monitoring the value of a variable

Debug Tool can display the value of variables in the following ways:
v One-time display, by using the LIST command or the PF4 key. One-time display
displays the value of the variable at the moment you enter the LIST command or
press the PF4 key. If you step or run through your program, any changes to the
value of the variable are not displayed.
v Continuous display, called monitoring, by using the MONITOR LIST command or
the SET AUTOMONITOR command. If you step or run through your program, any
changes to the value of the variable are displayed.
If Debug Tool cannot display the value of a variable in its declared data type,
Debug Tool displays the value of the variable in hexadecimal format. To change
the value of the variable, type in the new value in hexadecimal format.
One-time display of the value of variables

To display the contents of a variable once by using the PF4 key, do the following
steps:
1. Scroll through the Source window until you find the variable you want to
display.
2. Move your cursor to the variable name.
3. Press the PF4 (LIST) key. The value of the variable is displayed in the Log
window.
To display the contents of a variable once by using the LIST command, do the
following step:
1. Move the cursor to the command line.

2. Type the following command, substituting your variable name for variable-name:
LIST variable-name;
3. Press Enter. The value of the variable is displayed in the Log window.
Monitoring the value of variables

To monitor the value of a variable by using the MONITOR LIST command, do the
following steps:
2. Type the following command, substituting your variable name for variable-name:
MONITOR LIST variable-name;
3. Press Enter. The variable variable-name is added to the Monitor window and the
current value of variable-name is displayed. As you step through your program,
the value of variable-name is updated in the Monitor window so that the
window always displays the current value of variable-name.
To monitor the value of a variable by using the SET AUTOMONITOR ON command, do
the following steps:
2. Enter the following command:
SET AUTOMONITOR ON;
Debug Tool opens a separate section of the Monitor window, called the
automonitor section, and displays the name and value of variables in the next
statement that you run. Each time you enter the STEP command or a breakpoint
is encountered, Debug Tool does the following:
a. Removes the previous names and values.
b. Displays the names and values of the variables of the statement that Debug
Tool runs next. The values displayed are values before the statement is run.
To save the following information in the log file, enter the SET AUTOMONITOR ON LOG
command:
v Breakpoint locations
v The names and values of the variables at the breakpoints
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.
Variables that are monitored through the MONITOR LIST command are displayed
above the automonitor section of the Monitor window.
To close the automonitor section of the Monitor window and stop adding the name
and value of variables in the statements your run, enter the SET AUTOMONITOR OFF
command.
The SET AUTOMONITOR command is available only if you purchase and install IBM
Debug Tool Utilities and Advanced Functions, Version 4 Release 1 (5655-L23).

Example: SET AUTOMONITOR ON command
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.
Displaying values in hexadecimal format

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 VisualAge PL/I for OS/390 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:
v For PL/I programs: LIST HEX(variable-name) ;
v For all other programs: LIST %HEX(variable-name) ;
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:
1. If the variable is not displayed in the Source window, scroll through your
program until the variable you want is displayed in the Source window.
2. Move your cursor to the variable name.
3. Press the PF key to which you defined LIST %HEX command. Debug Tool
displays the value of the variable variable-name in hexadecimal format.
You cannot define a PF key with the PL/I HEX built-in function.
Monitoring the value of variables in hexadecimal format

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 it’s declared data
type, follow the instructions described in “Monitoring the value of variables” on
page 113. For PL/I programs, use the PL/I HEX built-in function to monitor the
value of a variable in hexadecimal format. If you monitor 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 monitor the value of a variable or expression in hexadecimal format, do one of

the following instructions:
v If the variable is already being monitored, enter the following command:
MONITOR n HEX ;
Substitute n with the number in the monitor list the corresponds to the
monitored expression that you would like to display in hex.
v If the variable is not being monitored, enter the following command:
MONITOR LIST (expression) HEX ;
Substitute expression with the name of the variable or a complex expression you
want to monitor.
Modifying variables
There are two methods to modify variables:
v By using a command, such as MOVE or an assignment command. Each command
is described in Debug Tool for z/OS Reference and Messages.
v By typing over the existing value that is displayed in the Monitor window.
To modify the value of a variable by typing over the existing value in the Monitor
window, do the following steps:
1. Move the cursor to the existing value.
2. Type in the new value. Black vertical bars mark the area where you can type in
your new value; you cannot type anything before and including the left vertical
bar nor can you type anything including and after the right vertical bar.
3. Press Enter. Debug Tool creates a command in the command line that will do
the modification.
4. Verify that the command that Debug Tool created is correct. Press Enter.
Restrictions for modifying variables in the Monitor window

You cannot remove variables in the automonitor section of the Monitor window by
using the CLEAR command.
You can modify the value of a variable by typing over the existing value in the
Monitor window, with the following exceptions:
v Only one value at a time can be modified. If you type over the values of more
than one variable, only the first one is modified.
v You cannot type in a value that is larger than the declared type of the variable.
For example, if you declare a variable as a string of four character and you try
to type in five characters, Debug Tool prevents you from typing in the fifth
character.
v If Debug Tool cannot display the entire value in the Monitor window, you
cannot modify the value of that variable. If the variable is a structure and you
want to modify an element of that structure, the element must not have an
ambiguous name. An ambiguous name is a reference to an element that might
have more than one definition. For example, if you have two structures in a C
program and each structure has an element defined as street_address char[15],
the Monitor window must display the beginning of the structure so that Debug
Tool can determine to which structure a specific element belongs to.
v If you enter quotes, carefully verify the command that Debug Tool creates to
ensure that the command complies with any applicable quotation rules.

Opening and closing the Monitor window
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.
Related tasks
“Displaying values of C and C++ variables or expressions” on page 208
“Accessing PL/I program variables” on page 202
“Displaying and modifying the value of assembler variables or storage” on page 168
Managing file allocations

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. These commands are available only if you purchase and install IBM
Debug Tool Utilities and Advanced Functions, Version 4 Release 1 (5655-L23).
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:

1 VOLUME
The volume serial of the DASD volume that contains the data set.
2 CAT
An asterisk in this column indicates that the data set was located by using
the system catalog.
3 DISP
The disposition that is assigned to the data set.

4 OPEN
An asterisk in this column indicates that the file is currently open.
5 DDNAME
DD name for the file.
6 DSNAME
Data set name for a DASD data set:
v DUMMY for a DD DUMMY
v SYSOUT(x) for a SYSOUT data set
v TERMINAL for a file allocated to the terminal
v * for a DD * file
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 for z/OS Reference and Messages describes the
parameters you must specify to list this information.
Displaying error numbers for messages in the Log window

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.
Related tasks
Finding a renamed source, listing, or separate debug file

If the source, listing, or separate debug file has been renamed since your program
was compiled, Debug Tool will not be able to find it, and it will not appear in the
Source window when you debug your program.
To point Debug Tool to the renamed file:

v Use the Source Identification panel to direct Debug Tool to the new files:
1. With the cursor on the command line, press PF4 (LIST).
In the Source Identification panel, you can associate the source, listings, or
separate debug files that show in the Source window with their compile
units.
2. Type over the Listing/Source File field with the new name.
v Use the SET SOURCE or SET DEFAULT LISTINGS commands to direct Debug Tool to
the new files:
1. With the cursor on the command line, type SET SOURCE ON (cuname)
new_file_name, where new_file_name is the renamed source file. Press Enter.

2. With the cursor on the command line, type SET DEFAULT LISTINGS
new_file_name, where new_file_name is the renamed listing or separate debug
file. Press Enter.
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) ;
If you need to do this repeatedly, note 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.
Related tasks
“Changing which source file appears in the Source window” on page 105
Requesting an attention interrupt during interactive sessions

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.
For CICS and full-screen mode through a VTAM terminal only: An attention
interrupt key is not supported in CICS or full-screen mode through a VTAM
terminal.
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 Dynamic Debug only: The Dynamic Debug feature does not support attention
interrupts for programs that have been compiled with the TEST(NONE,SYM) compiler
option, assembler programs, and disassembly programs.
The correct key might not be marked ATTN on every keyboard. Often the
following keys are used:
v Under TSO: PA1 key
v Under IMS: PA1 key
When you request an attention interrupt, control is given to Debug Tool:

v At the next hook if Debug Tool has previously gained control or if you specified
either TEST(ERROR) or TEST(ALL) or have specifically set breakpoints
v At a __ctest() or CEETEST call

v When an HLL condition is raised in the program, such as SIGINT in C
Related references
Ending a full-screen debug session

When you have finished debugging your program, you can end your full-screen
debug session by using one of the following methods:
Method A
1. Press PF3 (QUIT) or enter QUIT on the command line.
2. Type Y to confirm your request and press Enter. Your program stops
running.
Method B
1. Enter the QQUIT command. You are not prompted to confirm your
request to end your debug session. Your program stops running.
Method C
1. Enter the QUIT DEBUG command.
2. Type Y to confirm your request and press Enter. Your program
continues to run.
As the program runs, it cannot restart Debug Tool. To restart Debug
Tool you must stop running the program and restart your full-screen
debug session.
Related references

Chapter 21. Debugging a COBOL program in full-screen mode
The descriptions of basic debugging tasks for COBOL refer to the following
COBOL program.
“Example: sample COBOL program for debugging”
Related tasks
Chapter 28, “Debugging COBOL programs,” on page 187
“Halting when certain routines are called in COBOL” on page 124
“Modifying the value of a COBOL variable” on page 125
“Halting on a COBOL line only if a condition is true” on page 126
“Debugging COBOL when only a few parts are compiled with TEST” on page 127
“Capturing COBOL I/O to the system console” on page 127
“Displaying raw storage in COBOL” on page 128
“Getting a COBOL routine traceback” on page 128
“Tracing the run-time path for COBOL code compiled with TEST” on page 128
“Generating a COBOL run-time paragraph trace” on page 129
“Finding unexpected storage overwrite errors in COBOL” on page 130
“Halting before calling an invalid program in COBOL” on page 130
Related references
“Format for a COBOL source listing and debug file” on page 187
Example: sample COBOL program for debugging

The program below is used in various topics to demonstrate debugging tasks.
This program calls two subprograms to calculate a loan payment amount and the
future value of a series of cash flows. Several COBOL intrinsic functions are
utilized.
Main program COBCALC

**********************************************************
* COBCALC *
* *
* A simple program that allows financial functions to *
* be performed using intrinsic functions. *
* *
**********************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. COBCALC.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 PARM-1.
05 CALL-FEEDBACK PIC XX.
01 FIELDS.
05 INPUT-1 PIC X(10).
01 INPUT-BUFFER-FIELDS.
05 BUFFER-PTR PIC 9.
05 BUFFER-DATA.
10 FILLER PIC X(10) VALUE "LOAN".
10 FILLER PIC X(10) VALUE "PVALUE".
10 FILLER PIC X(10) VALUE "pvalue".
10 FILLER PIC X(10) VALUE "END".

05 BUFFER-ARRAY REDEFINES BUFFER-DATA
OCCURS 4 TIMES
PIC X(10).
PROCEDURE DIVISION.
DISPLAY "CALC Begins." UPON CONSOLE.
MOVE 1 TO BUFFER-PTR.
MOVE SPACES TO INPUT-1.
* Keep processing data until END requested
PERFORM ACCEPT-INPUT UNTIL INPUT-1 EQUAL TO "END".
* END requested
DISPLAY "CALC Ends." UPON CONSOLE.
GOBACK.
* End of program.
*
* Accept input data from buffer
*
ACCEPT-INPUT.
MOVE BUFFER-ARRAY (BUFFER-PTR) TO INPUT-1.
ADD 1 BUFFER-PTR GIVING BUFFER-PTR.
* Allow input data to be in UPPER or lower case
EVALUATE FUNCTION UPPER-CASE(INPUT-1) CALC1
WHEN "END"
MOVE "END" TO INPUT-1
WHEN "LOAN"
PERFORM CALCULATE-LOAN
WHEN "PVALUE"
PERFORM CALCULATE-VALUE
WHEN OTHER
DISPLAY "Invalid input: " INPUT-1
END-EVALUATE.
*
* Calculate Loan via CALL to subprogram
*
CALCULATE-LOAN.
CALL "COBLOAN" USING CALL-FEEDBACK.
IF CALL-FEEDBACK IS NOT EQUAL "OK" THEN
DISPLAY "Call to COBLOAN Unsuccessful.".
*
* Calculate Present Value via CALL to subprogram
*
CALCULATE-VALUE.
CALL "COBVALU" USING CALL-FEEDBACK.
IF CALL-FEEDBACK IS NOT EQUAL "OK" THEN
DISPLAY "Call to COBVALU Unsuccessful.".
Subroutine COBLOAN
**********************************************************
* COBLOAN *
* *
* A simple subprogram that calculates payment amount *
* for a loan. *
* *
**********************************************************
PROGRAM-ID. COBLOAN.
DATA DIVISION.
01 FIELDS.
05 PAYMENT PIC S9(9)V99 USAGE COMP.
05 PAYMENT-OUT PIC $$$$,$$$,$$9.99 USAGE DISPLAY.
05 LOAN-AMOUNT PIC S9(7)V99 USAGE COMP.
05 LOAN-AMOUNT-IN PIC X(16).

05 INTEREST-IN PIC X(5).
05 INTEREST PIC S9(3)V99 USAGE COMP.
05 NO-OF-PERIODS-IN PIC X(3).
05 NO-OF-PERIODS PIC 99 USAGE COMP.
05 OUTPUT-LINE PIC X(79).
LINKAGE SECTION.
01 PARM-1.
PROCEDURE DIVISION USING PARM-1.
MOVE "NO" TO CALL-FEEDBACK.
MOVE "30000 .09 24 " TO INPUT-1.
UNSTRING INPUT-1 DELIMITED BY ALL " "
INTO LOAN-AMOUNT-IN INTEREST-IN NO-OF-PERIODS-IN.
* Convert to numeric values
COMPUTE LOAN-AMOUNT = FUNCTION NUMVAL(LOAN-AMOUNT-IN).
COMPUTE INTEREST = FUNCTION NUMVAL(INTEREST-IN).
COMPUTE NO-OF-PERIODS = FUNCTION NUMVAL(NO-OF-PERIODS-IN).
* Calculate annuity amount required
COMPUTE PAYMENT = LOAN-AMOUNT *
FUNCTION ANNUITY((INTEREST / 12 ) NO-OF-PERIODS).
* Make it presentable
MOVE SPACES TO OUTPUT-LINE
MOVE PAYMENT TO PAYMENT-OUT.
STRING "COBLOAN:_Repayment_amount_for_a_" NO-OF-PERIODS-IN
"_month_loan_of_" LOAN-AMOUNT-IN
"_at_" INTEREST-IN "_interest_is:_"
DELIMITED BY SPACES
INTO OUTPUT-LINE.
INSPECT OUTPUT-LINE REPLACING ALL "_" BY SPACES.
DISPLAY OUTPUT-LINE PAYMENT-OUT.
MOVE "OK" TO CALL-FEEDBACK.
GOBACK.
Subroutine COBVALU
**********************************************************
* COBVALU *
* *
* A simple subprogram that calculates present value *
* for a series of cash flows. *
* *
**********************************************************
PROGRAM-ID. COBVALU.
DATA DIVISION.
01 CHAR-DATA.
05 PAYMENT-OUT PIC $$$$,$$$,$$9.99 USAGE DISPLAY.
05 INTEREST-IN PIC X(5).
05 NO-OF-PERIODS-IN PIC X(3).
05 INPUT-BUFFER PIC X(10) VALUE "5069837544".
05 BUFFER-ARRAY REDEFINES INPUT-BUFFER
OCCURS 5 TIMES
PIC XX.
05 OUTPUT-LINE PIC X(79).
01 NUM-DATA.
05 PAYMENT PIC S9(9)V99 USAGE COMP.
05 INTEREST PIC S9(3)V99 USAGE COMP.
05 COUNTER PIC 99 USAGE COMP.
05 NO-OF-PERIODS PIC 99 USAGE COMP.
05 VALUE-AMOUNT OCCURS 99 PIC S9(7)V99 COMP.
LINKAGE SECTION.
01 PARM-1.
PROCEDURE DIVISION USING PARM-1.
Chapter 21. Debugging a COBOL program in full-screen mode 123

MOVE "NO" TO CALL-FEEDBACK.
MOVE ".12 5 " TO INPUT-1.
UNSTRING INPUT-1 DELIMITED BY "," OR ALL " " VALU1
INTO INTEREST-IN NO-OF-PERIODS-IN.
* Convert to numeric values
COMPUTE INTEREST = FUNCTION NUMVAL(INTEREST-IN). VALU2
COMPUTE NO-OF-PERIODS = FUNCTION NUMVAL(NO-OF-PERIODS-IN).
* Get cash flows
PERFORM GET-AMOUNTS VARYING COUNTER FROM 1 BY 1 UNTIL
COUNTER IS GREATER THAN NO-OF-PERIODS.
* Calculate present value
COMPUTE PAYMENT =
FUNCTION PRESENT-VALUE(INTEREST VALUE-AMOUNT(ALL) ). VALU3
* Make it presentable
MOVE PAYMENT TO PAYMENT-OUT.
STRING "COBVALU:_Present_value_for_rate_of_"
INTEREST-IN "_given_amounts_"
BUFFER-ARRAY (1) ",_"
BUFFER-ARRAY (5) "_is:_"
DELIMITED BY SPACES
INTO OUTPUT-LINE.
INSPECT OUTPUT-LINE REPLACING ALL "_" BY SPACES.
DISPLAY OUTPUT-LINE PAYMENT-OUT.
MOVE "OK" TO CALL-FEEDBACK.
GOBACK.
*
* Get cash flows for each period
*
GET-AMOUNTS.
MOVE BUFFER-ARRAY (COUNTER) TO INPUT-1.
COMPUTE VALUE-AMOUNT (COUNTER) = FUNCTION NUMVAL(INPUT-1).
Related tasks
Halting when certain routines are called in COBOL

“Example: sample COBOL program for debugging” on page 121
To halt just before COBLOAN is called, issue the command:

AT CALL COBLOAN ;
If the CU COBVALU is known to Debug Tool (that is, it has been called
previously), to halt just after COBVALU is called, issue the command:
AT ENTRY COBVALU ;
If the CU COBVALU is not known to Debug Tool (that is, it has not been called
previously), to halt just before COBVALU is entered the first time, issue the
command:
AT APPEARANCE COBVALU ;
You can display a list of all compile units that are known to Debug Tool by
entering the command:
LIST NAMES CUS ;
The Debug Tool Log window displays something similar to:

LIST NAMES CUS ;
The following CUs are known in *:
COBCALC
COBLOAN
COBVALU
Additionally, you can combine the breakpoints as follows:

AT APPEARANCE COBVALU AT ENTRY COBVALU ; GO ;
The purpose for the appearance breakpoint is to gain control the first time the
COBVALU compile unit is run.
To take advantage of either AT ENTRY or AT APPEARANCE, you must compile the

routine program (COBVALU in the above example) with the TEST compiler option.
If you have many breakpoints set in your program, you can issue the command:
QUERY LOCATION
to indicate where in your program execution has been interrupted. The Debug Tool
Log window displays something similar to:
QUERY LOCATION ;
You were prompted because STEP ended.
The program is currently entering block COBVALU.
Modifying the value of a COBOL variable

To list the contents of a single variable, move the cursor to an occurrence of the
variable name in the Source window and press PF4 (LIST). Remember that Debug
Tool starts after program initialization but before symbolic COBOL variables are
initialized, so you cannot view or modify the contents of variables until you have
performed a step or run. The value is displayed in the Log window. This is
equivalent to entering LIST TITLED variable on the command line. Run the
COBCALC program to the statement labeled CALC1, and enter AT 46 ; GO ; on
the Debug Tool command line. Move the cursor over INPUT-1 and press LIST (PF4).
The following appears in the Log window:
LIST ( INPUT-1 ) ;
INPUT-1 = ’LOAN ’
To modify the value of INPUT-1, enter on the command line:

MOVE ’pvalue’ to INPUT-1 ;
You can enter most COBOL expressions on the command line.
Now step into the call to COBVALU by pressing PF2 (STEP) and step until the
statement labeled VALU2 is reached. To view the attributes of the variable
INTEREST, issue the Debug Tool command:
DESCRIBE ATTRIBUTES INTEREST ;
The result in the Log window is:

ATTRIBUTES FOR INTEREST
ITS LENGTH IS 4
ITS ADDRESS IS 00011DC8
02 COBVALU:>INTEREST S999V99 COMP

You can use this action as a simple browser for group items and data hierarchies.
For example, you can list all the values of the elementary items for the
CHAR-DATA group with the command:
LIST CHAR-DATA ;
with results in the Log window appearing something like this:

LIST CHAR-DATA ;
02 COBVALU:>INPUT-1 of 01 COBVALU:>CHAR-DATA = ’.12 5 ’
Invalid data for 02 COBVALU:>PAYMENT-OUT of 01 COBVALU:>CHAR-DATA is found.
02 COBVALU:>INTEREST-IN of 01 COBVALU:>CHAR-DATA = ’.12 ’
02 COBVALU:>NO-OF-PERIODS-IN of 01 COBVALU:>CHAR-DATA = ’5 ’
02 COBVALU:>INPUT-BUFFER of 01 COBVALU:>CHAR-DATA = ’5069837544’
SUB(1) of 02 COBVALU:>BUFFER-ARRAY of 01 COBVALU:>CHAR-DATA = ’50’
Note: If you use the LIST command to list the contents of an uninitialized variable,
or a variable that contains invalid data, Debug Tool displays INVALID DATA.
Related tasks
“Using COBOL variables with Debug Tool” on page 189
Halting on a COBOL line only if a condition is true

Often a particular part of your program works fine for the first few thousand
times, but it fails under certain conditions. You don’t want to just set a line
breakpoint because you will have to keep entering GO.
For example, in COBVALU you want to stop at the calculation of present value
only if the discount rate is less than or equal to -1 (before the exception occurs).
First run COBCALC, step into COBVALU, and stop at the statement labeled
VALU1. To accomplish this, issue these Debug Tool commands at the start of
COBCALC:
AT 67 ; GO ;
CLEAR AT 67 ; STEP 4 ;
Now set the breakpoint like this:

AT 44 IF INTEREST > -1 THEN GO ; END-IF ;
Line 44 is the statement labeled VALU3. The command causes Debug Tool to stop
at line 44. If the value of INTEREST is greater than -1, the program continues. The
command causes Debug Tool to remain on line 44 only if the value of INTEREST is
less than or equal to -1.
To force the discount rate to be negative, enter the Debug Tool command:
MOVE ’-2 5’ TO INPUT-1 ;
Run the program by issuing the GO command. Debug Tool halts the program at
line 44. Display the contents of INTEREST by issuing the LIST INTEREST command.
To view the effect of this breakpoint when the discount rate is positive, begin a
new debug session and repeat the Debug Tool commands shown in this section.
However, do not issue the MOVE ’-2 5’ TO INPUT-1 command. The program
execution does not stop at line 44 and the program runs to completion.

Debugging COBOL when only a few parts are compiled with TEST
Suppose you want to set a breakpoint at entry to COBVALU. COBVALU has been
compiled with TEST but the other programs have not. Debug Tool comes up with
an empty Source window. You can use the LIST NAMES CUS command to determine
if the COBVALU compile unit is known to Debug Tool and then set the
appropriate breakpoint using either the AT APPEARANCE or the AT ENTRY command.
Instead of setting a breakpoint at entry to COBVALU in this example, issue a STEP

command when Debug Tool initially displays the empty Source window. Debug
Tool runs the program until it reaches the entry for the first routine compiled with
TEST, COBVALU in this case.
Related tasks
“Halting when certain routines are called in COBOL” on page 124
Capturing COBOL I/O to the system console

To redirect output normally appearing on the system console to your Debug Tool
terminal, enter the following command:
SET INTERCEPT ON CONSOLE ;
For example, if you run COBCALC and issue the Debug Tool SET INTERCEPT ON
CONSOLE command, followed by the STEP 3 command, you will see the following
output displayed in the Debug Tool Log window:
SET INTERCEPT ON CONSOLE ;
STEP 3 ;
CONSOLE : CALC Begins.
The phrase CALC Begins. is displayed by the statement DISPLAY "CALC Begins."
UPON CONSOLE in COBCALC.
The SET INTERCEPT ON CONSOLE command not only captures output to the system
console, but also allows you to input data from your Debug Tool terminal instead
of the system console by using the Debug Tool INPUT command. For example, if
the next COBOL statement executed is ACCEPT INPUT-DATA FROM CONSOLE, the
following message appears in the Debug Tool Log window:
CONSOLE : IGZ0000I AWAITING REPLY.
The program is waiting for input from CONSOLE.
Use the INPUT command to enter 114 characters for the intercepted
fixed-format file.
Continue execution by replying to the input request by entering the following

Debug Tool command:
INPUT some data ;
Note: Whenever Debug Tool intercepts system console I/O, and for the duration
of the intercept, the display in the Source window is empty and the Location
field in the session panel header at the top of the screen shows Unknown.

Displaying raw storage in COBOL
You can display the storage for a variable by using the LIST STORAGE command.
For example, to display the storage for the first 12 characters of BUFFER-DATA
enter:
LIST STORAGE(BUFFER-DATA,12)
Getting a COBOL routine traceback

Often when you get close to a programming error, you want to know how you got
into that situation, and especially what the traceback of calling routines is. To get
this information, issue the command:
LIST CALLS ;
For example, if you run the COBCALC example with the commands:
AT APPEARANCE COBVALU AT ENTRY COBVALU;
GO;
GO;
LIST CALLS;
the Log window contains something like:

AT APPEARANCE COBVALU
AT ENTRY COBVALU ;
GO ;
GO ;
LIST CALLS ;
At ENTRY in COBOL program COBVALU.
From LINE 67.1 in COBOL program COBCALC.
which shows the traceback of callers.
Tracing the run-time path for COBOL code compiled with TEST
To trace a program showing the entry and exit points without requiring any
changes to the program, place the following Debug Tool commands in a file or
data set and USE them when Debug Tool initially displays your program.
Assuming you have a PDS member, USERID.DT.COMMANDS(COBCALC), that
contains the following Debug Tool commands:
* Commands in a COBOL USE file must be coded in columns 8-72.
* If necessary, commands can be continued by coding a ’-’ in
* column 7 of the continuation line.
01 LEVEL PIC 99 USAGE COMP;
MOVE 1 TO LEVEL;
AT ENTRY * PERFORM;
COMPUTE LEVEL = LEVEL + 1;
LIST ( "Entry:", LEVEL, %CU);
GO;
END-PERFORM;
AT EXIT * PERFORM;
LIST ( "Exit:", LEVEL);
COMPUTE LEVEL = LEVEL - 1;
GO;
END-PERFORM;
You can use this file as the source of commands to Debug Tool by entering the
following command:
USE USERID.DT.COMMANDS(COBCALC)

If, after executing the USE file, you run COBCALC, the following trace (or similar)
is displayed in the Log window:
ENTRY:
LEVEL = 00002
%CU = COBCALC
ENTRY:
LEVEL = 00003
%CU = COBLOAN
EXIT:
LEVEL = 00003
ENTRY:
LEVEL = 00003
%CU = COBVALU
EXIT:
LEVEL = 00003
ENTRY:
LEVEL = 00003
%CU = COBVALU
EXIT:
LEVEL = 00003
EXIT:
LEVEL = 00002
If you do not want to create the USE file, you can enter the commands through the
command line, and the same effect is achieved.
Generating a COBOL run-time paragraph trace

To generate a trace showing the names of paragraphs through which execution has
passed, the Debug Tool commands shown in the following example can be used.
You can either enter the commands from the Debug Tool command line or place
the commands in a file or data set.
Assume you have a PDS member, USERID.DT.COMMANDS(COBCALC2), that

contains the following Debug Tool commands.
* COMMANDS IN A COBOL USE FILE MUST BE CODED IN COLUMNS 8-72.
* IF NECESSARY, COMMANDS CAN BE CONTINUED BY CODING A ’-’ IN
* COLUMN 7 OF THE CONTINUATION LINE.
AT GLOBAL LABEL PERFORM;
LIST LINES %LINE;
GO;
END-PERFORM;
When Debug Tool initially displays your program, enter the following command:
USE USERID.DT.COMMANDS(COBCALC2)
After executing the USE file, you can run COBCALC and the following trace (or
similar) is displayed in the Log window:

42 ACCEPT-INPUT.
59 CALCULATE-LOAN.
42 ACCEPT-INPUT.
66 CALCULATE-VALUE.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
42 ACCEPT-INPUT.
66 CALCULATE-VALUE.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
64 GET-AMOUNTS.
42 ACCEPT-INPUT.
Finding unexpected storage overwrite errors in COBOL

During program run time, some storage might unexpectedly change its value and
you want to find out when and where this happened. Consider this example
where the program changes more than the caller expects it to change.
05 FIELD-1 OCCURS 2 TIMES
PIC X(8).
05 FIELD-2 PIC X(8).
PROCEDURE DIVISION.
* ( An invalid index value is set )
MOVE 3 TO PTR.
MOVE "TOO MUCH" TO FIELD-1( PTR ).
Find the address of FIELD-2 with the command:

DESCRIBE ATTRIBUTES FIELD-2
Suppose the result is X'0000F559'. To set a breakpoint that watches for a change in
storage values starting at that address for the next 8 bytes, issue the command:
AT CHANGE %STORAGE(H’0000F559’,8)
When the program runs, Debug Tool halts if the value in this storage changes.
Halting before calling an invalid program in COBOL

Calling an undefined program is a severe error. If you have developed a main
program that calls a subprogram that doesn’t exist, you can cause Debug Tool to
halt just before such a call. For example, if the subprogram NOTYET doesn’t exist,
you can set the breakpoint:

AT CALL (NOTYET)
When Debug Tool stops at this breakpoint, you can bypass the CALL by entering
the GO BYPASS command. This allows you to continue your debug session without
raising a condition.

Chapter 22. Debugging a PL/I program in full-screen mode
The descriptions of basic debugging tasks for PL/I refer to the following PL/I
program.
“Example: sample PL/I program for debugging”
Related tasks
Chapter 29, “Debugging PL/I programs,” on page 199
“Halting when certain PL/I functions are called” on page 136
“Modifying the value of a PL/I variable” on page 136
“Halting on a PL/I line only if a condition is true” on page 137
“Debugging PL/I when only a few parts are compiled with TEST” on page 137
“Displaying raw storage in PL/I” on page 138
“Getting a PL/I function traceback” on page 138
“Tracing the run-time path for PL/I code compiled with TEST” on page 138
“Finding unexpected storage overwrite errors in PL/I” on page 140
“Halting before calling an undefined program in PL/I” on page 140
Example: sample PL/I program for debugging

This program is a simple calculator that reads its input from a character buffer. If
integers are read, they are pushed on a stack. If one of the operators (+ - * /) is
read, the top two elements are popped off the stack, the operation is performed on
them and the result is pushed on the stack. The = operator writes out the value of
the top element of the stack to a buffer.
Before running PLICALC, you need to allocate SYSPRINT to the terminal by

entering the following command:
ALLOC FI(SYSPRINT) DA(*) REUSE
Main program PLICALC

plicalc: proc options(main);
/*------------------------------------------------------------------*/
/* */
/* A simple calculator that does operations on integers that */
/* are pushed and popped on a stack */
/* */
/*------------------------------------------------------------------*/
dcl index builtin;
dcl length builtin;
dcl substr builtin;
/* */
dcl 1 stack,
2 stkptr fixed bin(15,0) init(0),
2 stknum(50) fixed bin(31,0);
dcl 1 bufin,
2 bufptr fixed bin(15,0) init(0),
2 bufchr char (100) varying;
dcl 1 tok char (100) varying;
dcl 1 tstop char(1) init (’s’);
dcl 1 ndx fixed bin(15,0);
dcl num fixed bin(31,0);
dcl i fixed bin(31,0);

dcl push entry external;
dcl pop entry returns (fixed bin(31,0)) external;
dcl readtok entry returns (char (100) varying) external;
/*------------------------------------------------------------------*/
/* input action: */
/* 2 push 2 on stack */
/* 18 push 18 */
/* + pop 2, pop 18, add, push result (20) */
/* = output value on the top of the stack (20) */
/* 5 push 5 */
/* / pop 5, pop 20, divide, push result (4) */
/*------------------------------------------------------------------*/
bufchr = ’2 18 + = 5 / =’;
do while (tok ^= tstop);
tok = readtok(bufin); /* get next ’token’ */
select (tok);
when (tstop)
leave;
when (’+’) do;
num = pop(stack);
call push(stack,num); /* CALC1 statement */
end;
when (’-’) do;
num = pop(stack);
call push(stack,pop(stack)-num);
end;
when (’*’)
call push(stack,pop(stack)*pop(stack));
when (’/’) do;
num = pop(stack);
call push(stack,pop(stack)/num); /* CALC2 statement */
end;
when (’=’) do;
num = pop(stack);
put list (’PLICALC: ’, num) skip;
call push(stack,num);
end;
otherwise do;/* must be an integer */
num = atoi(tok);
call push(stack,num);
end;
end;
end;
return;
TOK function
atoi: procedure(tok) returns (fixed bin(31,0));
/*------------------------------------------------------------------*/
/* */
/* convert character string to number */
/* (note: string validated by readtok) */
/* */
/*------------------------------------------------------------------*/
dcl 1 num fixed bin (31,0);
dcl 1 j fixed bin(15,0);
num = 0;
do j = 1 to length(tok);
num = (10 * num) + (index(’0123456789’,substr(tok,j,1))-1);
end;
return (num);
end atoi;
end plicalc;
PUSH function

push: procedure(stack,num);
/*------------------------------------------------------------------*/
/* */
/* a simple push function for a stack of integers */
/* */
/*------------------------------------------------------------------*/
dcl 1 stack connected,
2 stkptr fixed bin(15,0),
dcl num fixed bin(31,0);
stkptr = stkptr + 1;
stknum(stkptr) = num; /* PUSH1 statement */
return;
end push;
POP function
pop: procedure(stack) returns (fixed bin(31,0));
/*------------------------------------------------------------------*/
/* */
/* a simple pop function for a stack of integers */
/* */
/*------------------------------------------------------------------*/
dcl 1 stack connected,
2 stkptr fixed bin(15,0),
stkptr = stkptr - 1;
return (stknum(stkptr+1));
end pop;
READTOK function
readtok: procedure(bufin) returns (char (100) varying);
/*------------------------------------------------------------------*/
/* */
/* a function to read input and tokenize it for a simple calculator */
/* */
/* action: get next input char, update index for next call */
/* return: next input char(s) */
/*------------------------------------------------------------------*/
dcl length builtin;
dcl substr builtin;
dcl verify builtin;
dcl 1 bufin connected,
2 bufptr fixed bin(15,0),
2 bufchr char (100) varying;
dcl 1 tstop char(1) init (’s’);
dcl 1 j fixed bin(15,0);
/* start of processing */
if bufptr > length(bufchr) then do;
tok = tstop;
return ( tok );
end;
bufptr = bufptr + 1;
do while (substr(bufchr,bufptr,1) = ’ ’);
bufptr = bufptr + 1;
if bufptr > length(bufchr) then do;
tok = tstop;
return ( tok );
end;
end;
tok = substr(bufchr,bufptr,1); /* get ready to return single char */
select (tok);
when (’+’,’-’,’/’,’*’,’=’)
bufptr = bufptr;
otherwise do; /* possibly an integer */
tok = ’’;
Chapter 22. Debugging a PL/I program in full-screen mode 135

do j = bufptr to length(bufchr);
if verify(substr(bufchr,j,1),’0123456789’) ^= 0 then
leave;
end;
if j > bufptr then do;
j = j - 1;
tok = substr(bufchr,bufptr,(j-bufptr+1));
bufptr = j;
end;
else
tok = tstop;
end;
end;
return (tok);
end readtok;
Related tasks
Halting when certain PL/I functions are called

“Example: sample PL/I program for debugging” on page 133
To halt just before READTOK is called, issue the command:

AT CALL READTOK ;
To halt just after READTOK is called, issue the command:

AT ENTRY READTOK ;
To take advantage of the AT ENTRY command, you must compile your program
with the TEST option.
QUERY LOCATION
QUERY LOCATION ;
You are executing commands in the ENTRY READTOK breakpoint.
The program is currently entering block READTOK.
Modifying the value of a PL/I variable

variable name in the Source window and press PF4 (LIST). The value is displayed
in the Log window. This is equivalent to entering LIST TITLED variable on the
command line. For example, run the PLICALC program to the statement labeled
CALC1 by entering AT 22 ; GO ; on the Debug Tool command line. Move the
cursor over NUM and press PF4 (LIST). The following appears in the Log window:
LIST NUM ;
NUM = 18
To modify the value of NUM to 22, type over the NUM = 18 line with NUM = 22,
press Enter to put it on the command line, and press Enter again to issue the
command.
You can enter most PL/I expressions on the command line.

Now step into the call to PUSH by pressing PF2 (STEP) and step until the statement
labeled PUSH1 is reached. To view the attributes of variable STKNUM, issue the
Debug Tool command:
DESCRIBE ATTRIBUTES STKNUM;

ATTRIBUTES FOR STKNUM
ITS ADDRESS IS 0003944C AND ITS LENGTH IS 200
PUSH : STACK.STKNUM(50) FIXED BINARY(31,0) REAL PARAMETER
ITS ADDRESS IS 0003944C AND ITS LENGTH IS 4
You can list all the values of the members of the structure pointed to by STACK with
the command:
LIST STACK;
with results in the Log window appearing something like this:

LIST STACK ;
STACK.STKPTR = 2
STACK.STKNUM(1) = 2
STACK.STKNUM(2) = 18
STACK.STKNUM(3)
. = 233864
.
.
STACK.STKNUM(50) = 121604
You can change the value of a structure member by issuing the assignment as a
command as in the following example:
STKNUM(STKPTR) = 33;
Halting on a PL/I line only if a condition is true

times, but it fails under certain conditions. You don’t want to just set a line
For example, in PLICALC you want to stop at the division selection only if the
divisor is 0 (before the exception occurs). Set the breakpoint like this:
AT 31 DO; IF NUM ^= 0 THEN GO; END;
Line 31 is the statement labeled CALC2. The command causes Debug Tool to stop
at line 31. If the value of NUM is not 0, the program continues. The command
causes Debug Tool to stop on line 31 only if the value of NUM is 0.
Debugging PL/I when only a few parts are compiled with TEST
Suppose you want to set a breakpoint at entry to subroutine PUSH. PUSH has
been compiled with TEST, but the other files have not. Debug Tool comes up with
an empty Source window. To display the compile units, enter the command:
LIST NAMES CUS
The LIST NAMES CUS command displays a list of all the compile units that are
known to Debug Tool. If PUSH is fetched later on by the application, this compile
unit might not be known to Debug Tool. If it is displayed, enter:

SET QUALIFY CU PUSH
AT ENTRY PUSH;
GO ;
If it is not displayed, set an appearance breakpoint as follows:

AT APPEARANCE PUSH ;
GO ;
You can also combine the breakpoints as follows:

AT APPEARANCE PUSH AT ENTRY PUSH; GO;
The only purpose for this appearance breakpoint is to gain control the first time a
function in the PUSH compile unit is run. When that happens, you can set a
breakpoint at entry to PUSH like this:
AT ENTRY PUSH;
Displaying raw storage in PL/I

You can display the storage for a variable by using the LIST STORAGE command.
For example, to display the storage for the first 30 characters of STACK enter:
LIST STORAGE(STACK,30)
Getting a PL/I function traceback

into that situation, and especially what the traceback of calling functions is. To get
LIST CALLS ;
For example, if you run the PLICALC example with the commands:
AT ENTRY READTOK ;
GO ;
LIST CALLS ;
the Log window will contain something like:

At ENTRY IN PL/I subroutine READTOK.
From LINE 17.1 IN PL/I subroutine PLICALC.
Tracing the run-time path for PL/I code compiled with TEST
To trace a program showing the entry and exit without requiring any changes to
the program, place the following Debug Tool commands in a file or data set and
USE them when Debug Tool initially displays your program. Assuming you have a
PDS member, USERID.DT.COMMANDS(PLICALL), that contains the following
Debug Tool commands:
SET PROGRAMMING LANGUAGE PLI ;
DCL LVLSTR CHARACTER (50);
DCL LVL FIXED BINARY (15); LVL = 0;
AT ENTRY *
DO;
LVLSTR = ’ ’ ;
LVL = LVL + 1 ;
SUBSTR ( LVLSTR, LVL, 1 ) = ’>’ ;

SUBSTR ( LVLSTR, LVL + 1, 8 ) = %BLOCK ;
LIST UNTITLED ( LVLSTR ) ;
GO ;
END; AT EXIT *
DO;
SUBSTR ( LVLSTR, LVL, 1 ) = ’<’ ;
SUBSTR ( LVLSTR, LVL + 1, 8 )= %BLOCK ;
LIST UNTITLED ( LVLSTR ) ;
LVL = LVL - 1 ;
GO ; END;
following command:
USE USERID.DT.COMMANDS(PLICALL)
If, after executing the USE file, you run the following program sequence:
*PROCESS MACRO,OPT(TIME);
*PROCESS S STMT TEST(ALL);
PLICALL: PROC OPTIONS (MAIN);
DCL PLIXOPT CHAR(60) VAR STATIC EXTERNAL
INIT(’STACK(20K,20K),TEST’);
CALL PLISUB;
PUT SKIP LIST(’DONE WITH PLICALL’);
PLISUB: PROC;
DCL PLISUB1 ENTRY ;
CALL PLISUB1;
PUT SKIP LIST(’DONE WITH PLISUB ’);
END PLISUB;
PLISUB1: PROC;
DCL PLISUB2 ENTRY ;
CALL PLISUB2;
PUT SKIP LIST(’DONE WITH PLISUB1’);
END PLISUB1;
PLISUB2: PROC;
PUT SKIP LIST(’DONE WITH PLISUB2’);

END PLISUB2;
END PLICALL;
the following trace (or similar) is displayed in the Log window:

’>PLICALL
’ >PLISUB
’ >PLISUB1
’ >PLISUB2
’ >PLISUB3
’ >PLISUB3<

Finding unexpected storage overwrite errors in PL/I

you want to find out when and where this happened. Consider the following
example where the program changes more than the caller expects it to change.
2 FIELD1(2) CHAR(8);
2 FIELD2 CHAR(8);
CTR = 3; /* an invalid index value is set */
FIELD1(CTR) = ’TOO MUCH’;
Find the address of FIELD2 with the command:

DESCRIBE ATTRIBUTES FIELD2
Suppose the result is X'00521D42'. To set a breakpoint that watches for a change in
AT CHANGE %STORAGE(’00521D42’px,8)
When the program is run, Debug Tool halts if the value in this storage changes.
Halting before calling an undefined program in PL/I

Calling an undefined program or function is a severe error. To halt just before such
a call is run, set this breakpoint:
AT CALL 0

Chapter 23. Debugging a C program in full-screen mode
The descriptions of basic debugging tasks for C refer to the following C program.
“Example: sample C program for debugging”
Related tasks
Chapter 30, “Debugging C and C++ programs,” on page 207
“Halting when certain functions are called in C” on page 144
“Modifying the value of a C variable” on page 144
“Halting on a line in C only if a condition is true” on page 145
“Debugging C when only a few parts are compiled with TEST” on page 145
“Capturing C output to stdout” on page 146
“Calling a C function from Debug Tool” on page 146
“Displaying raw storage in C” on page 147
“Debugging a C DLL” on page 147
“Getting a function traceback in C” on page 147
“Tracing the run-time path for C code compiled with TEST” on page 148
“Finding unexpected storage overwrite errors in C” on page 148
“Finding uninitialized storage errors in C” on page 149
“Halting before calling a NULL C function” on page 150
Example: sample C program for debugging

integers are read, they are pushed on a stack. If one of the operators (+ − * /) is
them, and the result is pushed on the stack. The = operator writes out the value of
CALC.H
/*----- FILE CALC.H --------------------------------------------------*/
/* */
/* Header file for CALC.C PUSHPOP.C READTOKN.C */
/* a simple calculator */
/*--------------------------------------------------------------------*/
typedef enum toks {
T_INTEGER,
T_PLUS,
T_TIMES,
T_MINUS,
T_DIVIDE,
T_EQUALS,
T_STOP
} Token;
Token read_token(char buf[]);
typedef struct int_link {
struct int_link * next;
int i;
} IntLink;
typedef struct int_stack {

IntLink * top;
} IntStack;
extern void push(IntStack *, int);
extern int pop(IntStack *);
CALC.C
/*----- FILE CALC.C --------------------------------------------------*/
/* */
/*--------------------------------------------------------------------*/
#include <stdio.h>
#include <stdlib.h>
#include "calc.h"
IntStack stack = { 0 };
main()
{
Token tok;
char word[100];
char buf_out[100];
int num, num2;
for(;;)
{
tok=read_token(word);
switch(tok)
{
case T_STOP:
break;
case T_INTEGER:
num = atoi(word);
push(&stack,num); /* CALC1 statement */
break;
case T_PLUS:
push(&stack, pop(&stack)+pop(&stack) );
break;
case T_MINUS:
num = pop(&stack);
push(&stack, num-pop(&stack));
break;
case T_TIMES:
push(&stack, pop(&stack)*pop(&stack));
break;
case T_DIVIDE:
num2 = pop(&stack);
num = pop(&stack);
push(&stack, num/num2); /*CALC2 statement */
break;
case T_EQUALS:
num = pop(&stack);
sprintf(buf_out,"= %d ",num);
push(&stack,num);
break;
}
if (tok==T_STOP)
break;
}
return 0;
}
PUSHPOP.C
/*----- FILE PUSHPOP.C -----------------------------------------------*/
/* */
/* A push and pop function for a stack of integers */
/*--------------------------------------------------------------------*/
#include <stdlib.h>
#include "calc.h"

/*--------------------------------------------------------------------*/
/* input: stk - stack of integers */
/* num - value to push on the stack */
/* action: get a link to hold the pushed value, push link on stack */
/* */
extern void push(IntStack * stk, int num)
{
IntLink * ptr;
ptr = (IntLink *) malloc( sizeof(IntLink)); /* PUSHPOP1 */
ptr–>i = num; /* PUSHPOP2 statement */
ptr–>next = stk–>top;
stk–>top = ptr;
}
/*--------------------------------------------------------------------*/
/* return: int value popped from stack */
/* action: pops top element from stack and gets return value from it */
/*--------------------------------------------------------------------*/
extern int pop(IntStack * stk)
{
IntLink * ptr;
int num;
ptr = stk–>top;
num = ptr–>i;
stk–>top = ptr–>next;
free(ptr);
return num;
}
READTOKN.C
/*----- FILE READTOKN.C ----------------------------------------------*/
/* */
/* A function to read input and tokenize it for a simple calculator */
/*--------------------------------------------------------------------*/
#include <ctype.h>
#include <stdio.h>
#include "calc.h"
/*--------------------------------------------------------------------*/
/* return: next input char */
/*--------------------------------------------------------------------*/
static char nextchar(void)
{
/*--------------------------------------------------------------------*/
/* input action: */
/* 2 push 2 on stack */
/* 18 push 18 */
/* + pop 2, pop 18, add, push result (20) */
/* 5 push 5 */
/* / pop 5, pop 20, divide, push result (4) */
/*--------------------------------------------------------------------*/
char * buf_in = "2 18 + = 5 / = ";
static int index; /* starts at 0 */
char ret;
ret = buf_in[index];
++index;
return ret;
}
/*--------------------------------------------------------------------*/
/* output: buf - null terminated token */
/* return: token type */
/* action: reads chars through nextchar() and tokenizes them */
/*--------------------------------------------------------------------*/
Token read_token(char buf[])
Chapter 23. Debugging a C program in full-screen mode 143

{
int i;
char c;
/* skip leading white space */
for( c=nextchar();
isspace(c);
c=nextchar())
;
buf[0] = c; /* get ready to return single char e.g."+" */
buf[1] = 0;
switch(c)
{
case '+' : return T_PLUS;
case '−' : return T_MINUS;
case '*' : return T_TIMES;
case '/' : return T_DIVIDE;
case '=' : return T_EQUALS;
default:
i = 0;
while (isdigit(c)) {
buf[i++] = c;
c = nextchar();
}
buf[i] = 0;
if (i==0)
return T_STOP;
else
return T_INTEGER;
}
}
Related tasks
Halting when certain functions are called in C

“Example: sample C program for debugging” on page 141
To halt just before read_token is called, issue the command:

AT CALL read_token ;
To halt just after read_token is called, issue the command:

AT ENTRY read_token ;
To take advantage of either of the above actions, you must compile your program
with the TEST compiler option.
Modifying the value of a C variable

To LIST the contents of a single variable, move the cursor to the variable name and
press PF4 (LIST). The value is displayed in the Log window. This is equivalent to
entering LIST TITLED variable on the command line.
Run the CALC program above to the statement labeled CALC1, move the cursor
over num and press PF4 (LIST). The following appears in the Log window:
LIST ( num ) ;
num = 2

To modify the value of num to 22, type over the num = 2 line with num = 22, press
Enter to put it on the command line, and press Enter again to issue the command.
You can enter most C expressions on the command line.
Now step into the call to push() by pressing PF2 (STEP) and step until the
statement labeled PUSHPOP2 is reached. To view the attributes of variable ptr,
issue the Debug Tool command:
DESCRIBE ATTRIBUTES *ptr;
The result in the Log window is similar to the following:

ATTRIBUTES for * ptr
Its address is 0BB6E010 and its length is 8
struct int_link
struct int_link *next;
int i;
You can use this action to browse structures and unions.
You can list all the values of the members of the structure pointed to by ptr with
the command:
LIST *ptr ;
with results in the Log window appearing similar to the following:

LIST * ptr ;
(* ptr).next = 0x00000000
(* ptr).i = 0
You can change the value of a structure member by issuing the assignment as a
command as in the following example:
(* ptr).i = 33 ;
Halting on a line in C only if a condition is true

times, but fails afterwards because a specific condition is present. Setting a simple
line breakpoint is an inefficient way to debug the program because you need to
execute the GO command a thousand times to reach the specific condition. You can
instruct Debug Tool to continue executing a program until a specific condition is
present.
For example, in the main procedure of the program above, you want to stop at
T_DIVIDE only if the divisor is 0 (before the exception occurs). Set the breakpoint
like this:
AT 40 { if(num2 != 0) GO; }
at line 40. If the value of num2 is not 0, the program continues. You can enter
Debug Tool commands to change the value of num2 to a nonzero value.
Debugging C when only a few parts are compiled with TEST


Suppose you want to set a breakpoint at entry to the function push() in the file
PUSHPOP.C. PUSHPOP.C has been compiled with TEST but the other files have
not. Debug Tool comes up with an empty Source window. To display the compile
units, enter the command:
LIST NAMES CUS
known to Debug Tool. Depending on the compiler you are using, or if
"USERID.MFISTART.C(PUSHPOP)" is fetched later on by the application, this compile
unit might not be known to Debug Tool. If it is displayed, enter:
SET QUALIFY CU "USERID.MFISTART.C(PUSHPOP)"
AT ENTRY push;
GO ;
or
AT ENTRY "USERID.MFISTART.C(PUSHPOP)":>push
GO;
If it is not displayed, set an appearance breakpoint as follows:

AT APPEARANCE "USERID.MFISTART.C(PUSHPOP)" ;
GO ;
The only purpose for this appearance breakpoint is to gain control the first time a
function in the PUSHPOP compile unit is run. When that happens, you can set
breakpoints at entry to push():
AT ENTRY push;

AT APPEARANCE "USERID.MFISTART.C(PUSHPOP)" AT ENTRY push; GO;
Capturing C output to stdout

To redirect stdout to the Log window, issue the following command:
SET INTERCEPT ON FILE stdout ;
With this SET command, you will capture not only stdout from your program, but
also from interactive function calls. For example, you can interactively call printf
on the command line to display a null-terminated string by entering:
printf(sptr);
You might find this easier than using LIST STORAGE.
Calling a C function from Debug Tool

You can start a library function (such as strlen) or one of the program functions
interactively by calling it on the command line.
Below, we call push() interactively to push one more value on the stack just before
a value is popped off.
AT CALL pop ;
GO ;
push(77);
GO ;

The calculator produces different results than before because of the additional
value pushed on the stack.
Displaying raw storage in C

A char * variable ptr can point to a piece of storage containing printable
characters. To display the first 20 characters enter:
LIST STORAGE(*ptr,20)
If the string is null terminated, you can also use an interactive function call on the
command line, as in:
puts(ptr) ;
Debugging a C DLL
Build PUSHPOP.C as a DLL, exporting push() and pop(). Build CALC.C and
READTOKN.C as the program that imports push() and pop() from the DLL
named PUSHPOP. When the application CALC starts the DLL, PUSHPOP will not
be known to Debug Tool. Use the AT APPEARANCE breakpoint to gain control in the
DLL the first time code in that compile unit appears, as shown in the following
example:
AT APPEARANCE "USERID.MFISTART.C(PUSHPOP)" ;
GO ;
The only purpose of this appearance breakpoint is to gain control the first time a
function in the PUSHPOP compile unit is run. When this happens, you can set
breakpoints in PUSHPOP.
Getting a function traceback in C

into that situation, and especially what the traceback of calling functions is. To get
LIST CALLS ;
For example, if you run the CALC example with the commands:
GO ;
LIST CALLS ;
the Log window will contain something like:

At ENTRY in C function CALC ::> "USERID.MFISTART.C(READTOKN)" :> read_token.
From LINE 18 in C function CALC ::> "USERID.MFISTART.C(CALC)" :> main :> %BLOCK2.

Tracing the run-time path for C code compiled with TEST
To trace a program showing the entry and exit points without requiring any
changes to the program, place the following Debug Tool commands in a file and
USE them when Debug Tool initially displays your program. Assuming you have a
data set USERID.DTUSE(TRACE) that contains the following Debug Tool commands:
int indent;
indent = 0;
SET INTERCEPT ON FILE stdout;
AT ENTRY * { \
++indent; \
if (indent < 0) indent = 0; \
printf("%*.s>%s\n", indent, " ", %block); \
GO; \
}
AT EXIT * {\
printf("%*.s<%s\n", indent, " ", %block); \
--indent; \
GO; \
}
following command:
USE USERID.DTUSE(TRACE)
The trace of running the program listed below after executing the USE file will be
displayed in the Log window.
int foo(int i, int j) {
return i+j;
}
int main(void) {
return foo(1,2);
}
The following trace in the Log window is displayed after running the sample
program, with the USE file as a source of input for Debug Tool commands:
>main
>foo
<foo
<main
Finding unexpected storage overwrite errors in C

you want to find out when and where this happens. Consider this example where
function set_i changes more than the caller expects it to change.
struct s { int i; int j;};
struct s a = { 0, 0 };
/* function sets only field i */

void set_i(struct s * p, int k)
{
p–>i = k;
p–>j = k; /* error, it unexpectedly sets field j also */

}
main() {
set_i(&a,123);
}
Find the address of a with the command

LIST &(a.j) ;
Suppose the result is 0x7042A04. To set a breakpoint that watches for a change in
AT CHANGE %STORAGE(0x7042A04,4)
When the program is run, Debug Tool will halt if the value in this storage changes.
Finding uninitialized storage errors in C

To help find your uninitialized storage errors, run your program with the
Language Environment TEST run-time and STORAGE options. In the following
example:
TEST STORAGE(FD,FB,F9)
the first subparameter of STORAGE is the fill byte for storage allocated from the
heap. For example, storage allocated through malloc() is filled with the byte 0xFD.
If you see this byte repeated through storage, it is likely uninitialized heap storage.
The second subparameter of STORAGE is the fill byte for storage allocated from the
heap but then freed. For example, storage freed by calling free() might be filled
with the byte 0xFB. If you see this byte repeated through storage, it is likely
storage that was allocated on the heap, but has been freed.
The third subparameter of STORAGE is the fill byte for auto storage variables in a
new stack frame. If you see this byte repeated through storage, it is likely
uninitialized auto storage.
The values chosen in the example are odd and large, to maximize early problem
detection. For example, if you attempt to branch to an odd address you will get an
exception immediately.
As an example of uninitialized heap storage, run program CALC with the

STORAGE run-time option as STORAGE(FD,FB,F9) to the line labeled PUSHPOP2
and issue the command:
LIST *ptr ;
You will see the byte fill for uninitialized heap storage as the following example
shows:
LIST * ptr ;
(* ptr).next = 0xFDFDFDFD
(* ptr).i = −33686019

Halting before calling a NULL C function
Calling an undefined function or calling a function through a function pointer that
points to NULL is a severe error. To halt just before such a call is run, set this
breakpoint:
AT CALL 0

Chapter 24. Debugging a C++ program in full-screen mode
The descriptions of basic debugging tasks for C++ refer to the following C++
program.
“Example: sample C++ program for debugging”
Related tasks
Chapter 30, “Debugging C and C++ programs,” on page 207
“Halting when certain functions are called in C++” on page 155
“Modifying the value of a C++ variable” on page 155
“Halting on a line in C++ only if a condition is true” on page 156
“Viewing and modifying data members of the this pointer in C++” on page 157
“Debugging C++ when only a few parts are compiled with TEST” on page 157
“Capturing C++ output to stdout” on page 158
“Calling a C++ function from Debug Tool” on page 158
“Displaying raw storage in C++” on page 158
“Debugging a C++ DLL” on page 158
“Getting a function traceback in C++” on page 159
“Tracing the run-time path for C++ code compiled with TEST” on page 159
“Finding unexpected storage overwrite errors in C++” on page 160
“Finding uninitialized storage errors in C++” on page 160
“Halting before calling a NULL C++ function” on page 161
Example: sample C++ program for debugging

integers are read, they are pushed on a stack. If one of the operators (+ − * /) is
them, and the result is pushed on the stack. The = operator writes out the value of
CALC.HPP
/*----- FILE CALC.HPP ------------------------------------------------*/
/* */
/* Header file for CALC.CPP PUSHPOP.CPP READTOKN.CPP */
/* a simple calculator */
/*--------------------------------------------------------------------*/
typedef enum toks {
T_INTEGER,
T_PLUS,
T_TIMES,
T_MINUS,
T_DIVIDE,
T_EQUALS,
T_STOP
} Token;
extern "C" Token read_token(char buf[]);
class IntLink {
private:
int i;
IntLink * next;
public:
IntLink();

~IntLink();
int get_i();
void set_i(int j);
IntLink * get_next();
void set_next(IntLink * d);
};
class IntStack {
private:
IntLink * top;
public:
IntStack();
~IntStack();
void push(int);
int pop();
};
CALC.CPP
/*----- FILE CALC.CPP ------------------------------------------------*/
/* */
/*--------------------------------------------------------------------*/
#include <stdio.h>
#include <stdlib.h>
#include "calc.hpp"
IntStack stack;
int main()
{
Token tok;
char word[100];
char buf_out[100];
int num, num2;
for(;;)
{
tok=read_token(word);
switch(tok)
{
case T_STOP:
break;
case T_INTEGER:
num = atoi(word);
stack.push(num); /* CALC1 statement */
break;
case T_PLUS:
stack.push(stack.pop()+stack.pop());
break;
case T_MINUS:
num = stack.pop();
stack.push(num-stack.pop());
break;
case T_TIMES:
stack.push(stack.pop()*stack.pop() );
break;
case T_DIVIDE:
num2 = stack.pop();
num = stack.pop();
stack.push(num/num2); /* CALC2 statement */
break;
case T_EQUALS:
num = stack.pop();
sprintf(buf_out,"= %d ",num);
stack.push(num);
break;
}
if (tok==T_STOP)

break;
}
return 0;
}
PUSHPOP.CPP
/*----- FILE: PUSHPOP.CPP --------------------------------------------*/
/* */
/* Push and pop functions for a stack of integers */
/*--------------------------------------------------------------------*/
#include <stdio.h>
#include <stdlib.h>
#include "calc.hpp"
/*--------------------------------------------------------------------*/
/* input: num - value to push on the stack */
/* action: get a link to hold the pushed value, push link on stack */
/*--------------------------------------------------------------------*/
void IntStack::push(int num) {
IntLink * ptr;
ptr = new IntLink;
ptr–>set_i(num);
ptr–>set_next(top);
top = ptr;
}
/*--------------------------------------------------------------------*/
/* return: int value popped from stack (0 if stack is empty) */
/* action: pops top element from stack and get return value from it */
/*--------------------------------------------------------------------*/
int IntStack::pop() {
IntLink * ptr;
int num;
ptr = top;
num = ptr–>get_i();
top = ptr–>get_next();
delete ptr;
return num;
}
IntStack::IntStack() {
top = 0;
}
IntStack::~IntStack() {
while(top)
pop();
}
IntLink::IntLink() { /* constructor leaves elements unassigned */
}
IntLink::~IntLink() {
}
void IntLink::set_i(int j) {
i = j;
}
int IntLink::get_i() {
return i;
}
void IntLink::set_next(IntLink * p) {
next = p;
}
IntLink * IntLink::get_next() {
return next;
}
READTOKN.CPP
/*----- FILE READTOKN.CPP --------------------------------------------*/
/* */
/* A function to read input and tokenize it for a simple calculator */
/*--------------------------------------------------------------------*/
Chapter 24. Debugging a C++ program in full-screen mode 153

#include <ctype.h>
#include <stdio.h>
#include "calc.hpp"
/*--------------------------------------------------------------------*/
/* return: next input char */
/*--------------------------------------------------------------------*/
static char nextchar(void)
{
/* input action
* ----- ------
* 2 push 2 on stack
* 18 push 18
* + pop 2, pop 18, add, push result (20)
* = output value on the top of the stack (20)
* 5 push 5
* / pop 5, pop 20, divide, push result (4)
* = output value on the top of the stack (4)
*/
char * buf_in = "2 18 + = 5 / = ";
static int index; /* starts at 0 */
char ret;
ret = buf_in[index];
++index;
return ret;
}
/*--------------------------------------------------------------------*/
/* output: buf - null terminated token */
/* return: token type */
/* action: reads chars through nextchar() and tokenizes them */
/*--------------------------------------------------------------------*/
extern "C"
Token read_token(char buf[])
{
int i;
char c;
/* skip leading white space */
for( c=nextchar();
isspace(c);
c=nextchar())
;
buf[0] = c; /* get ready to return single char e.g. "+" */
buf[1] = 0;
switch(c)
{
case '+' : return T_PLUS;
case '−' : return T_MINUS;
case '*' : return T_TIMES;
case '/' : return T_DIVIDE;
case '=' : return T_EQUALS;
default:
i = 0;
while (isdigit(c)) {
buf[i++] = c;
c = nextchar();
}
buf[i] = 0;
if (i==0)
return T_STOP;
else
return T_INTEGER;
}
}
Related tasks

Halting when certain functions are called in C++
You need to include the C++ signature along with the function name to set an AT
ENTRY or AT CALL breakpoint for a C++ function.
“Example: sample C++ program for debugging” on page 151
To facilitate entering the breakpoint, you can display PUSHPOP.CPP in the Source
window by typing over the name of the file on the top line of the Source window.
This makes PUSHPOP.CPP your currently qualified program. You can then issue
the command:
LIST NAMES
which displays the names of all the blocks and variables for the currently qualified
program. Debug Tool displays information similar to the following in the Log
window:
There are no session names.
The following names are known in block CALC ::> "USERID.MFISTART.CPP(PUSHPOP)"
IntStack::~IntStack()
IntStack::IntStack()
IntLink::get_i()
IntLink::get_next()
IntLink::~IntLink()
IntLink::set_i(int)
IntLink::set_next(IntLink*)
IntLink::IntLink()
Now you can save some keystrokes by inserting the command next to the block
name.
To halt just before IntStack::push(int) is called, insert AT CALL next to the

function signature and, by pressing Enter, the entire command is placed on the
command line. Now, with AT CALL IntStack::push(int) on the command line, you
can enter the command:
AT CALL IntStack::push(int)
To halt just after IntStack::push(int) is called, issue the command:

AT ENTRY IntStack::push(int) ;
in the same way as the AT CALL command.
To be able to halt, the file with the calling code must be compiled with the TEST
compiler option.
Modifying the value of a C++ variable

To list the contents of a single variable, move the cursor to the variable name and
press PF4 (LIST). The value is displayed in the Log window. This is equivalent to
entering LIST TITLED variable on the command line.
Run the CALC program and step into the first call of function
IntStack::push(int) until just after the IntLink has been allocated. Enter the
Debug Tool command:
LIST TITLED num

Debug Tool displays the following in the Log window:
LIST TITLED num;
num = 2
To modify the value of num to 22, type over the num = 2 line with num = 22, press
Enter to put it on the command line, and press Enter again to issue the command.
You can enter most C++ expressions on the command line.
To view the attributes of variable ptr in IntStack::push(int), issue the Debug Tool
command:
DESCRIBE ATTRIBUTES *ptr;

ATTRIBUTES for * ptr
Its address is 0BA25EB8 and its length is 8
class IntLink
signed int i
struct IntLink *next
So for most classes, structures, and unions, this can act as a browser.
You can list all the values of the data members of the class object pointed to by ptr
with the command:
LIST *ptr ;
with results in the Log window similar to:

LIST * ptr ; * ptr.i = 0 * ptr.next = 0x00000000
You can change the value of data member of a class object by issuing the
assignment as a command, as in this example:
(* ptr).i = 33 ;
Related tasks
“Using C and C++ variables with Debug Tool” on page 208
Halting on a line in C++ only if a condition is true

times, but fails under certain conditions. You don’t want to set a simple line
For example, in main you want to stop in T_DIVIDE only if the divisor is 0 (before
the exception occurs). Set the breakpoint like this:
AT 40 { if(num2 != 0) GO; }
at line 40. If the value of num is not 0, the program will continue. Debug Tool stops
on line 40 only if num2 is 0.

Viewing and modifying data members of the this pointer in C++
If you step into a class method, for example, one for class IntLink, the command:
LIST TITLED ;
responds with a list that includes this. With the command:

DESCRIBE ATTRIBUTES *this ;
you will see the types of the data elements pointed to by the this pointer. With the
command:
LIST *this ;
you will list the data member of the object pointed to and see something like:
LIST * this ;
(* this).i = 4
(* this).next = 0x0
in the Log window. To modify element i, enter either the command:

i = 2001;
or, if you have ambiguity (for example, you also have an auto variable named i),
enter:
(* this).i = 2001 ;
Debugging C++ when only a few parts are compiled with TEST
Suppose you want to set a breakpoint at entry to function IntStack::push(int) in

the file PUSHPOP.CPP. PUSHPOP.CPP has been compiled with TEST but the other
files have not. Debug Tool comes up with an empty Source window. To display the
compile units, enter the command:
LIST NAMES CUS
known to Debug Tool.
Depending on the compiler you are using, or if USERID.MFISTART.CPP(PUSHPOP) is

fetched later on by the application, this compile unit might or might not be known
to Debug Tool, and the PDS member PUSHPOP might or might not be displayed.
If it is displayed, enter:
SET QUALIFY CU "USERID.MFISTART.CPP(PUSHPOP)"
GO ;
or
AT ENTRY "USERID.MFISTART.CPP(PUSHPOP)":>push
GO
If it is not displayed, you need to set an appearance breakpoint as follows:

AT APPEARANCE "USERID.MFISTART.CPP(PUSHPOP)" ;
GO ;

AT APPEARANCE "USERID.MFISTART.CPP(PUSHPOP)" AT ENTRY push; GO;

function in the PUSHPOP compile unit is run. When that happens you can, for
example, set a breakpoint at entry to IntStack::push(int) as follows:
Capturing C++ output to stdout

To redirect stdout to the Log window, issue the following command:
SET INTERCEPT ON FILE stdout ;
With this SET command, you will not only capture stdout from your program, but
also from interactive function calls. For example, you can interactively use cout on
the command line to display a null terminated string by entering:
cout << sptr ;
You might find this easier than using LIST STORAGE.
For CICS only, SET INTERCEPT is not supported.
Calling a C++ function from Debug Tool

You can start a library function (such as strlen) or one of the programs functions
interactively by calling it on the command line. The same is true of C linkage
functions such as read_token. You cannot call C++ linkage functions interactively.
In the example below, we call read_token interactively.

AT CALL read_token;
GO;
read_token(word);
The calculator produces different results than before because of the additional
token removed from input.
Displaying raw storage in C++

A char * variable ptr can point to a piece of storage containing printable
characters. To display the first 20 characters, enter;
LIST STORAGE(*ptr,20)
If the string is null terminated, you can also use an interactive function call on the
command line as shown in this example:
puts(ptr) ;
Debugging a C++ DLL

Build PUSHPOP.CPP as a DLL, exporting IntStack::push(int) and IntStack::pop().

Build CALC.CPP and READTOKN.CPP as the program that imports
IntStack::push(int) and IntStack::pop() from the DLL named PUSHPOP. When the
application CALC starts, the DLL PUSHPOP is not known to Debug Tool. Use the
AT APPEARANCE breakpoint, as shown in the following example, to gain control in
the DLL the first time code in that compile unit appears.

AT APPEARANCE "USERID.MFISTART.CPP(PUSHPOP)" ;
GO ;
function in the PUSHPOP compile unit is run. When this happens, you can set
breakpoints in PUSHPOP.
Getting a function traceback in C++

into that situation, especially what the traceback of calling functions is. To get this
information, issue the command:
LIST CALLS ;
For example, if you run the CALC example with the following commands:
GO ;
LIST CALLS ;
the Log window contains something like:

At ENTRY in C function "USERID.MFISTART.CPP(READTOKN)" :> read_token.
From LINE 18 in C function "USERID.MFISTART.CPP(CALC)" :> main :> %BLOCK2.
Tracing the run-time path for C++ code compiled with TEST
To trace a program showing the entry and exit of that program without requiring
any changes to it, place the following Debug Tool commands, shown in the
example below, in a file and USE them when Debug Tool initially displays your
program. Assume you have a data set that contains USERID.DTUSE(TRACE) and
contains the following Debug Tool commands:
int indent;
indent = 0;
SET INTERCEPT ON FILE stdout;
AT ENTRY * { \
++indent; \
printf("%*.s>%s\n", indent, " ", %block); \
GO; \
}
AT EXIT * {\
printf("%*.s<%s\n", indent, " ", %block); \
--indent; \
GO; \
}
following command:
USE USERID.DTUSE(TRACE)
The trace of running the program listed below after executing the USE file is
displayed in the Log window:

int foo(int i, int j) {
return i+j;
}
int main(void) {
return foo(1,2);
}
The following trace in the Log window is displayed after running the sample
program, using the USE file as a source of input for Debug Tool commands:
>main
>foo(int,int)
<foo(int,int)
<main
command line, and the same effect will be achieved.
Finding unexpected storage overwrite errors in C++

you would like to find out when and where this happened. Consider this simple
example where function set_i changes more than the caller expects it to change.
struct s { int i; int j;};
struct s a = { 0, 0 };
/* function sets only field i */

void set_i(struct s * p, int k)
{
p–>i = k;
p–>j = k; /* error, it unexpectedly sets field j also */
}
main() {
set_i(&a,123);
}
Find the address of a with the command:

LIST &(a.j) ;
Suppose the result is 0x7042A04. To set a breakpoint that watches for a change in
storage values, starting at that address for the next 4 bytes, issue the command:
AT CHANGE %STORAGE(0x7042A04,4)
When the program is run, Debug Tool will halt if the value in this storage changes.
Finding uninitialized storage errors in C++

To help find your uninitialized storage errors, run your program with the
Language Environment TEST run-time and STORAGE options. In the following
example:
TEST STORAGE(FD,FB,F9)
the first subparameter of STORAGE is the fill byte for storage allocated from the
heap. For example, storage allocated through operator new is filled with the byte
0xFD. If you see this byte repeated throughout storage, it is likely uninitialized
heap storage.
The second subparameter of STORAGE is the fill byte for storage allocated from the
heap but then freed. For example, storage freed by the operator delete might be

filled with the byte 0xFB. If you see this byte repeated throughout storage, it is
likely storage that was allocated on the heap, but has been freed.
The third subparameter of STORAGE is the fill byte for auto storage variables in a
new stack frame. If you see this byte repeated throughout storage, it is likely that it
is uninitialized auto storage.
The values chosen in the example are odd and large, to maximize early problem
detection. For example, if you attempt to branch to an odd address, you will get an
exception immediately.
As an example of uninitialized heap storage, run program CALC, with the STORAGE
run-time option as STORAGE(FD,FB,F9), to the line labeled PUSHPOP2 and issue the
command:
LIST *ptr ;
You will see the byte fill for uninitialized heap storage as the following example
shows:
LIST * ptr ;
(* ptr).next = 0xFDFDFDFD
(* ptr).i = −33686019
Related references
Halting before calling a NULL C++ function

Calling an undefined function or calling a function through a function pointer that
points to NULL is a severe error. To halt just before such a call is run, set this
breakpoint:
AT CALL 0
When Debug Tool stops at this breakpoint, you can bypass the call by entering the
GO BYPASS command. This command allows you to continue your debug session
without raising a condition.

Chapter 25. Debugging an assembler program in full-screen
mode
The descriptions of basic debugging tasks for assembler refer to the following
assembler program.
“Example: sample assembler program for debugging”
Related tasks
Chapter 31, “Debugging an assembler program,” on page 231
“Defining a compilation unit as assembler and loading debug data” on page 166
“Defining a compilation unit in a different load module as assembler” on page 167
“Halting when certain assembler routines are called” on page 168
“Displaying and modifying the value of assembler variables or storage” on page 168
“Halting on a line in assembler only if a condition is true” on page 169
“Debugging assembler when debug data is only available for a few parts” on page 169
“Getting an assembler routine traceback” on page 170
“Finding unexpected storage overwrite errors in assembler” on page 170
Example: sample assembler program for debugging

To run this sample program, do the following steps:

1. Verify that the debug file for this assembler program is located in the SUBXMP
and DISPARM members of the yourid.EQALANGX data set.
2. Start Debug Tool.
3. To load the information in the debug file, enter the following commands:
LDD (SUBXMP,DISPARM)
This program is a small example of an assembler main routine (SUBXMP) that calls
an assembler subroutine (DISPARM).
Load module: XMPLOAD
SUBXMP.ASM
**************************************************************
* *
* NAME: SUBXMP *
* *
* A simple main assembler routine that brings up *
* Language Environment, calls a subroutine, and *
* returns with a return code of 0. *
* *
**************************************************************
SUBXMP CEEENTRY PPA=XMPPPA,AUTO=WORKSIZE
USING WORKAREA,R13
* Invoke CEEMOUT to issue the greeting message
CALL CEEMOUT,(HELLOMSG,DEST,FBCODE),VL,MF=(E,CALLMOUT)
* No plist to DISPARM, so zero R1. Then call it.
SLR R0,R0
ST R0,COUNTER
LA R0,HELLOMSG
SR R01,R01 ssue a message

CALL DISPARM CALL1
* Invoke CEEMOUT to issue the farewell message
CALL CEEMOUT,(BYEMSG,DEST,FBCODE),VL,MF=(E,CALLMOUT)
* Terminate Language Environment and return to the caller
CEETERM RC=0
* CONSTANTS
HELLOMSG DC Y(HELLOEND-HELLOSTR)
HELLOSTR DC C’Hello from the sub example.’
HELLOEND EQU *
BYEMSG DC Y(BYEEND-BYESTART)
BYESTART DC C’Terminating the sub example.’
BYEEND EQU *
DEST DC F’2’ Destination is the LE message file
COUNTER DC F’-1’
XMPPPA CEEPPA , Constants describing the code block

* The Workarea and DSA
WORKAREA DSECT
ORG *+CEEDSASZ Leave space for the DSA fixed part
CALLMOUT CALL ,(,,),VL,MF=L 3-argument parameter list
FBCODE DS 3F Space for a 12-byte feedback code
DS 0D
WORKSIZE EQU *-WORKAREA
PRINT NOGEN
CEEDSA , Mapping of the dynamic save area
CEECAA , Mapping of the common anchor area
R0 EQU 0
R01 EQU 1
R13 EQU 13
END SUBXMP Nominate SUBXMP as the entry point
DISPARM.ASM
**************************************************************
* *
* NAME: DISPARM *
* *
* Shows an assembler subroutine that displays inbound *
* parameters and returns. *
* *
**************************************************************
DISPARM CEEENTRY PPA=PARMPPA,AUTO=WORKSIZE,MAIN=NO
USING WORKAREA,R13
* Invoke CEE3PRM to retrieve the command parameters for us
SLR R0,R0
ST R0,COUNTER
CALL CEE3PRM,(CHARPARM,FBCODE),VL,MF=(E,CALL3PRM) CALL2
* Check the feedback code from CEE3PRM to see if everything worked.
CLC FBCODE(8),CEE000
BE GOT_PARM
* Invoke CEEMOUT to issue the error message for us
CALL CEEMOUT,(BADFBC,DEST,FBCODE),VL,MF=(E,CALLMOUT)
B GO_HOME Time to go....
GOT_PARM DS 0H
* See if the parm string is blank.
LA R1,1
SAVECTR ST R1,COUNTER
CL R1,=F’5’ BUMPCTR
BH LOOPEND
LA R1,1(,R1)
B SAVECTR
LOOPEND DS 0H
CLC CHARPARM(80),=CL80’ ’ Is the parm empty?
BNE DISPLAY_PARM No. Print it out.
* Invoke CEEMOUT to issue the error message for us

CALL CEEMOUT,(NOPARM,DEST,FBCODE),VL,MF=(E,CALLMOUT)
B GO_TEST Time to go....
DISPLAY_PARM DS 0H
* Set up the plist to CEEMOUT to display the parm.
LA R0,2
ST R0,COUNTER
LA R02,80 Get the size of the string
STH R02,BUFFSIZE Save it for the len-prefixed string
* Invoke CEEMOUT to display the parm string for us
CALL CEEMOUT,(BUFFSIZE,DEST,FBCODE),VL,MF=(E,CALLMOUT)
* AMODE Testing
GO_TEST DS 0H
L R15,INAMODE24@
BSM R14,R15
InAMode24 Equ *
LA R1,DEST
O R1,=X’FF000000’
L R15,0(,R1)
LA R15,2(,R15)
ST R15,0(,R1)
L R15,INAMODE31@
BSM R14,R15
InAMode31 Equ *
* Return to the caller
GO_HOME DS 0H
LA R0,3
ST R0,COUNTER
CEETERM RC=0
* CONSTANTS
DEST DC F’2’ Destination is the LE message file
CEE000 DS 3F’0’ Success feedback code
InAMode24@ DC A(InAMode24)
InAMode31@ DC A(InAMode31+X’80000000’)
BADFBC DC Y(BADFBEND-BADFBSTR)
BADFBSTR DC C’Feedback code from CEE3PRM was nonzero.’
BADFBEND EQU *
NOPARM DC Y(NOPRMEND-NOPRMSTR)
NOPRMSTR DC C’No user parm was passed to the application.’
NOPRMEND EQU *
PARMPPA CEEPPA , Constants describing the code block
* ===================================================================
WORKAREA DSECT
ORG *+CEEDSASZ Leave space for the DSA fixed part
CALL3PRM CALL ,(,),VL,MF=L 2-argument parameter list
CALLMOUT CALL ,(,,),VL,MF=L 3-argument parameter list
FBCODE DS 3F Space for a 12-byte feedback code
COUNTER DS F
BUFFSIZE DS H Halfword prefix for following string
CHARPARM DS CL255 80-byte buffer
DS 0D
WORKSIZE EQU *-WORKAREA
PRINT NOGEN
CEEDSA , Mapping of the dynamic save area
CEECAA , Mapping of the common anchor area
MYDATA DSECT ,
MYF DS F
R0 EQU 0
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5
R6 EQU 6
R7 EQU 7
R8 EQU 8
Chapter 25. Debugging an assembler program in full-screen mode 165

R9 EQU 9
R10 EQU 10
R11 EQU 11
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
R02 EQU 2
END
Defining a compilation unit as assembler and loading debug data

Before you can debug an assembler program, the assembler compilation unit (CU)
must meet the following requirements:
v The CU must be known to Debug Tool.
v The CU must be defined as a disassembly CU.
To ensure that a CU is known to Debug Tool, do the following steps:

1. Make sure that the load module that contains the CU has been loaded into
storage.
2. After you start Debug Tool, enter one of the following commands:
v SET ASSEMBLER ON ;
v SET DISASSEMBLY ON ;
3. Enter the LIST NAMES CUS command or the LIST command.
4. In the Log window, verify that the CU of the assembler program that you want
to debug is listed.
After doing these steps, you must define the CU as an assembler CU and load the
debug data that is associated with that program. To accomplish these objectives,
use the LOADDEBUGDATA command (abbreviated as LDD) as follows:
v If your assembler debug data is in a partitioned data set where the high-level
qualifier is the current user ID, the low-level qualifier is EQALANGX, and the
member name is the same as the name of the CU that you want to debug, enter
the following command:
LDD membername
v If your assembler debug data is in a different partitioned data set than
userid.EQALANGX but the member name is the same as the name of the CU that
you want to debug, enter the following command before or after you enter LDD
membername:
SET DEFAULT LISTINGS
v If your assembler debug data is in a sequential data set or is a member of a
partitioned data set but the member name is different from the CU name, enter
the following command before or after you enter LDD membername:
SET SOURCE
After you have entered an LDD command for a CU, you cannot view the CU as a
disassembly CU.
If Debug Tool cannot find the associated assembler debug data after you have
entered an LDD command, the CU is an assembler CU rather than a disassembly
CU. You cannot enter another LDD command for this CU. However, you can enter a
SET DEFAULT LISTING command or a SET SOURCE command to cause the associated
debug data to be loaded from a different data set.

Defining a compilation unit in a different load module as assembler
As described in the previous section, you can use the LDD command to identify a
CU as an assembler CU only after the CU name is known to Debug Tool. If the CU
is part of a load module that has not yet been loaded, you can use the following
technique to accomplish this.
First, make sure that you have previously issued a SET ASSEMBLER ON or SET
DISASSEMBLY ON command. The CU will not be recognized by the following
command if you have not previously issued one of these commands. Next, issue
the AT APPEARANCE cuname or AT APPEARANCE * command. When the AT APPEARANCE
breakpoint is triggered for the desired CU, you can then issue the LDD command
for that CU.
You can combine these steps into the following command:

AT APPEARANCE cuname LDD cuname
Note that if a CU name is already known to Debug Tool, the AT APPEARANCE

breakpoint will never trigger. For this reason, it is important to ensure that the CU
is not already known to Debug Tool before using this technique.
Multiple compilation units in a single assembly

Debug Tool treats each assembler CSECT as a separate compilation unit (CU). If
your assembler source contains more than one CSECT, the EQALANGX file, which
you create by running the EQALANGX program, contains debug information for
all CSECTs. Debug Tool, however, locates debug information as if each CU
(CSECT) were in separate EQALANGX files.
For example, you have an assembly that generates two CSECTs: MYPROG and
MYPROGA. The debug information for both of these CSECTs is in the data set
yourid.EQALANGX(MYPROG). If you enter the LOADDEBUGDATA (LDD) command for
MYPROG, Debug Tool finds and loads the debug information for both MYPROG
and MYPROGA. However, because you entered the LDD command only for
MYPROG, Debug Tool uses only the debug information for MYPROG. Then, if you
enter the command LDD MYPROGA, Debug Tool looks for debug information in
yourid.EQALANGX(MYPROGA). If it finds an EQALANGX file in that location, it uses
that file. If it doesn’t find an EQALGANX file, it displays a message indicating that
no debug information was found.
To instruct Debug Tool to use the debug information for MYPROGA that is located
in yourid.EQALANGX(MYPROG), enter the SET SOURCE command, either before or after
you enter the LDD MYPROGA command. The SET SOURCE command instructs Debug
Tool to associate the data set name yourid.EQALANGX(MYPROG) with the CU
MYPROGA.
The following set of commands instruct Debug Tool to load debug information for
MYPROG and MYPROGA from the MYPROG member of the EQALANGX data
set:
LDD MYPROG ;
SET SOURCE ON (MYPROGA) myuserid.EQALANGX(MYPROG) ;
LDD MYPROGA ;

Halting when certain assembler routines are called
“Example: sample assembler program for debugging” on page 163
To halt after the DISPARM routine is called, enter the command:

AT ENTRY DISPARM
The AT CALL command is not supported for assembler routines. Do not use the AT
CALL command to stop Debug Tool when an assembler routine is called.
QUERY LOCATION
QUERY LOCATION
You are executing commands in the ENTRY XMPLOAD ::> DISPARM breakpoint.
The program is currently entering block XMPLOAD ::> DISPARM.
Displaying and modifying the value of assembler variables or storage

variable name in the Source window and press PF4 (LIST). The value is displayed
in the Log window. This is equivalent to entering LIST variable on the command
line.
For example, run the SUBXMP program to the statement labeled CALL1 by
entering AT 70 ; GO ; on the Debug Tool command line. Scroll up until you see
line 67. Move the cursor over COUNTER and press PF4 (LIST). The following
appears in the Log window:
LIST ( COUNTER )
COUNTER = 0
To modify the value of COUNTER to 1, type over the COUNTER = 0 line with
COUNTER = 1, press Enter to put it on the command line, and press Enter again
to issue the command.
To list the contents of the 16 bytes of storage 2 bytes past the address contained in
register R0, type the command LIST STORAGE(R0->+2,16) on the command line and
press Enter. The contents of the specified storage are displayed in the Log window.
LIST STORAGE( R0 -> + 2 , 16 )
000C321E C8859393 96408699 969440A3 888540A2 *Hello from the s*
To modify the first two bytes of this storage to X’C182’, type the command R0->+2
<2> = X’C182’; on the command line and press Enter to issue the command.
Now step into the call to DISPARM by pressing PF2 (STEP) and step until the line
labeled CALL2 is reached. To view the attributes of variable COUNTER, issue the
Debug Tool command:
DESCRIBE ATTRIBUTES COUNTER

ATTRIBUTES for COUNTER
Its address is 1B0E2150 and its length is 4
DS F

Halting on a line in assembler only if a condition is true
times, but it fails under certain conditions. Setting a line breakpoint is inefficient
because you will have to repeatedly enter the GO command.
In the DISPARM program, to stop Debug Tool when the COUNTER variable is set to
3, enter the following command:
AT 78 DO; IF COUNTER ^= 3 THEN GO; END;
Line 78 is the line labeled BUMPCTR. The command causes Debug Tool to stop at
line 78. If the value of COUNTER is not 1, the program continues. The command
causes Debug Tool to stop on line 78 only if the value of COUNTER is 3.
Debugging assembler when debug data is only available for a few

parts
Suppose you want to set a breakpoint at the entry point to subroutine DISPARM
and that debug data is available for DISPARM but not for SUBXMP. In this
circumstance, Debug Tool would display an empty Source window. To display the
compile units, enter the following commands:
SET ASSEMBLER ON
LIST NAMES CUS
known to Debug Tool. If DISPARM is fetched later on by the application, this
compile unit might not be known to Debug Tool. If DISPARM is displayed in the
output of the LIST NAMES CUS command, enter the following commands:
SET QUALIFY CU DISPARM
AT ENTRY DISPARM LDD DISPARM
GO
If DISPARM is not displayed in the output of the LIST NAMES CUS command, enter
the following commands:
AT APPEARANCE DISPARM
GO
You can combine these commands into one command, as follows:

AT APPEARANCE DISPARM AT ENTRY DISPARM LDD DISPARM; GO;
The purpose of the AT APPEARANCE commands is to give Debug Tool control of the
DISPARM compile unit when it is first loaded. After it is loaded, you can set a
breakpoint at the entry point to DISPARM by entering the following command:

Getting an assembler routine traceback
Often when you get close to a programming error, you want to know what
sequence of calls lead you to the programming error. This sequence is called
traceback or traceback of callers. To get the traceback information, enter the
following command:
LIST CALLS
For example, if you run the SUBXMP example with the following commands, the
Log window displays the traceback of callers:
AT ENTRY DISPARM
GO
LIST CALLS
The Log window displays information similar to the following:

At ENTRY IN Assembler routine XMPLOAD ::> DISPARM.
From LINE 76.1 IN Assembler routine XMPLOAD ::> SUBXMP.
Finding unexpected storage overwrite errors in assembler

While your program is running, some storage might unexpectedly change its value
and you want to find out when and where this happened. Consider the following
example, where the program finds a value unexpectedly modified:
L R0,X’24’(R3)
To find the address of the operand being loaded, enter the following command:
LIST R3->+X’24’
Suppose the result is X'00521D42'. To set a breakpoint that watches for a change in
storage values starting at that address and for the next 4 bytes, enter the following
command:
AT CHANGE %STORAGE(X’00521D42’,4)
When the program runs, Debug Tool stops if the value in this storage changes.

Chapter 26. Customizing your full-screen session
You have several options for customizing your session. For example, you can
resize and rearrange windows, close selected windows, change session parameters,
and change session panel colors. This section explains how to customize your
session using these options.
The window acted upon as you customize your session is determined by one of
several factors. If you specify a window name (for example, WINDOW OPEN MONITOR
to open the Monitor window), that window is acted upon. If the command is
cursor-oriented, such as the WINDOW SIZE command, 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 setting of
Default window under the Profile Settings panel.
Related tasks
Chapter 20, “Using full-screen mode: overview,” on page 93
Chapter 26, “Customizing your full-screen session”
“Defining PF keys”
“Defining a symbol for commands or other strings”
“Customizing session panel colors” on page 174
“Saving customized settings in a preferences files” on page 177
Defining PF keys
To define your PF keys, use the SET PFKEY command. For example, to define the
PF8 key as SCROLL DOWN PAGE, enter one of the following commands:
v For PL/I:
SET PF8 'Down' = SCROLL DOWN PAGE ;
v For C and C++:
SET PF8 "Down" = SCROLL DOWN PAGE ;
Use single quotation marks for PL/I, double quotation marks for C and C++.
Assembler, COBOL, and disassembly allow the use of single or double quotation
marks. The string set apart by the quotation marks (Down in this example) is the
label that appears next to PF8 when you SET KEYS ON and your PF key definitions
are displayed at the bottom of your screen.
Related references
“Initial PF key settings” on page 103
Defining a symbol for commands or other strings

You can define a symbol to represent a long character string. For example, if you
have a long command that you do not want to retype several times, you can use
the SET EQUATE command to equate the command to a short symbol. Afterwards,
Debug Tool treats the symbol as though it were the command. The following
examples show various settings for using EQUATEs:

v SET EQUATE info = "abc, def(h+1)"; Sets the symbol info to the string, "abc,
def(h+1)". The use of single quotes (’, ’) or double quotes (″, ″) is language
dependent.
v CLEAR EQUATE (info); Disassociates the symbol and the string. This example
clears info.
v CLEAR EQUATE; If you do not specify what symbol to clear, all symbols created by
SET EQUATE are cleared.
If a symbol created by a SET EQUATE command is the same as a keyword or

keyword abbreviation in an HLL, the symbol takes precedence. If the symbol is
already defined, the new definition replaces the old. Operands of certain
commands are for environments other than the standard Debug Tool environment,
and are not scanned for symbol substitution.
Customizing the layout of windows on the session panel

To change the relative layout of the Source, Monitor, and Log windows, use the
PANEL LAYOUT command (the PANEL keyword is optional).
The PANEL LAYOUT command displays the panel below, showing the six possible
window layouts.
Window Layout Selection Panel
Command ===>
1 2 3

1 .-----------. 2 .-----------. 3 .-----------. Legend:
| M | | _ | _ | | _ |
|-----------| | | | | | L - Log
| S | |-----------| |-----------| M - Monitor
|-----------| | _ | | _ | _ | S - Source
| L | | | | | |
’-----------’ ’-----------’ ’-----------’ To reassign the
Source, Monitor,
4 5 6
4 .-----------. 5 .-----------. 6 .-----------. and Log windows,
| _ | _ | _ | | _ | _ | | _ | _ | type over the
| | | | | | | | | | current settings
| | | | |-----| | | |-----| or underscores
| | | | | _ | | | | _ | with L, M, or S.
| | | | | | | | | |
’-----------’ ’-----------’ ’-----------’
Enter END/QUIT to return with current settings saved.

CANCEL to return without current settings saved.
Initially, the session panel uses the default window layout 1.
Follow the instructions on the screen, then press the END PF key to save your
changes and return to the main session panel in the new layout.
Note: You can choose only one of the six layouts. Also, only one of each type of
window can be visible at a time on your session panel. For example, you
cannot have two Log windows on a panel.
Related tasks
“Opening and closing session panel windows” on page 173
“Resizing session panel windows” on page 173
“Zooming a window to occupy the whole screen” on page 173

Related references
Opening and closing session panel windows

To close a window, either:
v Type the WINDOW CLOSE command, move the cursor to the window you want to
close, then press Enter.
or
v Enter the WINDOW CLOSE LOG, WINDOW CLOSE MONITOR, or WINDOW CLOSE SOURCE
command.
When you close a window, the remaining windows occupy the full area of the
screen.
To open a window, enter the WINDOW OPEN LOG, WINDOW OPEN MONITOR, or WINDOW
OPEN SOURCE command.
The WINDOW CLOSE command can be assigned to a PF key.
If you want to monitor the values of selected variables as they change during your
Debug Tool session, the Monitor window must be open. If it is closed, open it as
described above. The Monitor window occupies the available space according to
your selected window layout.
If at any time during your session you open a window and the contents assigned
to it are not available, the window is empty.
Resizing session panel windows

To resize windows, type WINDOW SIZE on the command line, move the cursor to
where you want the window boundary, then press Enter. The WINDOW keyword is
optional.
Rather than using the cursor, you can also explicitly specify the number of rows or
columns you want the window to contain (as appropriate for the window layout).
For example, to change the Source window from 10 rows deep to 12 rows deep,
enter:
WINDOW SIZE 12 SOURCE
WINDOW SIZE can be assigned to a PF key.
To restore window sizes to their default values for the current window layout,
enter the PANEL LAYOUT RESET command.
Zooming a window to occupy the whole screen

To toggle a window to full screen (temporarily not displaying the others), move
the cursor into that window and press PF10 (ZOOM). Press PF10 to toggle back.
PF11 (ZOOM LOG) toggles the Log window in the same way, without the cursor
needing to be in the Log window.
Chapter 26. Customizing your full-screen session 173

Customizing session panel colors
You can change the color and highlighting on your session panel to distinguish the
fields on the panel. Consider highlighting such areas as the current line in the
Source window, the prefix area, and the statement identifiers where breakpoints
have been set.
To change the color, intensity, or highlighting of various fields of the session panel
on a color terminal, use the PANEL COLORS command. When you issue this
command, the panel shown below appears.
Color Selection Panel
Command ===>
Color Highlight Intensity
Title : field headers TURQ NONE HIGH
output fields GREEN NONE LOW Valid Color:
Monitor: contents TURQ REVERSE LOW White Yellow Blue
line numbers TURQ REVERSE LOW Turq Green Pink Red
Source : listing area WHITE REVERSE LOW
prefix area TURQ REVERSE LOW Valid Intensity:
suffix area YELLOW REVERSE LOW High Low
current line RED REVERSE HIGH
breakpoints GREEN NONE LOW Valid Highlight:
Log : program output TURQ NONE HIGH None Reverse
test input YELLOW NONE LOW Underline Blink
test output GREEN NONE HIGH
line numbers BLUE REVERSE HIGH Color and Highlight
Command line WHITE NONE HIGH are valid only with
Window headers GREEN REVERSE HIGH color terminals.
Tofeof delimiter BLUE REVERSE HIGH
Search target RED NONE HIGH
Initially, the session panel areas and fields have the default color and attribute
values shown above.
The usable color attributes are determined by the type of terminal you are using. If
you have a monochrome terminal, you can still use highlighting and intensity
attributes to distinguish fields.
To change the color and attribute settings for your Debug Tool session, enter the
desired colors or attributes over the existing values of the fields you want to
change. The changes you make are saved when you enter QUIT.
You can also change the colors or intensity of selected areas by issuing the
equivalent SET COLOR command from the command line. Either specify the fields
explicitly, or use the cursor to indicate what you want to change. Changing a color
or highlight with the equivalent SET command changes the value on the Color
Selection Panel.
Settings remain in effect for the entire debug session.
To preserve any changes you make to the default color fields, specify a file before
you begin your session using the ddname inspsafe and the dsname or fileid of
your choice. Debug Tool recognizes any file with this ddname as the file where it
saves session panel settings for use during subsequent sessions. If you do not
allocate this file before your session, Debug Tool begins the next debug session
with the default values shown in the panel above.

Related tasks
Customizing profile settings

The PANEL PROFILE command displays the Profile Settings Panel, which contains
profile settings that affect the way Debug Tool runs. This panel is shown below
with the IBM-supplied initial settings.
Profile Settings Panel
Command ===>
Current Setting
---------------
Change Test Granularity STATEMENT (All,Blk,Line,Path,Stmt)
DBCS characters NO (Yes or No)
Default Listing PDS name
Default scroll amount PAGE (Page,Half,Max,Csr,Data,int)
Default window SOURCE (Log,Monitor,Source)
Execute commands YES (Yes or No)
History YES (Yes or No)
History size 100 (nonnegative integer)
Logging YES (Yes or No)
Pace of visual trace 2 (steps per second)
Refresh screen NO (Yes or No)
Rewrite interval 50 (number of output lines)
Session log size 1000 (number of retained lines)
Show log line numbers YES (Yes or No)
Show message ID numbers NO (Yes or No)
Show monitor line numbers YES (Yes or No)
Show scroll field YES (Yes or No)
Show source/listing suffix YES (Yes or No)
Show warning messages YES (Yes or No)
Test level ALL (All,Error,None)
You can change the settings either by typing your desired values over them, or by
issuing the appropriate SET command at the command line or from within a
command file.
The profile parameters, their descriptions, and the equivalent SET commands are as
follows:
Change Test Granularity
Specifies the granularity of testing for AT CHANGE. Equivalent to SET CHANGE.
DBCS characters
Controls whether the shift-in or shift-out characters are recognized. Equivalent
to SET DBCS.
Default Listing PDS name
If specified, the data set where Debug Tool looks for the source or listing.
Equivalent to SET DEFAULT LISTINGS.
Default scroll amount
Specifies the default amount assumed for SCROLL commands where no amount
is specified. Equivalent to SET DEFAULT SCROLL.
Default window
Selects the default window acted upon when WINDOW commands are issued
with the cursor on the command line. Equivalent to SET DEFAULT WINDOW.

Execute commands
Controls whether commands are executed or just checked for syntax errors.
Equivalent to SET EXECUTE.
History
Controls whether a history (an account of each time Debug Tool is entered) is
maintained. Equivalent to SET HISTORY.
History size
Controls the size of the Debug Tool history table. Equivalent to SET HISTORY.
Logging
Controls whether a log file is written. Equivalent to SET LOG.
Pace of visual trace
Sets the maximum pace of animated execution. Equivalent to SET PACE.
Refresh screen
Clears the screen before each display. REFRESH is useful when there is another
application writing to the screen. Equivalent to SET REFRESH.
Rewrite interval
Defines the number of lines of intercepted output that are written by the
application before Debug Tool refreshes the screen. Equivalent to SET REWRITE.
Session log size
The number of session log output lines retained for display. Equivalent to SET
LOG.
Show log line numbers
Turns line numbers on or off in the log window. Equivalent to SET LOG
NUMBERS.
Show message ID numbers
Controls whether ID numbers are shown in Debug Tool messages. Equivalent
to SET MSGID.
Show monitor line numbers
Turns line numbers on or off in the monitor window. Equivalent to SET
MONITOR NUMBERS.
Show scroll field
Controls whether the scroll amount field is shown in the display. Equivalent to
SET SCROLL DISPLAY.
Show source/listing suffix
Controls whether the frequency suffix column is displayed in the Source
window. Equivalent TO SET SUFFIX.
Show warning messages (C and C++ and PL/I only)
Controls whether warning messages are shown or conditions raised when
commands contain evaluation errors. Equivalent to SET WARNING.
Test level
Selects the classes of exceptions to cause automatic entry into Debug Tool.
Equivalent to SET TEST.
A field indicating scrolling values is shown only if the screen is not large enough
to show all the profile parameters at once. This field is not shown in the example
panel above.
You can change the settings of these profile parameters at any time during your
session. For example, you can increase the delay that occurs between the execution

of each statement when you issue the STEP command by modifying the amount
specified in the Pace of visual trace field at any time during your session.
To modify the profile settings for your session, enter a new value over the old
value in the field you want to change. Equivalent SET commands are issued when
you QUIT from the panel.
Entering the equivalent SET command changes the value on the Profile Settings
panel as well.
To preserve any changes you make to the default profile settings, specify a file
before you begin your session using the ddname inspsafe and the dsname or
fileid of your choice. Debug Tool recognizes any file with this ddname as the file
where it saves session panel settings for use during subsequent sessions. All PANEL
settings are saved, except the setting for the Listing panel and the following
settings:
COUNTRY
FREQUENCY
INTERCEPT
LOG
NATIONAL LANGUAGE
PROGRAMMING LANGUAGE
QUALIFY
SOURCE
TEST
If you do not allocate this file before your session, Debug Tool begins the next
debug session with the values shown in the example panel above.
Settings remain in effect for the entire debug session.
Related tasks
“Saving customized settings in a preferences files”
Saving customized settings in a preferences files

You can place a set of commands into a data set, called a preferences file, and then
indicate that file should be used by providing its name in the preferences_file
suboption of the TEST run-time string. Debug Tool reads these commands at
initialization and sets up the session appropriately.
Below is an example preferences file.

SET TEST ERROR;
SET DEFAULT SCROLL CSR;
SET HISTORY OFF;
SET MSGID ON;
DESCRIBE CUS;

Part 5. Debugging your programs by using Debug Tool
commands

Chapter 27. Entering Debug Tool commands
Debug Tool commands can be issued in three modes: full-screen, line, and batch.
Some Debug Tool commands are valid only in certain modes or programming
languages. Unless otherwise noted, Debug Tool commands are valid in all modes,
and for all supported languages.
For input typed directly at the terminal, input is free-form, optionally starting in
column 1.
To separate multiple commands on a line, use a semicolon (;). This terminating

semicolon is optional for a single command, or the last command in a sequence of
commands.
For input that comes from a commands file or USE file, all of the Debug Tool
commands must be terminated with a semicolon, except for the C block command.
Related tasks
“Abbreviating Debug Tool keywords” on page 182
“Entering multiline commands in full-screen and line mode” on page 183
“Entering multiline commands in a command file” on page 183
“Entering multiline commands without continuation” on page 184
“Using blanks in Debug Tool commands” on page 184
“Entering comments in Debug Tool commands” on page 184
“Using constants in Debug Tool commands” on page 185
“Getting online help for Debug Tool command syntax” on page 185
Related references
Using uppercase, lowercase, and DBCS in Debug Tool commands

The character set and case vary with the double-byte character set (DBCS) or the
current programming language setting in a Debug Tool session.
DBCS
When the DBCS setting is ON, you can specify DBCS characters in the following
portions of all the Debug Tool commands:
v Commentary text
v Character data valid in the current programming language
v Symbolic identifiers such as variable names (for COBOL, this includes session
variables), entry names, block names, and so forth (if the names contain DBCS
characters in the application program).
When the DBCS setting is OFF, double-byte data is not correctly interpreted or
displayed. However, if you use the shift-in and shift-out codes as data instead of
DBCS indicators, you should issue SET DBCS OFF.
If you are debugging in full-screen mode and your terminal is not DBCS capable,
the SET DBCS ON command is not available.

Character case and DBCS in C and C++
For both C and C++, Debug Tool sets the programming language to C. When the
current programming language setting is C:
v All keywords and identifiers must be the correct case. Debug Tool does not do
conversion to uppercase.
v DBCS characters are allowed only within comments and literals.
v Either trigraphs or the equivalent special characters can be used. Trigraphs are
treated as their equivalents at all times. For example, FIND "??<" would find not
only "??<" but also "{".
v The vertical bar (|) can be entered for the following C and C++ operations:
bitwise or (|), logical or (||), and bitwise assignment or (|=).
v There are alternate code points for the following C and C++ characters: vertical
bar (|), left brace ({), right brace (}), left bracket ([), and right bracket (]) .
Although alternate code points will be accepted as input for the braces and
brackets, the primary code points will always be logged.
Character case in COBOL and PL/I

When the current programming language setting is not C, commands can generally
be either uppercase, lowercase, or mixed. Characters in the range a through z are
automatically converted to uppercase except within comments and quoted literals.
Also, in PL/I, only "|" and "¬" can be used as the boolean operators for OR and
NOT.
Abbreviating Debug Tool keywords

When you issue the Debug Tool commands, you can truncate most command
keywords. You cannot truncate reserved keywords for the different programming
languages, system keywords (that is, SYS, SYSTEM, or TSO) or special case keywords
such as BEGIN, CALL, COMMENT, COMPUTE, END, FILE (in the SET INTERCEPT and SET LOG
commands), GOTO, INPUT, LISTINGS (in the SET DEFAULT LISTINGS command), or USE.
In addition, PROCEDURE can only be abbreviated as PROC.
The system keywords, and COMMENT, INPUT, and USE keywords, take precedence
over other keywords and identifiers. If one of these keywords is followed by a
blank, it is always parsed as the corresponding command. Hence, if you want to
assign the value 2 to a variable named TSO and the current programming
language setting is C, the "=" must be abutted to the reference, as in "TSO<no
space>= 2;" not "TSO<space>= 2;". If you want to define a procedure named USE,
you must enter "USE<no space>: procedure;" not "USE<space>:: procedure;".
When you truncate, you need only enter enough characters of the command to
distinguish the command from all other valid Debug Tool commands. You should
not use truncations in a commands file or compile them into programs because
they might become ambiguous in a subsequent release. The following shows
examples of Debug Tool command truncations:
If you enter the following command... It will be interpreted as...

A 3 AT 3
G GO
Q B B QUALIFY BLOCK B
Q Q QUERY QUALIFY
Q QUIT

If you specify a truncation that is also a variable in your program, the keyword is
chosen if this is the only ambiguity. For example, LIST A does not display the
value of variable A, but executes the LIST AT command, listing your current AT
breakpoints. To display the value of A, issue LIST (A).
In addition, ambiguous commands that cannot be resolved cause an error message

and are not performed. That is, there are two commands that could be interpreted
by the truncation specified. For example, D A A; is an ambiguous truncation since
it could either be DESCRIBE ATTRIBUTES a; or DISABLE AT APPEARANCE;. Instead, you
would have to enter DE A A; if you wanted DESCRIBE ATTRIBUTES a; or DI A A; if
you wanted DISABLE AT APPEARANCE;. There are, of course, other variations that
would work as well (for example, D ATT A;).
Entering multiline commands in full-screen and line mode

If you need to use more than one line when entering a command, you must use a
continuation character.
When you are entering a command in interactive mode, the continuation character
must be the last nonblank character in each line that is to be continued. In the
following example:
LIST (" this is a very very very vvvvvvvvvvvvvvvvvvvvvvvvvvvvv –
very long string");
the continuation character is the single-byte character set (SBCS) hyphen (-).
If you want to end a line with a character that would be interpreted as a

continuation character, follow that character with another valid nonblank character.
For example, in C and C++, if you want to enter "i––", you could enter "(i––)" or
"i––;". When the current programming language setting is C and C++, the back
slash character (\) can also be used.
When Debug Tool is awaiting the continuation of a command in full-screen mode,

you receive a continuation prompt of "MORE..." until the command is completely
entered and processed. When continuation is indicated in line mode, you receive a
continuation prompt of "PENDING..." until the command is completely entered
and processed.
Entering multiline commands in a command file

The rules for line continuation when input comes from a commands file are
language-specific:
v When the current programming language setting is C and C++, identifiers,
keywords, and literals can be continued from one line to the next if the back
slash continuation character is used. The following is an example of the
continuation character for C:
LIST (" this is a very very very vvvvvvvvvvvvvvvvvvvvvvvvvvvvv\
very long string");
v When the current programming language setting is COBOL, columns 1-6 are
ignored by Debug Tool and input can be continued from one line to the next if
the SBCS hyphen (-) is used in column 7 of the next line. Command text must
begin in column 8 or later and end in or before column 72.
Chapter 27. Entering Debug Tool commands 183

In literal string continuation, an additional double (") or single (') quote is
required in the continuation line, and the character following the quote is
considered to follow immediately after the last character in the continued line.
The following is an example of line continuation for COBOL:
123456 LIST (" this is a very very very vvvvvvvvvvvvvvvvvvvvvvv"
123456-"very long string");
Continuation is not allowed within a DBCS name or literal string when the
current programming language setting is COBOL.
Entering multiline commands without continuation

You can enter the following command parts on separate lines without using the
SBCS hyphen (-) continuation character:
v Subcommands and the END keyword in the PROCEDURE command
v When the current programming language setting is C, statements that are part of
a compound or block statement
v When the current programming language setting is COBOL:
– EVALUATE
- Subcommands in WHEN and OTHER clauses
- END-EVALUATE keyword
– IF
- Subcommands in THEN and ELSE clauses
- END-IF keyword
– PERFORM
- Subcommands
- Subcommands in UNTIL clause
- END-PERFORM keyword
Using blanks in Debug Tool commands

Blanks cannot occur within keywords, identifiers, and numeric constants; however,
they can occur within character strings. Blanks between keywords, identifiers, or
constants are ignored except as delimiters. Blanks are required when no other
delimiter exists and ambiguity is possible.
Entering comments in Debug Tool commands

Debug Tool lets you insert descriptive comments into the command stream (except
within constants and other comments); however, the comment format depends on
the current programming language.
For C++ only: Comments in the form "//" are not processed by Debug Tool in
C++.
v For all supported programming languages, comments can be entered by:
– Enclosing the text in comment brackets "/*" and "*/". Comments can occur
anywhere a blank can occur between keywords, identifiers, and numeric
constants. Comments entered in this manner do not appear in the session log.
– Using the COMMENT command to insert commentary text in the session log.
Comments entered in this manner cannot contain embedded semicolons.
v When the current programming language setting is COBOL, comments can also
be entered by using an asterisk (*) in column 7. This is valid for file input only.

v For assembler and disassembly, comments can also be entered by using an
asterisk (*) in column 1.
Comments are most helpful in file input. For example, you can insert comments in
a USE file to explain and describe the actions of the commands.
Using constants in Debug Tool commands

Constants are entered as required by the current programming language setting.
Most constants defined for each of the supported HLLs are also supported by
Debug Tool.
Debug Tool allows the use of hexadecimal addresses in COBOL and PL/I.
The COBOL H constant is a fullword address value that can be specified in hex
using numeric-hex-literal format (hexadecimal characters only, delimited by either
double (") or single (') quotes and preceded by H). The value is right-justified and
padded on the left with zeros.
Note: The H constant can only be used where an address or POINTER variable can
be used. You can use this type of constant with the SET command. For
example, to assign a hexadecimal value of 124BF to the variable ptr, specify:
SET ptr TO H"124BF";
The COBOL hexadecimal notation for alphanumeric literals, such as MOVE

X'C1C2C3C4' TO NON-PTR-VAR, must be used for all other situations where a
hexadecimal value is needed.
The PL/I PX constant is a hexadecimal value, delimited by single quotes (') and
followed by PX. The value is right-justified and can be used in any context in
which a pointer value is allowed. For example, to display the contents at a given
address in hexadecimal format, specify:
LIST STORAGE ('20CD0'PX);
Related tasks
“Using constants in COBOL expressions” on page 194
Related references
“C and C++ expressions” on page 211
Getting online help for Debug Tool command syntax

You can get help with Debug Tool command syntax by either pressing PF1 or
entering a question mark (?) on the command line. This lists all Debug Tool
commands in the Log window.
To get a list of options for a command, enter a partial command followed by a

question mark.
For example, in full-screen mode, enter on the command line:

?
WINDOW ?
WINDOW CLOSE ?
WINDOW CLOSE SOURCE
Now reopen the Source window with:
Chapter 27. Entering Debug Tool commands 185

WINDOW OPEN SOURCE
to see the results.
The Debug Tool SYSTEM and TSO commands followed by ? do not invoke the syntax
help; instead the ? is sent to the host as part of the system command. The COMMENT
command followed by ? also does not invoke the syntax help.

Chapter 28. Debugging COBOL programs
Each version of the COBOL compiler provides enhancements that you can use to
develop COBOL programs. These enhancements can create different levels of
debugging capabilities. The topics below describe how to use these enhancements
when you debug your COBOL programs.
“Format for a COBOL source listing and debug file”

“Qualifying variables and changing the point of view in COBOL” on page 195
“Debug Tool evaluation of COBOL expressions” on page 193
“Using COBOL variables with Debug Tool” on page 189
“Using DBCS characters in COBOL” on page 191
“Using Debug Tool functions with COBOL” on page 195
“Debug Tool commands that resemble COBOL statements”
“%PATHCODE values for COBOL” on page 192
“Debugging VS COBOL II programs” on page 198
Format for a COBOL source listing and debug file

Debug Tool can use COBOL source listings that are in a PDS, a sequential file, or
an HFS file. The PDS or sequential file can be one of the following formats:
v Variable block.
v Fixed or fixed block with a record length of 133.
Debug Tool can use a separate debug file that is in a PDS, sequential file, or an
HFS file. The format for a PDS file or a sequential file must be fixed or fixed block
with a record length between 80 and 1024. You can create a separate debug file
when you specify the SEPARATE suboption of the TEST compiler option. This
suboption is available only on the following COBOL compilers:
Debug Tool commands that resemble COBOL statements

To test COBOL programs, you can write debugging commands that resemble
COBOL statements. Debug Tool provides an interpretive subset of COBOL
statements that closely resembles or duplicates the syntax and action of the
appropriate COBOL statements. You can therefore work with familiar commands
and insert into your source code program patches that you developed during your
debug session.
The table below shows the interpretive subset of COBOL statements recognized by
Debug Tool.
Command Description
CALL Subroutine call
COMPUTE Computational assignment (including expressions)
Declarations Declaration of session variables

Command Description
EVALUATE Multiway switch
IF Conditional execution
MOVE Noncomputational assignment
PERFORM Iterative looping
SET INDEX and POINTER assignment
This subset of commands is valid only when the current programming language is
COBOL.
Related references
COBOL command format

When you are entering commands directly at your terminal or workstation, the
format is free-form, because you can begin your commands in column 1 and
continue long commands using the appropriate method. You can continue on the
next line during your Debug Tool session by using an SBCS hyphen (-) as a
continuation character.
However, when you use a file as the source of command input, the format for your
commands is similar to the source format for the COBOL compiler. The first six
positions are ignored, and an SBCS hyphen in column 7 indicates continuation
from the previous line. You must start the command text in column 8 or later, and
end it in column 72.
The continuation line (with a hyphen in column 7) optionally has one or more
blanks following the hyphen, followed by the continuing characters. In the case of
the continuation of a literal string, an additional quote is required. When the token
being continued is not a literal string, blanks following the last nonblank character
on the previous line are ignored, as are blanks following the hyphen.
When Debug Tool copies commands to the log file, they are formatted according to
the rules above so that you can use the log file during subsequent Debug Tool
sessions.
Continuation is not allowed within a DBCS name or literal string. This restriction
applies to both interactive and command file input.
Related references
“COBOL compiler options in effect for Debug Tool commands”
“COBOL reserved keywords” on page 189
Enterprise COBOL for z/OS and OS/390 Language Reference
COBOL compiler options in effect for Debug Tool commands

While Debug Tool allows you to use many commands that are either similar or
equivalent to COBOL commands, Debug Tool does not necessarily interpret these
commands according to the compiler options you chose when compiling your
program. This is due to the fact that, in the Debug Tool environment, the following
settings are in effect:
DYNAM
NOCMPR2

NODBCS
NOWORD
NUMPROC(NOPFD)
QUOTE
TRUNC(BIN)
ZWB
Related references
COBOL reserved keywords

In addition to the subset of COBOL commands you can use while in Debug Tool,
there are reserved keywords used and recognized by COBOL that cannot be
abbreviated, used as a variable name, or used as any other type of identifier.
Related references
Using COBOL variables with Debug Tool

Debug Tool can process all variable types valid in the COBOL language.
In addition to being allowed to assign values to variables and display the values of
variables during your session, you can declare session variables to suit your testing
needs.
“Example: assigning values to COBOL variables”
Related tasks
“Accessing COBOL variables”
“Assigning values to COBOL variables”
“Declaring session variables in COBOL” on page 193
Accessing COBOL variables

Debug Tool obtains information about a program variable by name, using
information that is contained in the symbol table built by the compiler. You make
the symbol table available to Debug Tool by compiling with the TEST compiler
option.
Related tasks
Assigning values to COBOL variables

Debug Tool provides three COBOL-like commands to use when assigning values to
variables: COMPUTE, MOVE, and SET. Debug Tool assigns values according to COBOL
rules. See Debug Tool for z/OS Reference and Messages for tables that describe the
allowable values for the source and receiver of the COMPUTE, MOVE, and SET
commands.
Example: assigning values to COBOL variables

The examples for the COMPUTE, MOVE, and SET commands use the declarations
defined in the following COBOL program segment.
Chapter 28. Debugging COBOL programs 189

01 GRP.
02 ITM-1 OCCURS 3 TIMES INDEXED BY INX1.
03 ITM-2 PIC 9(3) OCCURS 3 TIMES INDEXED BY INX2.
01 B.
02 A PIC 9(10).
01 D.
02 C PIC 9(10).
01 F.
02 E PIC 9(10) OCCURS 5 TIMES.
77 AA PIC X(5) VALUE 'ABCDE'.
77 BB PIC X(5).
77 XX PIC 9(9) COMP.
77 ONE PIC 99 VALUE 1.
77 TWO PIC 99 VALUE 2.
77 PTR POINTER.
Assign to variable xx the result of the expression (a + e(1))/c * 2.

COMPUTE xx =(a + e(1))/c * 2;
You can also use table elements in such assignments as shown in the following
example:
COMPUTE itm−2(1,2)=(a + 1)/e(2);
The value assigned to a variable is always assigned to the storage for that variable.
In an optimized program, a variable can be temporarily assigned to a register, and
a new value assigned to that variable does not necessarily alter the value used by
the program.
Assign to the program variable c , found in structure d , the value of the program
variable a , found in structure b:
MOVE a OF b TO c OF d;
Note the qualification used in this example.
Assign the value of 123 to the first table element of itm-2:

MOVE 123 TO itm-2(1,1);
You can also use reference modification to assign values to variables as shown in
the following two examples:
MOVE aa(2:3)TO bb;
MOVE aa TO bb(1:4);
Assign the value 3 to inx1, the index to itm-1:

SET inx1 TO 3;
Assign the value of inx1 to inx2:

SET inx2 TO inx1;
Assign the value of an invalid address (nonnumeric 0) to ptr:

SET ptr TO NULL;
Assign the address of XX to ptr:

SET ptr TO ADDRESS OF XX;
Assigns the hexadecimal value of X'20000' to the pointer ptr:

SET ptr TO H’20000’;

Displaying values of COBOL variables
To display the values of variables, issue the LIST command. The LIST command
causes Debug Tool to log and display the current values (and names, if requested)
of variables. For example, if you want to display the variables aa, bb, one, and
their respective values at statement 52 of your program, issue the following
command:
AT 52 LIST TITLED (aa, bb, one); GO;
Debug Tool sets a breakpoint at statement 52 (AT), begins execution of the program
(GO), stops at statement 52, and displays the variable names (TITLED) and their
values.
Put commas between the variables when listing more than one. If you do not want
to display the variable names when issuing the LIST command, issue LIST
UNTITLED instead of LIST TITLED.
The value displayed for a variable is always the value that was saved in storage
for that variable. In an optimized program, a variable can be temporarily assigned
to a register, and the value shown for that variable might differ from the value
being used by the program.
If you use the LIST command to display a National variable, Debug Tool converts
the Unicode data to EBCDIC before displaying it. If the conversion results in
characters that cannot be displayed, enter the LIST %HEX() command to display the
unconverted Unicode data in hexadecimal format.
Using DBCS characters in COBOL

Programs you run with Debug Tool can contain variables and character strings
written using the double-byte character set (DBCS). Debug Tool also allows you to
issue commands containing DBCS variables and strings. For example, you can
display the value of a DBCS variable (LIST), assign it a new value, monitor it in
the monitor window (MONITOR), or search for it in a window (FIND).
To use DBCS with Debug Tool, enter:

SET DBCS ON;
If you are debugging in full-screen mode and your terminal is not DBCS capable,
the SET DBCS ON is not available.
The DBCS default for COBOL is OFF.
The DBCS syntax and continuation rules you must follow to use DBCS variables in
Debug Tool commands are the same as those for the COBOL language.
For COBOL you must type a DBCS literal, such as G, in front of a DBCS value in a
Monitor or Data pop-up window if you want to update the value.
Related references

%PATHCODE values for COBOL
The table below shows the possible values for the Debug Tool variable %PATHCODE
when the current programming language is COBOL.
–1 Debug Tool is not in control as the result of a path or attention situation.

0 Attention function (not ATTENTION condition).
1 A block has been entered.
2 A block is about to be exited.
3 Control has reached a label coded in the program (a paragraph name or section
name).
4 Control is being transferred as a result of a CALL or INVOKE. The invoked routine’s
parameters, if any, have been prepared.
5 Control is returning from a CALL or INVOKE. If GPR 15 contains a return code, it
has already been stored.
6 Some logic contained by an inline PERFORM is about to be executed. (Out-of-line
PERFORM ranges must start with a paragraph or section name, and are identified
by %PATHCODE = 3.)
7 The logic following an IF...THEN is about to be executed.
8 The logic following an ELSE is about to be executed.
9 The logic following a WHEN within an EVALUATE is about to be executed.
10 The logic following a WHEN OTHER within an EVALUATE is about to be executed.
11 The logic following a WHEN within a SEARCH is about to be executed.
12 The logic following an AT END within a SEARCH is about to be executed.
13 The logic following the end of one of the following structures is about to be
executed:
v An IF statement (with or without an ELSE clause)
v An EVALUATE or SEARCH
v A PERFORM
14 Control is about to return from a declarative procedure such as USE AFTER ERROR.
(Declarative procedures must start with section names, and are identified by
%PATHCODE = 3.)
15 The logic associated with one of the following phrases is about to be run:
v [NOT] ON SIZE ERROR
v [NOT] ON EXCEPTION
v [NOT] ON OVERFLOW
v [NOT] AT END (other than SEARCH AT END)
v [NOT] AT END-OF-PAGE
v [NOT] INVALID KEY
16 The logic following the end of a statement containing one of the following
phrases is about to be run:
v [NOT] ON SIZE ERROR
v [NOT] ON EXCEPTION
v [NOT] ON OVERFLOW
v [NOT] AT END (other than SEARCH AT END)
v [NOT] AT END-OF-PAGE
v [NOT] INVALID KEY.
Note: Values in the range 3–16 can be assigned to %PATHCODE only if your program
was compiled with an option supporting path hooks.

Related tasks
Declaring session variables in COBOL

You might want to declare session variables during your Debug Tool session. The
relevant variable assignment commands are similar to their counterparts in the
COBOL language. The rules used for forming variable names in COBOL also apply
to the declaration of session variables during a Debug Tool session.
The following declarations are for a string variable, a decimal variable, a pointer
variable, and a floating-point variable. To declare a string named description,
enter:
77 description PIC X(25)
To declare a variable named numbers, enter:

77 numbers PIC 9(4) COMP
To declare a pointer variable named pinkie, enter:

77 pinkie POINTER
To declare a floating-point variable named shortfp, enter:

77 shortfp COMP-1
Session variables remain in effect for the entire debug session.
Related tasks
“Using session variables across different languages” on page 272
Related references
Debug Tool evaluation of COBOL expressions

Debug Tool interprets COBOL expressions according to COBOL rules. Some
restrictions do apply. For example, the following restrictions apply when arithmetic
expressions are specified:
v Floating-point operands are not supported (COMP-1, COMP-2, external floating
point, floating-point literals).
v Only integer exponents are supported.
v Intrinsic functions are not supported.
v Windowed date-field operands are not supported in arithmetic expressions in
combination with any other operands.
When arithmetic expressions are used in relation conditions, both comparand

attributes are considered. Relation conditions follow the IF rules rather than the
EVALUATE rules.
Only simple relation conditions are supported. Sign conditions, class conditions,
condition-name conditions, switch-status conditions, complex conditions, and
abbreviated conditions are not supported. When either of the comparands in a
relation condition is stated in the form of an arithmetic expression (using operators
such as plus and minus), the restriction concerning floating-point operands applies
to both comparands. See Debug Tool for z/OS Reference and Messages for a table that

describes the allowable comparisons for the IF command. See the Enterprise
COBOL for z/OS and OS/390 Programming Guide for a description of the COBOL
rules of comparison.
Windowed date fields are not supported in relation conditions.
Related tasks
“Displaying the results of COBOL expression evaluation”
“Using constants in COBOL expressions”
Enterprise COBOL for z/OS and OS/390 Programming Guide
Related references
Displaying the results of COBOL expression evaluation

Use the LIST command to display the results of your expressions. For example, to
evaluate the expression and displays the result in the Log window, enter:
LIST a + (a − 10) + one;
You can also use structure elements in expressions. If e is an array, the following
two examples are valid:
LIST a + e(1) / c * two;
LIST xx / e(two + 3);
Conditions for expression evaluation are the same ones that exist for program
statements.
Related references
“COBOL compiler options in effect for Debug Tool commands” on page 188
Using constants in COBOL expressions

During your Debug Tool session you can use expressions that use string constants
as one operand, as well as expressions that include variable names or number
constants as single operands. All COBOL string constant types discussed in the
Enterprise COBOL for z/OS and OS/390 Language Reference are valid in Debug Tool,
with the following restrictions:
v The following COBOL figurative constants are supported:
ZERO, ZEROS, ZEROES
SPACE, SPACES
HIGH-VALUE, HIGH-VALUES
LOW-VALUE, LOW-VALUES
QUOTE, QUOTES
NULL, NULLS
Any of the above preceded by ALL
Symbolic-character (whether or not preceded by ALL).
v An N literal, which starts with N" or N’, is always treated as a national literal.
Additionally, Debug Tool allows the use of a hexadecimal constant that represents
an address. This H-constant is a fullword value that can be specified in hex using
numeric-hex-literal format (hexadecimal characters only, delimited by either
quotation marks (") or apostrophes (') and preceded by H). The value is
right-justified and padded on the left with zeros. The following example:
LIST STORAGE (H'20cd0');

displays the contents at a given address in hexadecimal format. You can use this
type of constant with the SET command. The following example:
SET ptr TO H'124bf';
assigns a hexadecimal value of 124bf to the variable ptr.
Using Debug Tool functions with COBOL

Debug Tool provides certain functions you can use to find out more information
about program variables and storage.
Using %HEX with COBOL

You can use the %HEX function with the LIST command to display the hexadecimal
value of an operand. For example, to display the external representation of the
packed decimal pvar3, defined as PIC 9(9), from 1234 as its hexadecimal (or
internal) equivalent, enter:
LIST %HEX (pvar3);
The Log window displays the hexadecimal string X’000001234’.
Using the %STORAGE function with COBOL

This Debug Tool function allows you to reference storage by address and length.
By using the %STORAGE function as the reference when setting a CHANGE breakpoint,
you can watch specific areas of storage for changes. For example, to monitor eight
bytes of storage at the hex address 22222 for changes, enter:
AT CHANGE %STORAGE (H'00022222', 8)
LIST 'Storage has changed at Hex address 22222'
Qualifying variables and changing the point of view in COBOL

Qualification is a method of specifying an object through the use of qualifiers, and
changing the point of view from one block to another so you can manipulate data
not known to the currently executing block. For example, the assignment MOVE 5
TO x; does not appear to be difficult for Debug Tool to process. However, you
might have more than one variable named x. You must tell Debug Tool which
variable x to assign the value of five.
You can use qualification to specify to what compile unit or block a particular
variable belongs. When Debug Tool is invoked, there is a default qualification
established for the currently executing block; it is implicitly qualified. Thus, you
must explicitly qualify your references to all statement numbers and variable
names in any other block. It is necessary to do this when you are testing a compile
unit that calls one or more blocks or compile units. You might need to specify
what block contains a particular statement number or variable name when issuing
commands.
Qualifying variables in COBOL

Qualifiers are combinations of load modules, compile units, blocks, section names,
or paragraph names punctuated by a combination of greater-than signs (>), colons,
and the COBOL data qualification notation, OF or IN, that precede referenced
statement numbers or variable names.

When qualifying objects on a block level, use only the COBOL form of data
qualification. If data names are unique, or defined as GLOBAL, they do not need to
be qualified to the block level.
The following is a fully qualified object:

load_name::>cu_name:>block_name:>object;
If required, load_name is the name of the load module. It is required only when the
program consists of multiple load modules and you want to change the
qualification to other than the current load module. load_name can also be the
Debug Tool variable %LOAD.
If required, cu_name is the name of the compile unit. The cu_name must be the fully
qualified compile unit name. It is required only when you want to change the
qualification to other than the currently qualified compile unit. It can be the Debug
Tool variable %CU.
If required, block_name is the name of the block. The block_name is required only
when you want to change the qualification to other than the currently qualified
block. It can be the Debug Tool variable %BLOCK. Remember to enclose the block
name in double (") or single (') quotes if case sensitive. If the name is not inside
quotes, Debug Tool converts the name to upper case.
Below are two similar COBOL programs (blocks).

MAIN
.
.
.
01 VAR1.
02 VAR2.
O3 VAR3 PIC XX.
01 VAR4 PIC 99..
****************MOVE commands entered here****************

SUBPROG
.
.
.
01 VAR1.
02 VAR2.
O3 VAR3 PIC XX.
01 VAR4 PIC 99.
01 VAR5 PIC 99.
****************LIST commands entered here****************
You can distinguish between the main and subprog blocks using qualification. If
you enter the following MOVE commands when main is the currently executing
block:
MOVE 8 TO var4;
MOVE 9 TO subprog:>var4;
MOVE 'A' TO var3 OF var2 OF var1;
MOVE 'B' TO subprog:>var3 OF var2 OF var1;
and the following LIST commands when subprog is the currently executing block:
LIST TITLED var4;
LIST TITLED main:>var4;
LIST TITLED var3 OF var2 OF var1;
LIST TITLED main:>var3 OF var2 OF var1;
each LIST command results in the following output (without the commentary) in
your Log window:

VAR4 = 9; /* var4 with no qualification refers to a variable */
/* in the currently executing block (subprog). */
/* Therefore, the LIST command displays the value of 9.*/
MAIN:>VAR4 = 8 /* var4 is qualified to main. */

/* Therefore, the LIST command displays 8, */
/* the value of the variable declared in main. */
VAR3 OF VAR2 OF VAR1 = 'B';

/* In this example, although the data qualification */
/* of var3 is OF var2 OF var1, the */
/* program qualification defaults to the currently */
/* executing block and the LIST command displays */
/* 'B', the value declared in subprog. */
VAR3 OF VAR2 OF VAR1 = 'A'

/* var3 is again qualified to var2 OF var1 */
/* but further qualified to main. */
/* Therefore, the LIST command displays */
/* 'A', the value declared in main. */
The above method of qualifying variables is necessary for command files.
Changing the point of view in COBOL

The point of view is usually the currently executing block. You can also get to
inaccessible data by changing the point of view using the SET QUALIFY command.
The SET keyword is optional. For example, if the point of view (current execution)
is in main and you want to issue several commands using variables declared in
subprog, you can change the point of view by issuing the following:
QUALIFY BLOCK subprog;
You can then issue commands using the variables declared in subprog without
using qualifiers. Debug Tool does not see the variables declared in procedure main.
For example, the following assignment commands are valid with the subprog point
of view:
MOVE 10 TO var5;
However, if you want to display the value of a variable in main while the point of
view is still in subprog, you must use a qualifier, as shown in the following
example:
LIST (main:>var-name);
The above method of changing the point of view is necessary for command files.
Considerations when debugging a COBOL class

The block structure of a COBOL class created with Enterprise COBOL for z/OS
and OS/390, Version 3 Release 1 or later, is different from the block structure of a
COBOL program. The block structure of a COBOL class has the following
differences:
v The CLASS is a compile unit.
v The FACTORY paragraph is a block.
v The OBJECT paragraph is a block.
v Each method is a block.
A method belongs to either the FACTORY block or the OBJECT block. A fully
qualified block name for a method in the FACTORY paragraph is:
class-name:>FACTORY:>method-name

A fully qualified block name for a method in the OBJECT paragraph is:
class-name:>OBJECT:>method-name
When you are at a breakpoint in a method, the currently qualified block is the
method. If you enter the LIST TITLED command with no parameters, Debug Tool
lists all of the data items associated with the method. To list all of the data items in
a FACTORY or OBJECT, do the following steps:
1. Enter the QUALIFY command to set the point of view to the FACTORY or
OBJECT.
2. Enter the LIST TITLED command.
For example, to list all of the object instance data items for a class called
ACCOUNT, enter the following command:
QUALIFY BLOCK ACCOUNT:>OBJECT; LIST TITLED;
Debugging VS COBOL II programs

There are limitations to debugging VS COBOL II programs. Language Environment
callable services, including CEETEST, are not available. However, you must use the
Language Environment run time.
Debug Tool does not get control of the program at breakpoints that you set by the
following commands:
v AT PATH
v AT CALL
v AT ENTRY
v AT EXIT
However, if you set the breakpoint with an AT CALL command that calls a non-VS
COBOL II program, Debug Tool does get control of the program. Use the AT ENTRY
*, AT EXIT *, AT GLOBAL ENTRY, and AT GLOBAL EXIT commands to set breakpoints
that Debug Tool can use to get control of the program.
Breakpoints that you set at entry points and exit statements have no statement
associated with them. Therefore, they are triggered only at the compile unit level.
When they are triggered, the current view of the listing moves to the top and no
statement is highlighted. Breakpoints that you set at entry points and exit
statements are ignored by the STEP command.
If you are debugging your VS COBOL II program in remote debug mode, use the
same TEST run-time options as for any COBOL program.
Finding the listing of a VS COBOL II program

The VS COBOL II compiler does not place the name of the listing data set in the
object (load module). Debug Tool tries to find the listing data set in the following
location: userid.CUName.LIST. If the listing is in a PDS, direct Debug Tool to the
location of the PDF in one of the following ways:
v In full-screen mode, enter the following command:
SET DEFAULT LISTINGS my.listing.pds
v In remote debug mode, add the -qremote option to the command that starts the
daemon:
idebug -qdaemon -quiport=8000 -qlang=cobol -qremotesource=my.listing.pds

Chapter 29. Debugging PL/I programs
The topics below describe how to use Debug Tool to debug your PL/I programs.
Related concepts
“Debug Tool evaluation of PL/I expressions” on page 204
Related tasks
Chapter 29, “Debugging PL/I programs”
“Accessing PL/I program variables” on page 202
Related references
“Debug Tool subset of PL/I commands”
“Supported PL/I built-in functions” on page 204
Debug Tool subset of PL/I commands

The table below lists the Debug Tool interpretive subset of PL/I commands. This
subset is a list of commands recognized by Debug Tool that either closely resemble
or duplicate the syntax and action of the corresponding PL/I command. This
subset of commands is valid only when the current programming language is
PL/I.
Command Description
Assignment Scalar and vector assignment
BEGIN Composite command grouping
CALL Debug Tool procedure call
DECLARE or DCL Declaration of session variables
DO Iterative looping and composite command grouping
IF Conditional execution
ON Define an exception handler
SELECT Conditional execution
PL/I language statements

PL/I statements are entered as Debug Tool commands. Debug Tool makes it
possible to issue commands in a manner similar to each language.
The following types of Debug Tool commands will support the syntax of the PL/I
statements:
Expression
This command evaluates an expression.
Block BEGIN/END, DO/END, PROCEDURE/END
These commands provide a means of grouping any number of Debug Tool
commands into ″one″ command.

Conditional
IF/THEN, SELECT/WHEN/END
These commands evaluate an expression and control the flow of execution
of Debug Tool commands according to the resulting value.
Declaration
DECLARE or DCL
These commands provide a means for declaring session variables.
Looping
DO/WHILE/UNTIL/END
These commands provide a means to program an iterative or conditional
loop as a Debug Tool command.
Transfer of Control
GOTO, ON
These commands provide a means to unconditionally alter the flow of
execution of a group of commands.
The table below shows the commands that are new or changed for this release of
Debug Tool when the current programming language is PL/I.
Command Description or changes

ANALYZE Displays the PL/I style of evaluating an expression, and the
precision and scale of the final and intermediate results.
ON Performs as the AT OCCURRENCE command except it takes PL/I
conditions as operands.
BEGIN BEGIN/END blocks of logic.
DECLARE Session variables can now include COMPLEX (CPLX), POINTER,
BIT, BASED, ALIGNED, UNALIGNED, etc. Arrays can be declared
to have upper and lower bounds. Variables can have precisions
and scales.
DO The three forms of DO are added; one is an extension of C’s do.
1. DO; command(s); END;
2. DO WHILE | UNTIL expression; command(s); END;
3. DO reference=specifications; command(s); END;
IF The IF / ELSE does not require the ENDIF.
SELECT The SELECT / WHEN / OTHERWISE / END programming structure
is added.
%PATHCODE values for PL/I

when the current programming language is PL/I.
0 An attention interrupt occurred.

3 Control has reached a label constant.
4 Control is being sent somewhere else as the result of a CALL or a function
reference.

5 Control is returning from a CALL invocation or a function reference. Register 15, if
it contains a return code, has not yet been stored.
6 Some logic contained in a complex DO statement is about to be executed.
7 The logic following an IF..THEN is about to be executed.
8 The logic following an ELSE is about to be executed.
9 The logic following a WHEN within a select-group is about to be executed.
10 The logic following an OTHERWISE within a select-group is about to be executed.
PL/I conditions and condition handling

All PL/I conditions are recognized by Debug Tool. They are used with the AT
OCCURRENCE and ON commands.
When an OCCURRENCE breakpoint is triggered, the Debug Tool %CONDITION variable

holds the following values:
Triggered condition %CONDITION value

AREA AREA
ATTENTION CEE35J
COND ( CC#1 ) CONDITION
CONVERSION CONVERSION
ENDFILE ( MF ) ENDFILE
ENDPAGE ( MF ) ENDPAGE
ERROR ERROR
FINISH CEE066
FOFL CEE348
KEY ( MF ) KEY
NAME ( MF ) NAME
OVERFLOW CEE34C
PENDING ( MF ) PENDING
RECORD ( MF ) RECORD
SIZE SIZE
STRG STRINGRANGE
STRINGSIZE STRINGSIZE
SUBRG SUBSCRIPTRANGE
TRANSMIT ( MF ) TRANSMIT
UNDEFINEDFILE ( MF ) UNDEFINEDFILE
UNDERFLOW CEE34D
ZERODIVIDE CEE349
Note: The Debug Tool condition ALLOCATE raises the ON ALLOCATE condition when a
PL/I program encounters an ALLOCATE statement for a controlled variable.
These PL/I language-oriented commands are only a subset of all the commands
that are supported by Debug Tool.
Chapter 29. Debugging PL/I programs 201

Entering commands in PL/I DBCS freeform format
Statements can be entered in PL/I’s DBCS freeform. This means that statements
can freely use shift codes as long as the statement is not ambiguous.
This will change the description or characteristics of LIST NAMES in that:

LIST NAMES db<.c.skk.w>ord
will search for

<.D.B.C.Skk.W.O.R.D>
This will result in different behavior depending upon the language. For example,
the following will find a<kk>b in C and <.Akk.b> in PL/I.
LIST NAMES a<kk>*
where <kk> is shiftout-kanji-shiftin.
Freeform will be added to the parser and will be in effect while the current
programming language is PL/I.
Initializing Debug Tool when TEST(ERROR, ...) run-time option is in

effect
With the run-time option, TEST(ERROR, ...) only the following can initialize
Debug Tool:
v The ERROR condition
v Attention recognition
v CALL PLITEST
v CALL CEETEST
Debug Tool enhancements to LIST STORAGE PL/I command

LIST STORAGE address has been enhanced so that the address can be a POINTER, a
Px constant, or the ADDR built-in function.
PL/I support for Debug Tool session variables

PL/I will support all Debug Tool scalar session variables. In addition, arrays and
structures can be declared.
Related tasks
Accessing PL/I program variables

Debug Tool obtains information about a program variable by name using
information that is contained in the symbol table built by the compiler. The symbol
table is made available to the compiler by compiling with TEST(SYM).
Debug Tool uses the symbol table to obtain information about program variables,
controlled variables, automatic variables, and program control constants such as
file and entry constants and also CONDITION condition names. Based variables,
controlled variables, automatic variables and parameters can be used with Debug
Tool only after storage has been allocated for them in the program. An exception to
this is DESCRIBE ATTRIBUTES, which can be used to display attributes of a variable.

Variable that are based on:
v An OFFSET variable,
v An expression, or
v A pointer that either is based or defined, a parameter, or member of either an
array or a structure
must be explicitly qualified when used in expressions. For example, assume you
made the following declaration:
DECLARE P1 POINTER;
DECLARE P2 POINTER;
DECLARE DX FIXED BIN(31) BASED(P2);
You would not be able to reference the variable directly by name. You can only
reference it by specifying either:
P2->DX
or
P1->P2->DX
The following types of program variables cannot be used with Debug Tool:
v iSUB defined variables
v Variables defined:
– On a controlled variable
– On an array with one or more adjustable bounds
– With a POSITION attributed that specifies something other than a constant
v Variables that are members of a based structure declared with the REFER options.
Related tasks
Accessing PL/I structures

You cannot reference elements of arrays of structures. For example, suppose a
structure called PAYROLL is declared as follows:
Declare 1 Payroll(100),
2 Name,
4 Last char(20),
4 First char(15),
2 Hours,
4 Regular Fixed Decimal(5,2),
4 Overtime Fixed Decimal(5,2);
Given the way PAYROLL is declared, the following examples of commands are
valid in Debug Tool:
LIST ( PAYROLL(1).NAME.LAST, PAYROLL(1).HOURS.REGULAR );
LIST ( ADDR ( PAYROLL) ) ;
LIST STORAGE ( PAYROLL.HOURS, 128 );
Given the way PAYROLL is declared, the following examples of commands are
invalid in Debug Tool:
LIST ( PAYROLL(1) );
LIST (ADDR ( PAYROLL(5) ) );
LIST STORAGE ( PAYROLL(15).HOURS, 128 ) );

Debug Tool evaluation of PL/I expressions
When the current programming language is PL/I, expression interpretation is
similar to that defined in the PL/I language, except for the PL/I language elements
not supported in Debug Tool.
The Debug Tool expression is similar to the PL/I expression. If the source of the
command is a variable-length record source (such as your terminal) and if the
expression extends across more than one line, a continuation character (an SBCS
hyphen) must be specified at the end of all but the last line.
All PL/I constant types are supported, plus the Debug Tool PX constant.
Related references
“Unsupported PL/I language elements” on page 205
Supported PL/I built-in functions

Debug Tool supports the following PL/I built-in functions:
ABS CSTG2 LOG1 REAL

ACOS CURRENTSTORAGE LOG2 REPEAT
ADDR DATAFIELD LOW SAMEKEY
ALL DATE MPSTR SIN
ALLOCATION DATETIME NULL SIND
ANY DIM OFFSET SINH
ASIN EMPTY ONCHAR SQRT
ATAN ENTRYADDR ONCODE STATUS
ATAND ERF ONCOUNT STORAGE
ATANH ERFC ONFILE STRING
BINARYVALUE EXP ONKEY SUBSTR
BINVALUE1 GRAPHIC ONLOC SYSNULL
BIT HBOUND ONSOURCE TAN
BOOL HEX PLIRETV TAND
CHAR HIGH POINTER TANH
COMPLETION IMAG POINTERADD TIME
COS LBOUND POINTERVALUE TRANSLATE
COSD LENGTH PTRADD3 UNSPEC
COSH LINENO PTRVALUE4 VERIFY
COUNT LOG
Notes:
1. Abbreviation for BINARYVALUE
2. Abbreviation for CURRENTSTORAGE
3. Abbreviation for POINTERADD
4. Abbreviation for POINTERVALUE
Related tasks
“Using SET WARNING PL/I command with built-in functions”
Using SET WARNING PL/I command with built-in functions

Certain checks are performed when the Debug Tool SET WARNING command setting
is ON and a built-in function (BIF) is evaluated:
v Division by zero
v The remainder (%) operator for a zero value in the second operand

v Array subscript out of bounds for defined arrays
v Bit shifting by a number that is negative or greater than 32
v On a built-in function call for an incorrect number of parameters or for
parameter type mismatches
v On a built-in function call for differing linkage calling conventions
These checks are restrictions that can be removed by issuing SET WARNING OFF.
Unsupported PL/I language elements

The following list summarizes PL/I functions not available:
v Use of iSUB
v Interactive declaration or use of user-defined functions
v All preprocessor directives
v Multiple assignments
v BY NAME assignments
v LIKE attribute
v FILE, PICTURE, and ENTRY data attributes
v All I/O statements, including DISPLAY
v INIT attribute
v Structures with the built-in functions CSTG, CURRENTSTORAGE, and STORAGE
v The repetition factor is not supported for string constants
v GRAPHIC string constants are not supported for expressions involving other data
types
v Declarations cannot be made as sub-commands (for example in a BEGIN, DO, or
SELECT command group)

Chapter 30. Debugging C and C++ programs
The topics below describe how to use Debug Tool to debug your C and C++
programs.
“Example: referencing variables and setting breakpoints in C and C++ blocks” on

page 221
Related concepts
“Debug Tool evaluation of C and C++ expressions” on page 215
“Scope of objects in C and C++” on page 218
“Blocks and block identifiers for C” on page 220
“Blocks and block identifiers for C++” on page 220
“Monitoring storage in C++” on page 228
Related tasks
“Using C and C++ variables with Debug Tool” on page 208
“Declaring session variables with C and C++” on page 210
“Calling C and C++ functions from Debug Tool” on page 212
“Intercepting files when debugging C and C++ programs” on page 216
“Displaying environmental information” on page 222
“Stepping through C++ programs” on page 225
“Setting breakpoints in C++” on page 225
“Examining C++ objects” on page 227
“Qualifying variables in C and C++” on page 223
Related references
“Debug Tool commands that resemble C and C++ commands”
“%PATHCODE values for C and C++” on page 209
“C reserved keywords” on page 213
“C operators and operands” on page 213
“Language Environment conditions and their C and C++ equivalents” on page 214
Debug Tool commands that resemble C and C++ commands

Debug Tool’s command language is a subset of C and C++ commands and has the
same syntactical requirements. Debug Tool allows you to work in a language you
are familiar with so learning a new set of commands is not necessary.
The table below shows the interpretive subset of C and C++ commands recognized
by Debug Tool.
Command Description
block ({}) Composite command grouping
break Termination of loops or switch commands
declarations Declaration of session variables
do/while Iterative looping
expression Any C expression except the conditional (?) operator

Command Description
for Iterative looping
if Conditional execution
switch Conditional execution
This subset of commands is valid only when the current programming language is
C or C++.
In addition to the subset of C and C++ commands that you can use is a list of
reserved keywords used and recognized by C and C++ that you cannot abbreviate,
use as variable names, or use as any other type of identifier.
Related references
“C reserved keywords” on page 213
Using C and C++ variables with Debug Tool

Debug Tool can process all program variables that are valid in C or C++. You can
assign and display the values of variables during your session. You can also
declare session variables with the recognized C declarations to suit your testing
needs.
Related tasks
“Accessing C and C++ program variables”
“Displaying values of C and C++ variables or expressions”
“Assigning values to C and C++ variables” on page 209
Accessing C and C++ program variables

Debug Tool obtains information about a program variable by name using the
symbol table built by the compiler. If you specify TEST(SYM) at compile time, the
compiler builds a symbol table that allows you to reference any variable in the
program.
Note: There are no suboptions for C++. Symbol information is generated by

default when the TEST compiler option is specified.
Related tasks
Displaying values of C and C++ variables or expressions

To display the values of variables or expressions, use the LIST command. The LIST
command causes Debug Tool to log and display the current values (and names, if
requested) of variables, including the evaluated results of expressions.
Suppose you want to display the program variables X, row[X], and col[X], and
their values at line 25. If you issue the following command:
AT 25 LIST ( X, row[X], col[X] ); GO;
Debug Tool sets a breakpoint at line 25 (AT), begins execution of the program (GO),
stops at line 25, and displays the variable names and their values.

If you want to see the result of their addition, enter:
AT 25 LIST ( X + row[X] + col[X] ); GO;
Debug Tool sets a breakpoint at line 25 (AT), begins execution of the program (GO),
stops at line 25, and displays the result of the expression.
Put commas between the variables when listing more than one. If you do not want
to display the variable names when issuing the LIST command, enter LIST
UNTITLED.
You can also list variables with the printf function call as follows:
printf ("X=%d, row=%d, col=%d\n", X, row[X], col[X]);
The output from printf, however, does not appear in the Log window and is not
recorded in the log file unless you SET INTERCEPT ON FILE stdout.
Assigning values to C and C++ variables

To assign a value to a C and C++ variable, you use an assignment expression.
Assignment expressions assign a value to the left operand. The left operand must
be a modifiable lvalue. An lvalue is an expression representing a data object that
can be examined and altered.
C contains two types of assignment operators: simple and compound. A simple

assignment operator gives the value of the right operand to the left operand.
Note: Only the assignment operators that work for C will work for C++, that is,
there is no support for overloaded operators.
The following example demonstrates how to assign the value of number to the
member employee of the structure payroll:
payroll.employee = number;
Compound assignment operators perform an operation on both operands and give

the result of that operation to the left operand. For example, this expression gives
the value of index plus 2 to the variable index:
index += 2
Debug Tool supports all C operators except the tenary operator, as well as any
other full C language assignments and function calls to user or C library functions.
Related tasks
“Calling C and C++ functions from Debug Tool” on page 212
%PATHCODE values for C and C++

when the current programming language is C and C++.
–1 Debug Tool is not in control as the result of a path or attention situation.

0 Attention function (not ATTENTION condition).
3 Control has reached a user label.
Chapter 30. Debugging C and C++ programs 209

4 Control is being transferred as a result of a function reference. The invoked
routine’s parameters, if any, have been prepared.
5 Control is returning from a function reference. Any return code contained in
register 15 has not yet been stored.
6 Some logic contained by a conditional do/while, for, or while statement is about
to be executed. This can be a single or Null statement and not a block statement.
7 The logic following an if(...) is about to be executed.
8 The logic following an else is about to be executed.
9 The logic following a case within an switch is about to be executed.
10 The logic following a default within a switch is about to be executed.
13 The logic following the end of a switch, do, while, if(...), or for is about to be
executed.
17 A goto, break, continue, or return is about to be executed.
Values in the range 3–17 can only be assigned to %PATHCODE if your program was
compiled with an option supporting path hooks.
Declaring session variables with C and C++

You might want to declare session variables for use during the course of your
session. You cannot initialize session variables in declarations. However, you can
use an assignment statement or function call to initialize a session variable.
As in C, keywords can be specified in any order. Variable names up to 255

characters in length can be used. Identifiers are case-sensitive, but if you want to
use the session variable when the current programming language changes from C
to another HLL, the variable must have an uppercase name and compatible
attributes.
To declare a hexadecimal floating-point variable called maximum, enter the following

C declaration:
double maximum;
You can only declare scalars, arrays of scalars, structures, and unions in Debug
Tool (pointers for the above are allowed as well).
If you declare a session variable with the same name as a programming variable,
the session variable hides the programming variable. To reference the
programming variable, you must qualify it. For example:
main:>x for the program variable x
x for the session variable x
Session variables remain in effect for the entire debug session, unless they are
cleared using the CLEAR command.
Related tasks
“Qualifying variables and changing the point of view in C and C++” on page 222

C and C++ expressions
Debug Tool allows evaluation of expressions in your test program. All expressions
available in C and C++ are also available within Debug Tool except for the
conditional expression (? :). That is, all operators such as +, −, %:, and += are fully
supported with the exception of the conditional operator.
C and C++ language expressions are arranged in the following groups based on
the operators they contain and how you use them:
Primary expression
Unary expression
Binary expression
Conditional expression
Assignment expression
Comma expression
lvalue
Constant
An lvalue is an expression representing a data object that can be examined and

altered. For a more detailed description of expressions and operators, see the C
and C++ Program Guides.
The semantics for C and C++ operators are the same as in a compiled C or C++
program. Operands can be a mixture of constants (integer, floating-point,
character, string, and enumeration), C and C++ variables, Debug Tool variables,
or session variables declared during a Debug Tool session. Language constants are
specified as described in the C and C++ Language Reference publications.
The Debug Tool command DESCRIBE ATTRIBUTES can be used to display the
resultant type of an expression, without actually evaluating the expression.
The C and C++ language does not specify the order of evaluation for function call
arguments. Consequently, it is possible for an expression to have a different
execution sequence in compiled code than within Debug Tool. For example, if you
enter the following in an interactive session:
int x;
int y;
x = y = 1;
printf ("%d %d %d%" x, y, x=y=0);
the results can differ from results produced by the same statements located in a C
or C++ program segment. Any expression containing behavior undefined by ANSI
standards can produce different results when evaluated by Debug Tool than when
evaluated by the compiler.
The following examples show you various ways Debug Tool supports the use of
expressions in your programs:
v Debug Tool assigns 12 to a (the result of the printf()) function call, as in:
a = (1,2/3,a++,b++,printf("hello world\n"));
v Debug Tool supports structure and array referencing and pointer dereferencing,
as in:
league[num].team[1].player[1]++;
league[num].team[1].total += 1;
++(*pleague);

v Simple and compound assignment is supported, as in:
v.x = 3;
a = b = c = d = 0;
*(pointer++) −= 1;
v C and C++ language constants in expressions can be used, as in:
pointer_to_c = "abcdef" + 0x2;
*pointer_to_long = 3521L = 0x69a1;
float_val = 3e−11 + 6.6E−10;
char_val = '7';
v The comma expression can be used, as in:
intensity <<= 1, shade * increment, rotate(direction);
alpha = (y>>3, omega % 4);
v Debug Tool performs all implicit and explicit C conversions when necessary.
Conversion to long double is performed in:
long_double_val = unsigned_short_val;
long_double_val = (long double) 3;
Related references
Calling C and C++ functions from Debug Tool

You can perform calls to user and C library functions within Debug Tool.
You can make calls to C library functions at any time. In addition, you can use the
C library variables stdin, stdout, stderr, __amrc, and errno in expressions
including function calls.
The library function ctdli cannot be called unless it is referenced in a compile unit
in the program, either main or a function linked to main.
Calls to user functions can be made, provided Debug Tool is able to locate an
appropriate definition for the function within the symbol information in the user
program. These definitions are created when the program is compiled with
TEST(SYM) for C or TEST for C++.
Debug Tool performs parameter conversions and parameter-mismatch checking

where possible. Parameter checking is performed if:
v The function is a library function
v A prototype for the function exists in the current compile unit
v Debug Tool is able to locate a prototype for the function in another compile unit,
or the function itself was compiled with TEST(SYM) for C or with TEST for C++.
You can turn off this checking by specifying SET WARNING OFF.
Calls can be made to any user functions that have linkage supported by the C or
C++ compiler. However, for C++ calls made to any user function, the function
must be declared as:
extern "C"
For example, use this declaration if you want to debug an application signal
handler. When a condition occurs, control passes to Debug Tool which then passes
control to the signal handler.

Debug Tool attempts linkage checking, and does not perform the function call if it
determines there is a linkage mismatch. A linkage mismatch occurs when the target
program has one linkage but the source program believes it has a different linkage.
It is important to note the following regarding function calls:

v The evaluation order of function arguments can vary between the C and C++
program and Debug Tool. No discernible difference exists if the evaluation of
arguments does not have side effects.
v Debug Tool knows about the function return value, and all the necessary
conversions are performed when the return value is used in an expression.
Related tasks
Related references
C reserved keywords
The table below lists all keywords reserved by the C language. When the current
programming language is C or C++, these keywords cannot be abbreviated, used
as variable names, or used as any other type of identifiers.
auto else long switch

break enum register typedef
case extern return union
char float short unsigned
const for signed void
continue goto sizeof volatile
default if static while
do int struct _Packed
double
C operators and operands

The table below lists the C language operators in order of precedence and shows
the direction of associativity for each operator. The primary operators have the
highest precedence. The comma operator has the lowest precedence. Operators in
the same group have the same precedence.

Precedence level Associativity Operators
Primary left to right () [ ] . –>
Unary right to left ++ -- - + ! ~ &
* (typename) sizeof
Multiplicative left to right * / %
Additive left to right + −
Bitwise shift left to right << >>
Relational left to right < > <= >=
Equality left to right ++ !=
Bitwise logical AND left to right &
Bitwise exclusive OR left to right ^ or ¬
Bitwise inclusive OR left to right |
Logical AND left to right &&
Logical OR left to right ||
Assignment right to left = += −= *= /=
<<= >>= %= &= ^= |=
Comma left to right ,
Language Environment conditions and their C and C++ equivalents

Language Environment condition names (the symbolic feedback codes CEExxx) can
be used interchangeably with the equivalent C and C++ conditions listed in the
following table. For example, AT OCCURRENCE CEE341 is equivalent to AT OCCURRENCE
SIGILL. Raising a CEE341 condition triggers an AT OCCURRENCE SIGILL breakpoint
and vice versa.
Language Environment Description Equivalent C/C++

condition condition
CEE341 Operation exception SIGILL
CEE342 Privileged operation exception SIGILL
CEE343 Execute exception SIGILL
CEE344 Protection exception SIGSEGV
CEE345 Addressing exception SIGSEGV
CEE346 Specification exception SIGILL
CEE347 Data exception SIGFPE
CEE348 Fixed point overflow exception SIGFPE
CEE349 Fixed point divide exception SIGFPE
CEE34A Decimal overflow exception SIGFPE
CEE34B Decimal divide exception SIGFPE
CEE34C Exponent overflow exception SIGFPE
CEE34D Exponent underflow exception SIGFPE
CEE34E Significance exception SIGFPE
CEE34F Floating-point divide exception SIGFPE

Debug Tool evaluation of C and C++ expressions
Debug Tool interprets most input as a collection of one or more expressions. You
can use expressions to alter a program variable or to extend the program by
adding expressions at points that are governed by AT breakpoints.
Debug Tool evaluates C and C++ expressions following the rules presented in
C/C++ Language Reference. The result of an expression is equal to the result that
would have been produced if the same expression had been part of your compiled
program.
Implicit string concatenation is supported. For example, "abc" "def" is accepted for
"abcdef" and treated identically. Concatenation of wide string literals to string
literals is not accepted. For example, L"abc"L"def" is valid and equivalent to
L"abcdef", but "abc" L"def" is not valid.
Expressions you use during your session are evaluated with the same sensitivity to
enablement as are compiled expressions. Conditions that are enabled are the same
ones that exist for program statements.
During a Debug Tool session, if the current setting for WARNING is ON, the occurrence
in your C or C++ program of any one of the conditions listed below causes the
display of a diagnostic message.
v Division by zero
v Remainder (%) operator for a zero value in the second operand
v Array subscript out of bounds for a defined array
v Bit shifting by a number that is either negative or greater than 32
v Incorrect number of parameters, or parameter type mismatches for a function
call
v Differing linkage calling conventions for a function call
v Assignment of an integer value to a variable of enumeration data type where the
integer value does not correspond to an integer value of one of the enumeration
constants of the enumeration data type
v Assignment to an lvalue that has the const attribute
v Attempt to take the address of an object with register storage class
v A signed integer constant not in the range −2**31 to 2**31
v A real constant not having an exponent of 3 or fewer digits
v A float constant not larger than 5.39796053469340278908664699142502496E-79 or
smaller than 7.2370055773322622139731865630429929E+75
v A hex escape sequence that does not contain at least one hexadecimal digit
v An octal escape sequence with an integer value of 256 or greater
v An unsigned integer constant greater than the maximum value of 4294967295.
Related references

Intercepting files when debugging C and C++ programs
Several considerations must be kept in mind when using the SET INTERCEPT
command to intercept files while you are debugging a C application.
For CICS only: SET INTERCEPT is not supported for CICS.
For C++, there is no specific support for intercepting IOStreams. IOStreams is

implemented using C I/O which implies that:
v If you intercept I/O for a C standard stream, this implicitly intercepts I/O for
the corresponding IOStreams’ standard stream.
v If you intercept I/O for a file, by name, and define an IOStream object
associated with the same file, IOStream I/O to that file will be intercepted.
Note: Although you can intercept IOStreams indirectly via C/370 I/O, the
behaviors might be different or undefined in C++.
You can use the following names with the SET INTERCEPT command during a
debug session:
v stdout, stderr, and stdin (lowercase only)
v any valid fopen() file specifier.
The behavior of I/O interception across system() call boundaries is global. This
implies that the setting of INTERCEPT ON for xx in Program A is also in effect for
Program B (when Program A system() calls to Program B). Correspondingly,
setting INTERCEPT OFF for xx in Program B turns off interception in Program A
when Program B returns to A. This is also true if a file is intercepted in Program B
and returns to Program A. This model applies to disk files, memory files, and
standard streams.
When a stream is intercepted, it inherits the text/binary attribute specified on the

fopen statement. The output to and input from the Debug Tool log file behaves like
terminal I/O, with the following considerations:
v Intercepted input behaves as though the terminal was opened for record I/O.
Intercepted input is truncated if the data is longer than the record size and the
truncated data is not available to subsequent reads.
v Intercepted output is not truncated. Data is split across multiple lines.
v Some situations causing an error with the real file might not cause an error
when the file is intercepted (for example, truncation errors do not occur). Files
expecting specific error conditions do not make good candidates for interception.
v Only sequential I/O can be performed on an intercepted stream, but file
positioning functions are tolerated and the real file position is not changed.
fseek, rewind, ftell, fgetpos, and fsetpos do not cause an error, but have no
effect.
v The logical record length of an intercepted stream reflects the logical record
length of the real file.
v When an unintercepted memory file is opened, the record format is always fixed
and the open mode is always binary. These attributes are reflected in the
intercepted stream.
v Files opened to the terminal for write are flushed before an input operation
occurs from the terminal. This is not supported for intercepted files.
Other characteristics of intercepted files are:

v When an fclose() occurs or INTERCEPT is set OFF for a file that was intercepted,
the data is flushed to the session log file before the file is closed or the SET
INTERCEPT OFF command is processed.
v When an fopen() occurs for an intercepted file, an open occurs on the real file
before the interception takes effect. If the fopen() fails, no interception occurs for
that file and any assumptions about the real file, such as the ddname allocation
and data set defaults, take effect.
v The behavior of the ASIS suboption on the fopen() statement is not supported
for intercepted files.
v When the clrmemf() function is invoked and memory files have been
intercepted, the buffers are flushed to the session log file before the files are
removed.
v If the fldata() function is invoked for an intercepted file, the characteristics of
the real file are returned.
v If stderr is intercepted, the interception overrides the Language Environment
message file (the default destination for stderr). A subsequent SET INTERCEPT
OFF command returns stderr to its MSGFILE destination.
v If a file is opened with a ddname, interception occurs only if the ddname is
specified on the INTERCEPT command. Intercepting the underlying file name does
not cause interception of the stream.
v User prefix qualifications are included in MVS data set names entered in the
INTERCEPT command, using the same rules as defined for the fopen() function.
v If library functions are invoked when Debug Tool is waiting for input for an
intercepted file (for example, if you interactively enter fwrite(..) when Debug
Tool is waiting for input), subsequent behavior is undefined.
v I/O intercepts remain in effect for the entire debug session, unless you terminate
them by selecting SET INTERCEPT OFF.
Command line redirection of the standard streams is supported under Debug Tool,
as shown below.
1>&2 If stderr is the target of the interception command, stdout is also
intercepted. If stdout is the target of the INTERCEPT command, stderr is
not intercepted. When INTERCEPT is set OFF for stdout, the stream is
redirected to stderr.
2>&1 If stdout is the target of the INTERCEPT command, stderr is also
intercepted. If stderr is the target of the INTERCEPT command, stdout is
not intercepted. When INTERCEPT is set OFF for stderr, the stream is
redirected to stdout again.
1>file.name
stdout is redirected to file.name. For interception of stdout to occur,
stdout or file.name can be specified on the interception request. This also
applies to 1>>file.name
2>file.name
stderr is redirected to file.name. For interception of stderr to occur,
stderr or file.name can be specified on the interception request. This also
applies to 2>>file.name
2>&1 1>file.name
stderr is redirected to stdout, and both are redirected to file.name. If
file.name is specified on the interception command, both stderr and
stdout are intercepted. If you specify stderr or stdout on the INTERCEPT
command, the behavior follows rule 1b above.

1>&2 2>file.name
stdout is redirected to stderr, and both are redirected to file.name. If you
specify file.name on the INTERCEPT command, both stderr and stdout are
intercepted. If you specify stdout or stderr on the INTERCEPT command,
the behavior follows rule 1a above.
The same standard stream cannot be redirected twice on the command line.
Interception is undefined if this is violated, as shown below.
2>&1 2>file.name
Behavior of stderr is undefined.
1>&2 1>file.name
Behavior of stdout is undefined.
Related references
z/OS C/C++ Programming Guide
Scope of objects in C and C++

An object is visible in a block or source file if its data type and declared name are
known within the block or source file. The region where an object is visible is
referred to as its scope. In Debug Tool, an object can be a variable or function and
is also used to refer to line numbers.
Note: The use of an object here is not to be confused with a C++ object. Any
reference to C++ will be qualified as such.
In ANSI C, the four kinds of scope are:

Block
File
Function
Function prototype
For C++, in addition to the scopes defined for C, it also has the class scope.
An object has block scope if its declaration is located inside a block. An object with
block scope is visible from the point where it is declared to the closing brace (})
that terminates the block.
An object has file scope if its definition appears outside of any block. Such an
object is visible from the point where it is declared to the end of the source file. In
Debug Tool, if you are qualified to the compilation unit with the file static
variables, file static and global variables are always visible.
The only type of object with function scope is a label name.
An object has function prototype scope if its declaration appears within the list of
parameters in a function prototype.
A class member has class scope if its declaration is located inside a class.
You cannot reference objects that are visible at function prototype scope, but you
can reference ones that are visible at file or block scope if:
v For C variables and functions, the source file was compiled with TEST(SYM) and
the object was referenced somewhere within the source.

v For C variables declared in a block that is nested in another block, the source file
was compiled with TEST(SYM, BLOCK).
v For line numbers, the source file was compiled with TEST(LINE) GONUMBER.
v For labels, the source file was compiled with TEST(SYM, PATH). In some cases
(for example, when using GOTO), labels can be referenced if the source file was
compiled with TEST(SYM, NOPATH).
Debug Tool follows the same scoping rules as ANSI, except that it handles objects
at file scope differently. An object at file scope can be referenced from within
Debug Tool at any point in the source file, not just from the point in the source file
where it is declared. Debug Tool session variables always have a higher scope than
program variables, and consequently have higher precedence than a program
variable with the same name. The program variable can always be accessed
through qualification.
In addition, Debug Tool supports the referencing of variables in multiple load

modules. Multiple load modules are managed through the C library functions
dllload(), dllfree(), fetch(), and release().
“Example: referencing variables and setting breakpoints in C and C++ blocks” on

page 221
Related concepts
“Storage classes in C and C++”
Storage classes in C and C++

Debug Tool supports the change and reference of all objects declared with the
following storage classes:
auto
register
static
extern
Session variables declared during the Debug Tool session are also available for
reference and change.
An object with auto storage class is available for reference or change in Debug
Tool, provided the block where it is defined is active. Once a block finishes
executing, the auto variables within this block are no longer available for change,
but can still be examined using DESCRIBE ATTRIBUTES.
An object with register storage class might be available for reference or change in
Debug Tool, provided the variable has not been optimized to a register.
An object with static storage class is always available for change or reference in
Debug Tool. If it is not located in the currently qualified compile unit, you must
specifically qualify it.
An object with extern storage class is always available for change or reference in
Debug Tool. It might also be possible to reference such a variable in a program
even if it is not defined or referenced from within this source file. This is possible
provided Debug Tool can locate another compile unit (compiled with TEST(SYM))
with the appropriate definition.

Blocks and block identifiers for C
It is often necessary to set breakpoints on entry into or exit from a given block or
to reference variables that are not immediately visible from the current block.
Debug Tool can do this, provided that all blocks are named. It uses the following
naming convention:
v The outermost block of a function has the same name as the function.
v Blocks enclosed in this outermost block are sequentially named: %BLOCK2,
%BLOCK3, %BLOCK4, and so on in order of their appearance in the function.
When these block names are used in the Debug Tool commands, you might need
to distinguish between nested blocks in different functions within the same source
file. This can be done by naming the blocks in one of two ways:
Short form
function_name:>%BLOCKzzz
Long form
function_name:>%BLOCKxxx :>%BLOCKyyy: ... :>%BLOCKzzz
%BLOCKzzz is contained in %BLOCKyyy, which is contained in %BLOCKxxx. The short

form is always allowed; it is never necessary to specify the long form.
The currently active block name can be retrieved from the Debug Tool variable
%BLOCK. You can display the names of blocks by entering:
DESCRIBE CU;
Blocks and block identifiers for C++

Block Identifiers tend to be longer for C++ than C because C++ functions can be
overloaded. In order to distinguish one function name from the other, each block
identifier is like a prototype. For example, a function named shapes(int,int) in C
would have a block named shapes; however, in C++ the block would be called
shapes(int,int).
You must always refer to a C++ block identifier in its entirety, even if the function
is not overloaded. That is, you cannot refer to shapes(int,int) as shapes only.
Note: The block name for main() is always main (without the qualifying
parameters after it) even when compiled with C++ because main() has
extern C linkage.
Since block names can be quite long, it is not unusual to see the name truncated in
the LOCATION field on the first line of the screen. If you want to find out where you
are, enter:
QUERY LOCATION
and the name will be shown in its entirety (wrapped) in the session log.
Block identifiers are restricted to a length of 255 characters. Any name longer than
255 characters is truncated.

Example: referencing variables and setting breakpoints in C and C++
blocks
The program below is used as the basis for several examples, described after the
program listing.
#pragma runopts(EXECOPS)
#include <stdlib.h>
main()
{
>>> Debug Tool is given <<<
>>> control here. <<<
init();
sort();
}
short length = 40;

static long *table;
init()
{
table
. = malloc(sizeof(long)*length);
.
.
}
sort ()
{ /* Block sort */
int i;
for (i = 0; i < length–1; i++) { /* Block %BLOCK2 */
int j;
for (j = i+1; j < length; j++) { /* Block %BLOCK3 */
static int temp;
temp = table[i];
table[i] = table[j];
table[j] = temp;
}
}
}
Scope and visibility of objects

Let’s assume the program shown above is compiled with TEST(SYM). When Debug
Tool gains control, the file scope variables length and table are available for
change, as in:
length = 60;
The block scope variables i, j, and temp are not visible in this scope and cannot be
directly referenced from within Debug Tool at this time. You can list the line
numbers in the current scope by entering:
LIST LINE NUMBERS;
Now let’s assume the program is compiled with TEST(SYM, NOBLOCK). Since the
program is explicitly compiled using NOBLOCK, Debug Tool will never know about
the variables j and temp because they are defined in a block that is nested in
another block. Debug Tool does know about the variable i since it is not in a scope
that is nested.
Blocks and block identifiers

In the program above, the function sort has three blocks:
sort

%BLOCK2
%BLOCK3
The following example sets a breakpoint on entry to the second block of sort:
at entry sort:>%BLOCK2;
The following example sets a breakpoint on exit of the first block of main and lists
the entries of the sorted table.
at exit main {
for (i = 0; i < length; i++)
printf("table entry %d is %d\n", i, table[i]);
}
The following example lists the variable temp in the third block of sort. This is
possible since temp has the static storage class.
LIST sort:>%BLOCK3:temp;
Displaying environmental information

You can also use the DESCRIBE command to display a list of attributes applicable to
the current run-time environment. The type of information displayed varies from
language to language.
Issuing DESCRIBE ENVIRONMENT displays a list of open files and conditions being
monitored by the run-time environment. For example, if you enter DESCRIBE
ENVIRONMENT while debugging a C or C++ program, you might get the following
output:
Currently open files
stdout
sysprint
The following conditions are enabled:
SIGFPE
SIGILL
SIGSEGV
SIGTERM
SIGINT
SIGABRT
SIGUSR1
SIGUSR2
SIGABND
Qualifying variables and changing the point of view in C and C++

Qualification is a method of:
v Specifying an object through the use of qualifiers
v Changing the point of view
Qualification is often necessary due to name conflicts, or when a program consists

of multiple load modules, compile units, and/or functions.
When program execution is suspended and Debug Tool receives control, the
default, or implicit qualification is the active block at the point of program
suspension. All objects visible to the C or C++ program in this block are also
visible to Debug Tool. Such objects can be specified in commands without the use
of qualifiers. All others must be specified using explicit qualification.
Qualifiers depend, of course, upon the naming convention of the system where
you are working.

Related concepts
“Example: using qualification in C” on page 224
Related tasks
“Qualifying variables in C and C++”
“Changing the point of view in C and C++”
Qualifying variables in C and C++

You can precisely specify an object, provided you know the following:
v Load module or DLL name
v Source file (compilation unit) name
v Block name (must include function prototype for C++ block qualification).
These are known as qualifiers and some, or all, might be required when
referencing an object in a command. Qualifiers are separated by a combination of
greater than signs (>) and colons and precede the object they qualify. For example,
the following is a fully qualified object:
load_name::>cu_name:>block_name:>object
If required, load_name is the name of the load module. It is required only when the
program consists of multiple load modules and when you want to change the
qualification to other than the current load module. load_name is enclosed in
double quotation marks. If it is not, it must be a valid identifier in the C or C++
programming language. load_name can also be the Debug Tool variable %LOAD.
If required, CU_NAME is the name of the compilation unit or source file. The
cu_name must be the fully qualified source file name or an absolute pathname. It is
required only when you want to change the qualification to other than the
currently qualified compilation unit. It can be the Debug Tool variable %CU. If there
appears to be an ambiguity between the compilation unit name, and (for example),
a block name, you must enclose the compilation unit name in double quotation
marks (").
If required, block_name is the name of the block. block_name can be the Debug Tool
variable %BLOCK.
Related concepts
“Blocks and block identifiers for C” on page 220
Changing the point of view in C and C++

To change the point of view from the command line or a command file, use
qualifiers in conjunction with the SET QUALIFY command. This can be necessary to
get to data that is inaccessible from the current point of view, or can simplify
debugging when a number of objects are being referenced.
It is possible to change the point of view to another load module or DLL, to

another compilation unit, to a nested block, or to a block that is not nested. The
SET keyword is optional.

Example: using qualification in C
The examples below use the following program.
LOAD MODULE NAME: MAINMOD
SOURCE FILE NAME: MVSID.SORTMAIN.C
short length = 40;

main ()
{
long *table;
void (*pf)();
table
. = malloc(sizeof(long)*length);
.
.
pf = fetch("SORTMOD");
(*pf)(table);
.
.
.
release(pf);
.
.
.
}
LOAD MODULE NAME: SORTMOD

SOURCE FILE NAME: MVSID.SORTSUB.C
short length = 40;

short sn = 3;
void (long table[])
{
short i;
for (i = 0; i < length-1; i++) {
short j;
for (j = i+1; j < length; j++) {
float sn = 3.0;
short temp;
. temp = table[i];
.
.
>>> Debug Tool is given <<<
. >>> control here. <<<
.
.
table[i] = table[j];
table[j] = temp;
}
}
}
When Debug Tool receives control, variables i, j, temp, table, and length can be
specified without qualifiers in a command. If variable sn is referenced, Debug Tool
uses the variable that is a float. However, the names of the blocks and compile
units differ, maintaining compatibility with the operating system.
Qualifying variables
v Change the file scope variable length defined in the compilation unit
MVSID.SORTSUB.C in the load module SORTMOD:
"SORTMOD"::>"MVSID.SORTSUB.C":>length = 20;
v Assume Debug Tool gained control from main(). The following changes the
variable length:
%LOAD::>"MVSID.SORTMAIN.C":>length = 20;
Because length is in the current load module and compilation unit, it can also
be changed by:
length = 20;

v Assume Debug Tool gained control as shown in the example program above.
You can break whenever the variable temp in load module SORTMOD changes
in any of the following ways:
AT CHANGE temp;
AT CHANGE %BLOCK3:>temp;
AT CHANGE sort:%BLOCK3:>temp;
AT CHANGE %BLOCK:>temp;
AT CHANGE %CU:>sort:>%BLOCK3:>temp;
AT CHANGE "MVSID.SORTSUB.C":>sort:>%BLOCK3:>temp;
AT CHANGE "SORTMOD"::>"MVSID.SORTSUB.C":>sort:>%BLOCK3:>temp;
Changing the point of view

v Qualify to the second nested block in the function sort() in sort.
SET QUALIFY BLOCK %BLOCK2;
You can do this in a number of other ways, including:

QUALIFY BLOCK sort:>%BLOCK2;
Once the point of view changes, Debug Tool has access to objects accessible from
this point of view. You can specify these objects in commands without qualifiers,
as in:
j = 3;
temp = 4;
v Qualify to the function main in the load module MAINMOD in the compilation
unit MVSID.SORTMAIN.C and list the entries of table.
QUALIFY BLOCK "MAINMOD"::>"MVSID.SORTMAIN.C":>main;
LIST table[i];
Stepping through C++ programs

You can step through methods as objects are constructed and destructed. In
addition, you can step through static constructors and destructors. These are
methods of objects that are executed before and after main() respectively.
If you are debugging a program that calls a function that resides in a header file,
the cursor moves to the applicable header file. You can then view the function
source as you step through it. Once the function returns, debugging continues at
the line following the original function call.
You can step around a header file function by issuing the STEP OVER command.
This is useful in stepping over Library functions (for example, string functions
defined in string.h) that you cannot debug anyway.
Setting breakpoints in C++

The differences between setting breakpoints in C++ and C are described below.
Setting breakpoints in C++ using AT ENTRY/EXIT

AT ENTRY/EXIT sets a breakpoint in the specified block. You can set a breakpoint on
methods, methods within nested classes, templates, and overloaded operators. An
example is given for each below.
A block identifier can be quite long, especially with templates, nested classes, or
class with many levels of inheritance. In fact, it might not even be obvious at first
as to the block name for a particular function. To set a breakpoint for these

nontrivial blocks can be quite cumbersome. Therefore, it is recommended that you
make use of DESCRIBE CU and retrieve the block identifier from the session log.
When you do a DESCRIBE CU, the methods are always shown qualified by their
class. If a method is unique, you can set a breakpoint by using just the method
name. Otherwise, you must qualify the method with its class name. The following
two examples are equivalent:
AT ENTRY method()
AT ENTRY classname::method()
The following examples are valid:
AT ENTRY square(int,int) 'simple' method square

AT ENTRY shapes::square(int) Method square qualified by its class
shapes.
AT EXIT outer::inner::func() Nested classes. Outer and inner are
classes. func() is within class inner.
AT EXIT Stack<int,5>::Stack() Templates.
AT ENTRY Plus::operator++(int) Overloaded operator.
AT ENTRY ::fail() Functions defined at file scope must
be referenced by the global scope
operator ::
The following examples are invalid:
AT ENTRY shapes Where shapes is a class. Cannot set

breakpoint on a class. (There is no
block identifier for a class.)
AT ENTRY shapes::square Invalid since method square must
be followed by its parameter list.
AT ENTRY shapes:>square(int) Invalid since shapes is a class name,
not a block name.
Setting breakpoints in C++ using AT CALL

AT CALL gives Debug Tool control when the application code attempts to call the
specified entry point. The entry name must be a fully qualified name. That is, the
name shown in DESCRIBE CU must be used. Using the example
AT ENTRY shapes::square(int)
to set a breakpoint on the method square, you must enter:

AT CALL shapes::square(int)
even if square is uniquely identified.
Related tasks

Examining C++ objects
When displaying an C++ object, only the local member variables are shown.
Access types (public, private, protected) are not distinguished among the variables.
The member functions are not displayed. If you want to see their attributes, you
can display them individually, but not in the context of a class. When displaying a
derived class, the base class within it is shown as type class and will not be
expanded.
Related tasks
“Example: displaying attributes of C++ objects”
Example: displaying attributes of C++ objects

The examples below use the following definitions.
class shape { ... };
class line : public shape {

member variables of class line...
}
line edge;
Displaying object attributes

To describe the attributes of the object edge, enter the following command.
DESCRIBE ATTRIBUTES edge;
The Log window displays the following output.

DESCRIBE ATTRIBUTES edge;
ATTRIBUTES for edge
Its address is yyyyyyyy and its length is xx
class line
class shape
member variables of class shape....
Note that the base class is shown as class shape _shape.
Displaying class attributes

To display the attributes of class shape, enter the following command.
DESCRIBE ATTRIBUTES class shape;
The Log window displays the following output.

DESCRIBE ATTRIBUTES class shape ;
ATTRIBUTES for class shape
const class shape...
Displaying static data

If a class contains static data, the static data will be shown as part of the class
when displayed. For example:
class A {
int x;
static int y;
}
A obj;
You can also display the static member by referencing it as A::y since each object
of class A has the same value.

Displaying global data
To avoid ambiguity, variables declared at file scope can be referenced using the
global scope operator ::. For example:
int x;
class A {
int x;
.
.
.
}
}
If you are within a member function of A and want to display the value of x at file
scope, enter LIST ::x. If you do not use ::, entering LIST x will display the value
of x for the current object (i.e., this–>x).
Monitoring storage in C++

You might find it useful to monitor registers (general-purpose and floating-point)
while stepping through your code and assembly listing by using the LIST
REGISTERS command. The compiler listing displays the pseudo assembly code,
including Debug Tool hooks. You can watch the hooks that you stop on and watch
expected changes in register values step by step in accordance with the pseudo
assembly instructions between the hooks. You can also modify the value of
machine registers while stepping through your code.
You can list the contents of storage in various ways. Using the LIST REGISTERS
command, you can receive a list of the contents of the general-purpose registers or
the floating-point registers.
You can also monitor the contents of storage by specifying a dump-format display
of storage. To accomplish this, use the LIST STORAGE command. You can specify the
address of the storage that you want to view, as well as the number of bytes.
Example: monitoring and modifying registers and storage in C

The examples below use the following C program to demonstrate how to monitor
and modify registers and storage.
int dbl(int j) /* line 1 */
{ /* line 2 */
return 2*j; /* line 3 */
} /* line 4 */
int main(void)
{
int i;
i = 10;
return dbl(i);
}
If you compile the program above using the compiler options TEST(ALL),LIST, then
your pseudo assembly listing will be similar to the listing shown below.
* int dbl(int j)
ST r1,152(,r13)
* {
EX r0,HOOK..PGM-ENTRY
* return 2*j;
EX r0,HOOK..STMT
L r15,152(,r13)
L r15,0(,r15)
SLL r15,1
B @5L2
DC A@5L2-ep)

NOPR
@5L1 DS 0D
* }
@5L2 DS 0D
EX r0,HOOK..PGM-EXIT
To display a continuously updated view of the registers in the Monitor window,

enter the following command:
MONITOR LIST REGISTERS
After a few steps, Debug Tool halts on line 1 (the program entry hook, shown in
the listing above). Another STEP takes you to line 3, and halts on the statement
hook. The next STEP takes you to line 4, and halts on the program exit hook. As
indicated by the pseudo assembly listing, only register 15 has changed during this
STEP, and it contains the return value of the function. In the Monitor window,
register 15 now has the value 0x00000014 (decimal 20), as expected.
You can change the value from 20 to 8 just before returning from dbl() by issuing
the command:
%GPR15 = 8 ;

Chapter 31. Debugging an assembler program
To debug programs that have been assembled with debug information and that
run under Language Environment, you can use most of the Debug Tool
commands. Any exceptions are noted in Debug Tool for z/OS Reference and Messages.
Before debugging an assembler program, prepare your program as described in
Chapter 9, “Preparing an assembler program,” on page 37.
The SET ASSEMBLER and SET DISASSEMBLY commands

The SET ASSEMBLER ON and SET DISASSEMBLY ON commands enable some of the
same functions. However, you must consider which type of CUs that you will be
debugging (assembler, disassembly, or both) before deciding which command to
use. The following guidelines can help you decide which command to use:
v If you are debugging assembler CUs but no disassembly CUs, you might want
to use the SET ASSEMBLER ON command. If you need the following functions, use
the SET ASSEMBLER ON command:
– Use the LIST, LIST NAMES CUS, or DESCRIBE CUS commands to see the name of
disassembly CUs.
– Use AT APPEARANCE to stop Debug Tool when the disassembly CU is loaded so
that you can enter the LOADDEBUGDATA command.
If you don’t need any of these functions, you don’t need to use either command.
v If you are debugging a disassembly CU, you must use the SET DISASSEMBLY ON
command so that you can see the disassembly view of the disassembly CUs. The
SET DISASSEMBLY ON command enables the functions enabled by SET ASSEMBLER
ON and also enables the following functions that are not available through the
SET ASSEMBLER ON command:
– View the disassembled listing in the Source window.
– Use the STEP INTO command to enter the disassembly CU.
– Use the AT ENTRY * command to stop at the entry point of disassembly CUs.
If you are debugging an assembler CU and later decide you want to debug a
disassembly CU, you can enter the SET DISASSEMBLY ON command after you enter
the SET ASSEMBLER ON command.
Loading an assembler program’s debug information

Use the LOADDEBUGDATA (or LDD) command to indicate to Debug Tool that a compile
unit is an assembler compile unit and to load the debug information associated
with that compile unit. The LDD command can be issued only for compile units
which have no debug information and are, therefore, considered disassembly
compile units. In the following example, mypgm is the compile unit (CSECT) name
of an assembler program:
LDD mypgm
Debug Tool locates the debug information in a data set with the following name:
yourid.EQALANGX(mypgm). If Debug Tool finds this data set, you can begin to debug
your assembler program. Otherwise, enter the SET SOURCE or SET DEFAULT LISTINGS
command to indicate to Debug Tool where to find the debug information.

Normally, compile units without debug information are not listed when you enter
the DESCRIBE CUS or LIST NAMES CUS commands. To include these compile units,
enter the SET ASSEMBLER ON command. The next time you enter the DESCRIBE CUS
or LIST NAMES CUS command, these compile units are listed.
Debug Tool session panel while debugging an assembler program

The Debug Tool session panel below shows the information displayed in the
Source window while you debug an assembler program.
Assemble LOCATION: SUBXMP
MONITOR --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 0 OF 0
******************************* TOP OF MONITOR ********************************
SOURCE: SUBXMP ---1----+----2----+----3----+----4----+----5---- LINE: 23 OF 575

1 5 + PUSH USING .
6 + DROP , .
7 3 + USING *,15 .
8 00000000 47F0 F014 + B CEEZ0001 .
9 00000004 + DC X’00C3C5C5’ .
10 2 +CEEY0001 DC A(((WORKSIZE+7)/8)*8) .
10 00000008 + . .
11 0000000C + DC A(XMPPPA-SUBXMP) . Addres .
12 00000010 47F0 F001 + B 1(,15) .
13 +CEEZ0001 EQU * .
14 00000014 90EC D00C + STM 14,12,CEEDSAR14-CEEDSA(13) .
15 00000018 5820 F050 + L 2,CEEINPL0001 .
16 0000001C 58F0 F054 + L 15,CEEINT0001 .
17 + DROP 15 .
18 00000020 05EF +4 BALR 14,15 .
19 00000022 1821 + LR 2,1 .
20 00000024 58E0 C2F0 + L 14,752(,12) .
21 00000028 9680 E008 + OI 8(14),X’80’ .
22 0000002C 05B0 + BALR 11,0 5 .
23 + USING *,11 .
24 0000002E 58B0 B02A + L 11,CEEOEPV0001 .
25 + POP USING .
LOG 0----+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 8
********************************* TOP OF LOG **********************************
0002 09/26/2003 2:11:59 PM
0004 EQA1872E An error occurred while opening file: INSPPREF. The file may not
0005 exist, or is not accessible.
0006 Source or Listing data is not available, or the CU was not compiled with
0007 the correct compile options.
0008 LDD subxmp ;
******************************** BOTTOM OF LOG ********************************

The information displayed in the Source window is similar to the listing generated
by the assembler. The Source window displays the following information:
1 statement number
The statement number is a number assigned by the EQALANGX program.
Use this column to set breakpoints and identify statements.
2 offset
The offset from the start of the CSECT. This column matches the left-most
column in the assembler listing.

3 object
The object code for instructions. This column matches the ″Object Code″
column in the assembler listing. Object code for data fields is not
displayed.
4 macro generated
A ″+″ in this column indicates that the line is generated by macro
expansion.
5 source statement
The original source statement. This column corresponds to the ″Source
Statement″ column in the assembler listing.
Restrictions for debugging an assembler program

You can only use Debug Tool to debug assembler programs if the program runs
under Language Environment.
Restrictions for debugging an assembler MAIN program

When you debug a Language Environment-enabled assembler main program, the
following restrictions apply:
v If Debug Tool is positioned at the entry point to the assembler main program
and you enter a STEP command, the STEP command stops at the instruction that
is after the prologue BALR instruction that initializes Language Environment.
You cannot step through the portion of the prologue that is prior to the
completion of Language Environment initialization.
v If you set a breakpoint in the prologue prior to the completion of Language
Environment initialization, the breakpoint is accepted. However, Debug Tool
does not stop or gain control at this a breakpoint.
Restrictions for debugging with the STORAGE run-time option

When the Language Environment STORAGE run-time option is in effect, the
following restrictions apply:
v If you try to step across the portion of the prologue code that is between the
point where the stack extend routine is called and the LR 13,x instruction that
loads the address of the new DSA into register 13, the STEP command stops at
the instruction immediately following the LR 13,x instruction.
v If you try to set a breakpoint in the portion of the prologue code between the
point where the stack extend routine is called and the LR 13,x instruction that
loads the address of the new DSA into register 13, Debug Tool will not set the
breakpoint.
Restrictions on the use of non-Language Environment

services
You can debug only load modules that are brought into storage through Language
Environment services such as CEELOAD and CEEFETCH. You cannot debug
programs loaded through other services, for example:
v MVS macros or SVC’s such as LOAD, LINK, ATTACH, and XCTL
v CICS services such as EXEC CICS LOAD
Restrictions for debugging self-modifying code

Debug Tool cannot debug self-modifying code. If your program contains
self-modifying code that modifies an instruction while the containing compilation
Chapter 31. Debugging an assembler program 233

unit is being debugged, the result can be unpredictable, including an abnormal
termination (ABEND) of Debug Tool. If your program contains self-modifying code
that completely replaces an instruction while the containing compilation unit is
being debugged, the result might not be an ABEND. However, Debug Tool might
miss a breakpoint on that instruction or display a message indicating an invalid
hook address at delete.
The following coding techniques can be used to minimize problems debugging

self-modifying code:
1. Do not modify part of an instruction. Instead, replace an instruction. The
following table compares coding techniques:
Coding that modifies an instructions Coding that replaces an instruction
ModInst BC 0,Target ModInst BC 0,Target

... ...
MVI ModInst+1,X’F0’ MVC ModInst(4),NewInst
...
NewInst BC 15,Target
2. Define instructions to be modified by using DC instructions instead of

executable instructions. For example, use the instruction ModInst DC
X’4700’,S(Target) instead of the instruction MVC ModInst(4),NewInst.

Chapter 32. Debugging a disassembled program
To debug programs that have been compiled or assembled without debug
information, you can use the disassembly view. When you use the disassembly
view, symbolic information from the original source program (program variables,
labels, and other symbolic references to a section of memory ) is not available. The
DYNDEBUG switch must be ON before you use the disassembly view.
If you are not familiar with the program that you are debugging, we recommend
that you have a copy of the listing that was created by the compiler or High Level
Assembler (HLASM) available while you debug the program. There are no special
assembly or compile requirements that the program must comply with to use the
disassembly view.
The SET ASSEMBLER and SET DISASSEMBLY commands

The SET ASSEMBLER ON and SET DISASSEMBLY ON commands enable some of the
same functions. However, you must consider which type of CUs that you will be
debugging (assembler, disassembly, or both) before deciding which command to
use. The following guidelines can help you decide which command to use:
v If you are debugging assembler CUs but no disassembly CUs, you might want
to use the SET ASSEMBLER ON command. If you need the following functions, use
the SET ASSEMBLER ON command:
– Use the LIST, LIST NAMES CUS, or DESCRIBE CUS commands to see the name of
disassembly CUs.
– Use AT APPEARANCE to stop Debug Tool when the disassembly CU is loaded so
that you can enter the LOADDEBUGDATA command.
If you don’t need any of these functions, you don’t need to use either command.
v If you are debugging a disassembly CU, you must use the SET DISASSEMBLY ON
command so that you can see the disassembly view of the disassembly CUs. The
SET DISASSEMBLY ON command enables the functions enabled by SET ASSEMBLER
ON and also enables the following functions that are not available through the
SET ASSEMBLER ON command:
– View the disassembled listing in the Source window.
– Use the STEP INTO command to enter the disassembly CU.
– Use the AT ENTRY * command to stop at the entry point of disassembly CUs.
If you are debugging an assembler CU and later decide you want to debug a
disassembly CU, you can enter the SET DISASSEMBLY ON command after you enter
the SET ASSEMBLER ON command.
Capabilities of the disassembly view

When you use the disassembly view, you can do the following tasks:
v Set breakpoints at the start of any assembler instruction.
v Step through the disassembly instructions of your program.
v Display and modify registers.
v Display and modify storage.
v Monitor general-purpose registers or areas of main storage.

v Switch the debug view.
v Use most Debug Tool commands.
Starting the disassembly view

To start the disassembly view:
1. Enter the SET DISASSEMBLY ON command
2. Open the program that does not contain debug data. Debug Tool then changes
the language setting to Disassem and the Source window displays the
assembler code.
If you enter a program that does contain debug data, the language setting does not
change and the Source window does not display disassembly code.
The disassembly view

When you debug a program through the disassembly view, the Source window
displays the disassembly instructions. The language area of the Debug Tool screen
(upper left corner) displays the word Disassem. The Debug Tool screen appears as
follows:
Disassem LOCATION: MAIN initialization
MONITOR --+----1----+----2----+----3----+----4----+----5----+----6 LINE: 0 OF 0
******************************* TOP OF MONITOR ********************************
SOURCE: MAIN +----1----+----2----+----3----+----4----+----5----+ LINE: 1 OF 160

0 1950C770 47F0 F014 BC 15,20(,R15) .
A4 1950C774 00C3 ???? .
6 1950C776B C5C5 ???? .
8 1950C778 0000 ???? .
A 1950C77A 0080C ???? .
C 1950C77C 0000 ???? .
E 1950C77E 00C4 ????D .
10 1950C780 47F0 F001 BC 15,1(,R15) .
14 1950C784 90EC D00C STM R14,R12,12(R13) .
18 1950C788 18BF LR R11,R15 E .
1A 1950C78A 5820 B130 L R2,304(,R11) .
1E 1950C78E 58F0 B134 L R15,308(,R11) .
22 1950C792 05EF BALR R14,R15 .
24 1950C794 1821 LR R2,R1 .
26 1950C796 58E0 C2F0 L R14,752(,R12) .
2A 1950C79A 9680 E008 OI 8(R14),128 .
2E 1950C79E 05B0 BALR R11,0 .
LOG 0----+----1----+----2----+----3----+----4----+----5----+----6- LINE: 1 OF 5
********************************* TOP OF LOG **********************************
0002 09/26/2003 10:52:22 AM
0004 EQA1872E An error occurred while opening file: INSPPREF. The file may not
0005 exist, or is not accessible.
0006 SET DISASSEMBLY ON ;
A Prefix Area

Displays the offset from the start of the CU or CSECT.
B Columns 1-8
Displays the address of the machine instruction in memory.

C Columns 13-26
Displays the machine instruction in memory.
D Columns 29-32
Displays the op-code mnemonic or ???? if the op-code is not valid.
E Columns 35-70
Displays the disassembled machine instruction.
When you use the disassembly view, the disassembly instructions displayed in the
source area are not guaranteed to be accurate because it is not always possible to
distinguish data from instructions. Because of the possible inaccuracies, we
recommend that you have a copy of the listing that was created by the compiler or
by HLASM. Debug Tool keeps the disassembly view as accurate as possible by
refreshing the Source window whenever it processes the machine code, for
example, after a STEP command.
Performing single-step operations

Use the STEP command to single-step through your program. In the disassembly
view, you step from one disassembly instruction to the next. Debug Tool highlights
the instruction that it runs next.
If you try to step back into the program that called your program, set a breakpoint
at the instruction to which you return in the calling program. If you try to step
over another program, set a breakpoint immediately after the instruction that calls
another program. When you try to step out of your program, Debug Tool displays
a warning message and lets you set the appropriate breakpoints. Then you can do
the step.
Debug Tool refreshes the disassembly view whenever it determines that the
disassembly instructions that are displayed are no longer correct. This refresh can
happen while you are stepping through your program.
Setting breakpoints
You can use a special breakpoint when you debug your program through the
disassembly view. AT OFFSET sets a breakpoint at the point that is calculated from
the start of the entry point address of the CSECT. You can set a breakpoint by
entering the AT OFFSET command on the command line or by placing the cursor in
the prefix area of the line where you want to set a breakpoint and press the AT
function key or type AT in the prefix area.
Debug Tool lets you set breakpoints anywhere within the starting and ending
address range of the CU or CSECT as long as the address appears to be a valid
op-code and is an even number offset. To avoid setting breakpoints at the wrong
offset, we recommend that you verify the offset by referring to a copy of the listing
that was created by the compiler or by HLASM.
Restrictions for debugging self-modifying code

Debug Tool cannot debug self-modifying code. If your program contains
self-modifying code that modifies an instruction while the containing compilation
unit is being debugged, the result can be unpredictable, including an abnormal
termination (ABEND) of Debug Tool. If your program contains self-modifying code
that completely replaces an instruction while the containing compilation unit is
Chapter 32. Debugging a disassembled program 237

being debugged, the result might not be an ABEND. However, Debug Tool might
miss a breakpoint on that instruction or display a message indicating an invalid
hook address at delete.
The following coding techniques can be used to minimize problems debugging

self-modifying code:
1. Do not modify part of an instruction. Instead, replace an instruction. The
following table compares coding techniques:
Coding that modifies an instructions Coding that replaces an instruction
ModInst BC 0,Target ModInst BC 0,Target

... ...
MVI ModInst+1,X’F0’ MVC ModInst(4),NewInst
...
NewInst BC 15,Target
2. Define instructions to be modified by using DC instructions instead of

executable instructions. For example, use the instruction ModInst DC
X’4700’,S(Target) instead of the instruction MVC ModInst(4),NewInst.
Displaying and modifying registers

You can display the contents of all the registers by using the LIST REGISTERS
command. To display the contents of an individual register, use the LIST Rx
command, where x is the individual register number. You can also display the
contents of an individual register by placing the cursor on the register and pressing
the LIST function key. The default LIST function key is PF4. You can modify the
contents of a register by using the assembler assignment statement.
Displaying and modifying storage

You can display the contents of storage by using the LIST STORAGE command. You
can modify the contents of storage by using the STORAGE command.
You can also use assembler statements to display and modify storage. For example,
to set the four bytes located by the address in register 2 to zero, enter the following
command:
R2-> <4>=0
To verify that the four bytes are set to zero, enter the following command:
LIST R2->
Changing the program displayed in the disassembly view

You can use the SET QUALIFY command to change the program that is displayed in
the disassembly view. Suppose you are debugging program ABC and you need to
set a breakpoint in program BCD.
1. Enter the command SET QUALIFY CU BCD on the command line. Debug Tool
changes the Source window to display the disassembly instructions for
program BCD.
2. Scroll through the Source window until you find the instruction where want to
set a breakpoint.
3. To return to program ABC, at the point where the next instruction is to run,
issue the SET QUALIFY RESET command.

Restrictions for the disassembly view
When you debug a disassembled program, the following restrictions apply:
v Language Environment must be available before Debug Tool is started.
Language Environment launches Debug Tool according to the suboptions that
you specified for the TEST run-time option.
v The main program in the application must be a fully conforming Language
Environment program and the disassembly program must be a Language
Environment-enabled program.
v Debug Tool’s support of non-conforming Language Environment programs is
limited to those programs where the non-main programs are within an
Language Environment application.
v Applications that use the XPLINK linking convention are not supported.
v The Dynamic Debug facility must be activated before you start debugging
through the disassembly view.
Debug Tool can debug Language Environment-conforming assembler programs as

described in the sections titled “Language Environment-conforming Assembler”
and “Non-Language Environment-conforming Assembler” in the OS/390 Language
Environment for OS/390 & VM Programming Guide.
When you debug a program through the disassembly view, Debug Tool cannot
stop the application in any of the following situations:
v The program does not comply with the first three restrictions that are listed
above.
v Between the following instructions:
– After the LE stack extend has been called in the prologue code, and
– Before R13 has been set with a savearea or DSA address and the backward
pointer has been properly set.
The application runs until Debug Tool encounters a valid save area backchain.
Chapter 32. Debugging a disassembled program 239

Part 6. Debugging in different environments

Chapter 33. Debugging DB2 programs
The topics below describe the steps for using Debug Tool to debug your DB2
programs.
v Chapter 10, “Preparing a DB2 program,” on page 41
v “Precompiling DB2 programs for debugging” on page 41
v “Compiling DB2 programs for debugging” on page 41
v “Linking DB2 programs for debugging” on page 42
v “Binding DB2 programs for debugging” on page 43
v “Debugging DB2 programs in batch mode”
v “Debugging DB2 programs in full-screen mode”
v Chapter 10, “Preparing a DB2 program,” on page 41
Related tasks
Debugging DB2 programs in batch mode

In order to debug your program with Debug Tool while in batch mode, follow
these steps:
1. Make sure the Debug Tool modules are available, either by STEPLIB or through
the LINKLIB.
2. Provide all the data set definitions in the form of DD statements (example: Log,
Preference, list, and so on).
3. Specify your debug commands in the command input file.
4. Run your program through the TSO batch facility.
Debugging DB2 programs in full-screen mode

In full-screen mode, you can decide at debug time what debugging commands you
want issued during the test.
Using Debug Tool Setup Utility (DTSU)
The Debug Tool Setup Utility is available through Debug Tool Utilities.
1. Start DTSU by using the TSO command or the ISPF panel option, if available.
Contact your system administrator to determine if the ISPF panel option is
available.
2. Create a setup file. Remember to select the Initialize New setup file for DB2
field.
3. Fill in all the fields with the appropriate information. Remember to enter the
proper commands in the DSN command options and the RUN command
options fields.
4. Enter the RUN command to run the DB2 program.
Using TSO commands

1. Ensure that either you or your system programmer has allocated all the
required data sets through a CLIST or REXX EXEC.

2. Issue the DSN command to start DB2.
3. Issue the RUN subcommand to execute your program. The TEST run-time option
can be specified as a parameter on the RUN subcommand. An example for a
COBOL program is:
RUN PROG(progname) PLAN(planname) LIB('user.library')
PARMS('/TEST(,*,;,*)')
Using TSO/Call Access Facility (CAF)

1. Link-edit the CAF language interface module DSNALI with your program.
2. Ensure that the data sets required by Debug Tool and your program have been
allocated through a CLIST or REXX procedure.
3. Enter the TSO CALL command CALL 'user.library(name of your program)', to
start your program. Include the TEST run-time option as a parameter in this
command.
In full-screen mode through a VTAM terminal

1. Specify the MFI%LU_name: parameter as part of the TEST option.
2. Follow the other requirements for debugging DB2 programs either under TSO
or in batch mode.
After your program has been initiated, debug your program by issuing the
required Debug Tool commands.
Note: If your source does not come up in Debug Tool when you launch it, check
that the listing or source file name corresponds to the MVS library name,
and that you have at least read access to that MVS library.
The program listing (for COBOL and PL/I) or program source (for C and C++)
that Debug Tool displays and uses for the debug session is the output from the
compile step and precompile step respectively, and thus includes all the DB2
expansion code produced by the DB2 precompiler. If you are compiling your
program with a COBOL compiler option that support the SQL compiler option, the
program listing does not include all the DB2 expansion code produced by the DB2
precompiler.
Related references
DB2 UDB for OS/390 Administration Guide

Chapter 34. Debugging DB2 stored procedures
A DB2 stored procedure is a compiled high-level language (HLL) program that can
run SQL statements. Debug Tool can debug in remote debug mode or full-screen
mode through a VTAM terminal any stored procedure written in C, C++, COBOL,
and PL/I. The program resides in an address space that is separate from the
calling program. The stored procedure can be called by another application or a
tool such as the IBM DB2 Stored Procedure Builder.
The topics below describe the steps for using Debug Tool to debug your DB2
stored procedures.
Related tasks
“Starting Debug Tool from DB2 stored procedures: troubleshooting” on page 85
Related references
Resolving some common problems

While debugging a stored procedure, it is useful to add the DB2 return codes and
message code variables (SQLCODE, SQLERRMC) to the Debug Tool Program Monitor.
Table 7 are some common errors and suggestions for resolving them:
Table 7. Common problems while debugging stored procedures and resolutions to those
problems
Error code Error message Resolution
SQLCODE = 471, SQLERRMC = Stored procedure was Start the stored procedure
00E79001 stopped. using DB2 Start Procedure
command.
SQLCODE = 471, SQLERRMC = Stored procedure could not Try using the DB2 Start
00E79002 be started because of a Procedure command. If this
scheduling problem. does not work, contact the
DB2 Administrator to raise
the dispatching priority of
the procedure.
SQLCODE = 471, SQLERRMC = WLM application Activate the WLM address
00E7900C environment name is not space using the MVS WLM
defined or available. VARY command, for example:
WLM VARY APPLENV=applenv,RESUME
where applenv is the name of

the WLM address space.
SQLCODE = 444, SQLERRMC Program not found. Verify that the LOADLIB is in
(none) the STEPLIB for the WLM or
DB2 address space JCL and
has the appropriate RACF
Read authorization for other
applications to access it.

Table 7. Common problems while debugging stored procedures and resolutions to those
problems (continued)
Error code Error message Resolution
SQLCODE = 430, SQLERRMC Abnormal termination in This can occur for many
(none) stored procedure reasons. If the stored
procedure abends without
calling Debug Tool, analyze
the Procedure for any logic
errors. If the Procedure runs
successfully without Debug
Tool, there may a problem
with how the stored
procedure was compiled and
linked. Be sure that the
Procedure data set has the
proper RACF authorizations.
There may be a problem with
the address space. Verify that
the WLM or DB2 Address
Space is correct. If there are
any modifications, be sure
the region is recycled.

Chapter 35. Debugging IMS programs
You can use Debug Tool to debug IMS programs in the following ways:
v To debug your IMS Transaction Manager (TM) programs without Batch Terminal
Simulator (BTS), use full-screen mode through a VTAM terminal or remote
debug mode.
v To debug your IMS TM programs with BTS Full-Screen Image Support (FSS) to
display your MFS screen formats on the TSO terminal, choose one of the
following:
– If you want all interaction to be on a single screen, use full-screen mode.
– If you want BTS/FSS data displayed on your TSO terminal and your Debug
Tool session to be displayed on another terminal, use full-screen mode
through a VTAM terminal or remote debug mode.
FSS is the default option when BTS is started in the TSO foreground, and is
available only when you are running BTS in the TSO foreground. FSS can only
be turned off by specifying TSO=NO on the ./O command. When running in the
TSO foreground, all call traces are displayed on your TSO terminal by default.
This can be turned off by parameters on either the ./O or ./T commands.
v To debug your batch IMS programs without BTS, use batch mode, full-screen
mode through a VTAM terminal, or remote debug mode.
v To debug your batch IMS programs with BTS, choose one of the following:
– If you want all interaction to be on a single screen, use full-screen mode.
– If you want BTS data displayed on your TSO terminal and your Debug Tool
session to be displayed on another terminal, use full-screen mode through a
VTAM terminal or remote debug mode.
Related tasks
Chapter 13, “Preparing an IMS program,” on page 53
“Setting up the run-time options for your IMS Version 8 TM program by using
Debug Tool Utilities” on page 54
“Linking IMS programs for debugging” on page 55
“Debugging IMS programs in interactive mode”
Related references
IMS/VS Batch Terminal Simulator Program Reference and Operations Manual
Debugging IMS programs in interactive mode

There are three ways to start Debug Tool in interactive mode:
v Specifying the MFI%LU_name: parameter of the TEST run-time option. This starts
Debug Tool in full-screen mode with a VTAM terminal. The VTAM terminal
controls the Debug Tool session.
v Specifying the VADTCPIP&tcpip_workstation_id: or the
TCPIP&tcpip_workstation_id: parameter of the TEST run-time option. This starts
Debug Tool in remote debug mode with a remote debugger.
v Run BTS in the TSO foreground.
In interactive mode, Debug Tool commands can be entered as required.

If you want to debug an IMS batch program using the interactive mode of Debug
Tool, do the following under BTS:
1. Define a dummy transaction code on the ./T command to initiate your program
2. Include a dummy transaction in the BTS input stream
3. Start BTS in the TSO foreground
Note: If your source (C and C++) or listing (COBOL and PL/I) does not come up
in Debug Tool when you launch it, check that the source or listing file name
corresponds to the MVS library name, and that you have at least read access
to that MVS library.
Currently, Debug Tool can only be used to debug one iteration of a transaction at a
time. When the program terminates you must close down Debug Tool before you
can view the output of the transaction.
Therefore, if you use an input data set, you can only specify data for one
transaction in that data set. The data for the next transaction must be entered from
your TSO terminal.
A new debug session will be started automatically for the next transaction. When
using FSS, you must enter the /* command on your TSO terminal to terminate the
BTS session.
Debugging IMS programs in batch mode

You can use Debug Tool to debug IMS programs in batch mode. The debug
commands must be predefined and included in one of the Debug Tool command
files, or in a command string. The command string can be specified as a parameter
either in the TEST run-time option, or when CALL CEETEST or __ctest is used.
Although batch mode consumes fewer resources, you must know beforehand
exactly which debug commands you are going to issue. When you run BTS as a
batch job, the batch mode of Debug Tool is the only mode available for use.
For example, you can allocate a data set, userid.CODE.BTSINPUT with individual
members of test input data for IMS transactions under BTS.
Under IMS, you can start Debug Tool in the following ways:
v Use the compiler run-time option (#pragma runopts for C and C++)
v Include CSECT CEEUOPT when linking your program (for C and C++)
v Use the Language Environment callable service CEETEST (__ctest() for C and
C++)

Chapter 36. Debugging CICS programs
Before you can debug your programs under CICS, make sure your Systems
Programmer has made the appropriate changes to your CICS region to support
Debug Tool (see the Debug Tool for z/OS Customization Guide). You also need to
ensure that your program is translated by the CICS translator prior to compilation.
The program source file (for C and C++ and Enterprise PL/I), the program listing
(for COBOL and all other PL/I), or separate debug file (for COBOL) must be
retained in a permanent data set for Debug Tool to read when you debug your
program.
Note: For C and C++ and Enterprise PL/I, it is the input to the compiler (that is,
the output from the CICS translator) that needs to be retained. To enhance
performance when using Debug Tool, use a large block size when saving
these files.
Related tasks
“Starting Debug Tool under CICS” on page 86
“Using DTCN to start Debug Tool for CICS programs” on page 87
“Link-editing CEEBXITA into your program” on page 47
“Creating and storing a DTCN profile” on page 47
“Using compiler directives to start Debug Tool under CICS” on page 88
“Using CEDF to start Debug Tool under CICS” on page 88
“Preventing Debug Tool from stopping at EXEC CICS RETURN” on page 250
“Saving settings while debugging a pseudo-conversational program” on page 250
Related references
“Debug modes under CICS”
“Restrictions when debugging under CICS” on page 250
Debug modes under CICS

Debug Tool can run in several different modes, providing you with the flexibility
to debug your applications in the way that suits you best. These modes include:
Single terminal mode
This is probably the mode you will use the most. A single 3270 session is
used by both Debug Tool and the application, swapping displays on the
terminal as required.
As you step through your application, the terminal shows Debug Tool
screens, but when an EXEC CICS SEND command is issued, that screen will
be displayed. Debug Tool holds that screen on the terminal for you to
review; simply press Enter to return to a Debug Tool screen. When your
application issues EXEC CICS RECEIVE, the application screen again appears,
so you can fill in the screen details.
Dual terminal mode
This mode can be useful if you are debugging screen I/O applications.
Debug Tool displays its screens on a separate 3270 session than the
terminal displaying the application.
You step through the application using the Debug Tool terminal and,
whenever the application issues an EXEC CICS SEND, the screen is sent to

the application display terminal. Note that, if you do not code IMMEDIATE
on the EXEC CICS SEND command, the buffer of data might be held within
CICS Terminal Control until an optimum opportunity to send it is
encountered--usually the next EXEC CICS SEND or EXEC CICS RECEIVE. When
the application issues an EXEC CICS RECEIVE, the Debug Tool terminal will
wait until you respond to the application terminal.
Interactive batch mode
Use this mode if you are debugging a transaction that does not have a
terminal associated with it. The transaction continues to run without a
CICS principal facility, but Debug Tool screens are displayed on a 3270
session that you name.
Noninteractive batch mode
In this mode, Debug Tool does not have a terminal associated to it at all. It
receives its commands from a command file and writes its results to a log
file. This mode is useful if you want Debug Tool to debug a program
automatically.
Preventing Debug Tool from stopping at EXEC CICS RETURN

Debug Tool stops at EXEC CICS RETURN and displays one of the following messages:
v CEE0199W The termination of a thread was signaled due to a STOP statement.
To prevent Debug Tool from stopping at every EXEC CICS RETURN statement in
your application and suppress this message, set the TEST level to ERROR by
using the SET TEST ERROR command.
v LOCATION: Unknown (Application program has terminated)
This message is displayed at the top of the screen, in the session panel header.
To prevent Debug Tool from stopping at every EXEC CICS RETURN statement in
your application and suppress this message, clear the AT TERMINATION
breakpoints by using the CLEAR AT TERMINATION command.
Saving settings while debugging a pseudo-conversational program

If you change the Debug Tool display settings (for example, color settings) while
you debug a pseudo-conversational CICS program, Debug Tool might restore the
default settings. To ensure that your changes remain in effect every time your
program starts Debug Tool, store your display settings in the preferences file or the
commands file.
Saving and restoring breakpoints

When breakpoints are set in a CICS transaction, Debug Tool saves these breakpoint
settings and restores them the next time this transaction is started. However,
saving and restoring of breakpoints in assembler compilation units is not currently
supported.
Restrictions when debugging under CICS

The following restrictions apply when debugging programs with the Debug Tool in
a CICS environment.
v The __ctest() function with CICS does nothing.

v The CDT# transaction is a special Debug Tool service transaction, and is not
intended for activation by direct terminal input. If CDT# is started via terminal
entry, it will return to the caller (no function is performed).
v Applications that issue EXEC CICS POST cannot be debugged in Dual Terminal
mode.
v Data definition (ddname) is not supported. All files, including the log file, USE
files, and preferences file, must be referred to by their full data set names.
v The commands TSO, SET INTERCEPT, and SYSTEM cannot be used.
v CICS does not support an attention interrupt from the keyboard.
v The log file (INSPLOG) is not automatically started. You need to use the SET LOG
ON command.
v Ensure that you allocate a log file big enough to hold all the log output from a
debug session, because the log file is truncated after it becomes full. (A warning
message is not issued before the log is truncated.)
v Save files (INSPSAFE) are not used under CICS.
Chapter 36. Debugging CICS programs 251

Chapter 37. Debugging ISPF applications
You can debug ISPF applications in one of two ways:
v Using a separate terminal by specifying the LU name of a VTAM terminal as
part of the TEST parameter. For example:
TEST(,,,MFI%TCP00001:)
v Using the same emulator session. PA2 refreshes the ISPF application panel and
removes residual Debug Tool output from the emulator session. However, if
Debug Tool sends output to the emulator session between displays of the ISPF
application panels, you need to press PA2 after each ISPF panel display.
The rest of this section assumes that you are debugging ISPF applications using the
same emulator session.
When you debug ISPF applications or applications that use line mode input and
output, issue the SET REFRESH ON command. This command is executed and is
displayed in the log output area of the Command/Log window.
Because SET REFRESH ON modifies the Debug Tool environment, the REFRESH setting
is saved in the preferences file (inspsafe), and it is preserved between Debug Tool
invocations. You need to specify it only once; Debug Tool uses the same setting on
subsequent invocations.
Related tasks
Chapter 26, “Customizing your full-screen session,” on page 171

Chapter 38. Debugging programs in a production environment
Programs in a production environment have any of the following characteristics:
v The programs are compiled without hooks.
v The programs are compiled with the optimization compiler option, usually the
OPT compiler option.
v The programs are compiled with COBOL compilers that support the SEPARATE
suboption of the TEST compiler option.
This section helps you determine how much of Debug Tool’s testing functions you
want to continue using after you complete major testing of your application and
move into the final tuning phase. Included are discussions of program size and
performance considerations; the consequences of removing hooks, the statement
table, and the symbol table; and using Debug Tool on optimized programs.
Related tasks
“Fine-tuning your programs with Debug Tool”
“Debugging without hooks, statement tables, and symbol tables” on page 256
“Debugging optimized C, C++, PL/I and older COBOL programs” on page 257
“Debugging optimized COBOL programs” on page 258
Fine-tuning your programs with Debug Tool

After initial testing, you might want to consider the following options available to
improve performance and reduce size:
v Removing the hooks, which can improve the performance of your program.
v Removing the statement and symbol tables, which can reduce the size of your
program.
Removing hooks
One option for increasing the performance of your program is to compile with a
minimum of hooks or with no hooks.
v For C programs, compiling with the option TEST(NOLINE,BLOCK,NOPATH) causes
the compiler to insert a minimum number of hooks while still allowing you to
perform tasks at block boundaries.
v For COBOL programs, compiling with the option TEST(NONE,SYM) creates
programs that do not have hooks. Using the Dynamic Debug facility, Debug Tool
inserts hooks while debugging the program, allowing you to perform almost any
debugging task.
Independent studies show that performance degradation is negligible because of

hook-overhead for PL/I programs. Also, in the event you need to request an
attention interrupt, Debug Tool is not able to regain control without compiled-in
hooks. In such a case you can request an interrupt three times. After the third time,
Debug Tool is able to stop program execution and prompt you to enter QUIT or GO.
If you enter QUIT, your Debug Tool session ends. If you enter GO, control is
returned to your application.
It is a good idea to examine the benefits of maintaining hooks in light of the

performance overhead for that particular program.

Removing statement and symbol tables
If you are concerned about the size of your program, you can remove the symbol
table, the statement table, or both, after the initial testing period. For C and PL/I
programs, compiling with the option TEST(NOSYM) inhibits the creation of symbol
tables.
Before you remove them, however, you should consider their advantages. The
statement table allows you to display the execution history with statement
numbers rather than offsets, and error messages identify statement numbers that
are in error. The symbol table enables you to refer to variables and program
control constants by name. Therefore, you need to look at the trade-offs between
the size of your program and the benefits of having symbol and statement tables.
For programs that are compiled with the following compilers and with the
SEPARATE suboption of the TEST compiler option, the symbol tables are saved in a
separate debug file. This arrangement lets you to retain the symbol table
information and have a smaller program:
Debugging without hooks, statement tables, and symbol tables

Debug Tool can gain control at program initialization by using the PROMPT
suboption of the TEST run-time option. Even when you have removed all hooks
and the statement and symbol tables from a production program, Debug Tool
receives control when a condition is raised in your program if you specify ALL or
ERROR on the TEST run-time option, or when a __ctest(), CEETEST, or PLITEST is
executed.
When Debug Tool receives control in this limited environment, it does not know
what statement is in error (no statement table), nor can it locate variables (no
symbol table). Thus, you must use addresses and interpret hexadecimal data
values to examine variables. In this limited environment, you can:
v Determine the block that is in control:
list (%LOAD, %CU, %BLOCK);
or
list (%LOAD, %PROGRAM, %BLOCK);
v Determine the address of the error and of the compile unit:
list (%ADDRESS, %EPA); (where %EPA is allowed)
v Display areas of the program in hexadecimal format. Using your listing, you can
find the address of a variable and display the contents of that variable. For
example, you can display the contents at address 20058 in a C and C++ program
by entering:
LIST STORAGE (0x20058);
To display the contents at address 20058 in a COBOL or PL/I program, you

would enter:
LIST STORAGE (X'20058');
v Display registers:
LIST REGISTERS;
v Display program characteristics:

DESCRIBE CU; (for C)
DESCRIBE PROGRAM; (for COBOL)

v Display the dynamic block chain:
LIST CALLS;
v Request assistance from your operating system:
SYSTEM ...;
v Continue your program processing:
GO;
v End your program processing:
QUIT;
If your program does not contain a statement or symbol table, you can use session
variables to make the task of examining values of variables easier.
Even in this limited environment, HLL library routines are still available.
Programs that are compiled with Enterprise COBOL for z/OS and OS/390 or
COBOL for OS/390 & VM can have the best performance and smallest module
size, while retaining full debugging capabilities, if they are compiled with the
TEST(NONE,SYM,SEPARATE) compiler option. This option specifies that no hooks are
inserted and symbol table information is saved in a separate debug file.
Debugging optimized C, C++, PL/I and older COBOL programs

If you debug your application program with Debug Tool after compiling with the
OPTIMIZE compiler option (where applicable), keep in mind that optimization
decreases the reliability of Debug Tool functions in several areas:
v Values of variables
v Statement numbers
v Placement of breakpoints
v Interdependencies
In the case of variable values, Debug Tool displays the contents of the storage
where the variable has been assigned. However, in an optimized program, the
variable might actually reside in a register. For example, consider the following
assignments for the OPTIMIZE compiler option:
a = 5
b = a + 3
In an optimized program, the value of 5 that is associated with the variable a

might never be placed into storage. Instead, it might be pulled from a machine
register. If Debug Tool is requested to LIST TITLED a;, however, it looks in the
storage assigned to a and displays that value, no matter what it is.
To determine the source statement that is associated with a specific storage

location, you use the LIST STATEMENT NUMBERS command. This command shows the
statements that, for example, can be used in AT and GOTO commands. Optimization
can change the way it stores the specific storage location of a source statement.
Normally, the statement table supplies this information to Debug Tool, but if you
have requested optimization, the statement table might not match the source
statements. Code that is associated with one statement can move to another storage
location, and can appear (according to the statement table) to be part of a
Chapter 38. Debugging programs in a production environment 257

completely different statement. Therefore, the statement number that Debug Tool
displays as associated with a particular breakpoint might be incorrect.
If you have requested that your application be optimized, Debug Tool cannot
guarantee that a breakpoint that is set at a particular statement indeed occurs at
the beginning of the code that is generated for that statement.
Optimization usually causes the code that is generated for a statement to be

dependent on register values that the code for preceding statements loaded. Thus,
if you request Debug Tool to change the path of flow in your program, you run
the risk of depriving statements of necessary input.
Debugging optimized COBOL programs

COBOL programs that are compiled with the following compilers are enhanced
with features that make optimized programs easier to debug:
v Enterprise COBOL for z/OS and OS/390, Version 3 Release 2
v Enterprise COBOL for z/OS and OS/390, Version 3 Release 1, with APAR
PQ63235
v COBOL for OS/390 & VM, Version 2, with APAR PQ63234
You must compile your COBOL programs with one of the following combinations
of compiler options:
v OPT(STD) TEST(NONE,SYM)
v OPT(STD) TEST(NONE,SYM,SEPARATE)
v OPT(FULL) TEST(NONE,SYM)
v OPT(FULL) TEST(NONE,SYM,SEPARATE)
Most of the restrictions described in “Debugging optimized C, C++, PL/I and

older COBOL programs” on page 257 do not apply to programs compiled with the
compilers listed above:
v You can set breakpoints. If the optimizer moves or removes a statement, you
can’t set a breakpoint at that statement.
v You can display the value of a variable by using the LIST or LIST TITLED
commands. Debug Tool displays the correct value of the variable.
v You can step through programs one statement at a time, or run your program
until you encounter a breakpoint.
v You can use the SET AUTOMONITOR and PLAYBACK commands.
v You can change the value of a variable. Enter the SET WARNING OFF command
before you begin modifying variables. You only need to enter the SET WARNING
OFF command once during your debugging session. Whenever you enter a
command that modifies the value of a variable, Debug Tool performs the
command and displays a warning message. You must also apply APAR PQ71779
to Language Environment to take advantage of this feature.
The enhancements to the compilers help you create programs that can be
debugged in the same way that you debug unoptimized programs. There are some
exceptions:
v You cannot change the flow of your program.
v You cannot use the GOTO command.
v You cannot use the AT CALL entry_name command. Instead, use the AT CALL *
command.

v If the optimizer discarded a variable, you can refer to the variable only by using
the DESCRIBE ATTRIBUTES command. If you try to use any other command,
Debug Tool displays a message indicating that the variable was discarded by the
optimization techniques of the compiler.
v If you use the AT command, the following restrictions apply:
– You cannot specify a line number where all the statements have been
removed.
– You cannot specify a range of line numbers where all the statements have
been removed.
– You cannot specify a range of line numbers where the beginning point or
ending point specifies a line number where all the statements have been
removed.
The Source window does display the variables and statements that the optimizer
removed, but you cannot use any Debug Tool commands on those variables or
statements. For example, you cannot list the value of a variable removed by the
optimizer.
Chapter 38. Debugging programs in a production environment 259

Chapter 39. Debugging UNIX System Services programs
You must debug your UNIX System Services programs in remote debug mode
using a remote debugger, or in full-screen mode using a VTAM terminal. If your
program spans more than one process, you must debug it in remote debug mode
using a remote debugger. The remote debugger is available through several
products, including C/C++ Productivity Tools for OS/390. If your program does
not span more than one process, you can debug it in full-screen mode through a
VTAM terminal.
If one or more of the programs you are debugging are in a shared library and you
are using dynamic debugging, you need to assign the environment variable
_BPX_PTRACE_ATTACH a value of YES. This enables Debug Tool to set hooks in the
shared libraries. Programs that have a .so suffix are programs in a shared library.
For more information on how to set environment variables, see your UNIX System
Services documentation.
Debugging MVS POSIX programs

You can debug MVS POSIX programs, including the following types of programs:
v Programs that store source in HFS
v Programs that use POSIX multithreading
v Programs that use fork/exec
v Programs that use asynchronous signals that are handled by the Language
Environment condition handler
To debug MVS POSIX programs in full screen mode or batch mode, the program
must run under TSO or MVS batch. If you want to run your program under the
UNIX SHELL, you must debug in full-screen mode through a VTAM terminal. To
debug any MVS POSIX program that spans more than one process, you must
debug the program in remote debug mode.

Part 7. Debugging complex applications

Chapter 40. Debugging multilanguage applications
To support multiple high-level programming languages (HLL), Debug Tool adapts
its commands to the HLLs, provides interpretive subsets of commands from the
various HLLs, and maps common attributes of data types across the languages. It
evaluates HLL expressions and handles constants and variables.
The topics below describe how Debug Tool makes it possible for you to debug
programs consisting of different languages, structures, conventions, variables, and
methods of evaluating expressions.
A general rule to remember is that Debug Tool tries to let the language itself guide
how Debug Tool works with it.
Related tasks
“Qualifying variables and changing the point of view” on page 267
“Debugging multilanguage applications” on page 271
“Handling conditions and exceptions in Debug Tool” on page 269
Related references
“Debug Tool evaluation of HLL expressions”
“Debug Tool interpretation of HLL variables and constants”
“Debug Tool commands that resemble HLL commands” on page 266
“Coexistence with other debuggers” on page 273
“Coexistence with unsupported HLL modules” on page 274
Debug Tool evaluation of HLL expressions

When you enter an expression, Debug Tool records the programming language in
effect at that time. When the expression is run, Debug Tool passes it to the
language run time in effect when you entered the expression. This run time might
be different from the one in effect when the expression is run.
When you enter an expression that will not be run immediately, you should fully
qualify all program variables. Qualifying the variables assures that proper context
information (such as load module and block) is passed to the language run time
when the expression is run. Otherwise, the context might not be the one you
intended when you set the breakpoint, and the language run time might not
evaluate the expression.
Related references
“Debug Tool evaluation of COBOL expressions” on page 193
“Debug Tool evaluation of PL/I expressions” on page 204
Debug Tool interpretation of HLL variables and constants

Debug Tool supports the use of HLL variables and constants, both as a part of
evaluating portions of your test program and in declaring and using session
variables.
Three general types of variables supported by Debug Tool are:

v Program variables defined by the HLL compiler’s symbol table
v Debug Tool variables denoted by the percent (%) sign
v Session variables declared for a given Debug Tool session and existing only for
the session
HLL variables
Some variable references require language-specific evaluation, such as pointer
referencing or subscript evaluation. Once again, the Debug Tool interprets each
case in the manner of the HLL in question. Below is a list of some of the areas
where Debug Tool accepts a different form of reference depending on the current
programming language:
v Structure qualification
C and C++ and PL/I: dot (.) qualification, high-level to low-level
COBOL: IN or OF keyword, low-level to high-level
v Subscripting
C and C++: name [subscript1][subscript2]...
COBOL and PL/I: name(subscript1,subscript2,...)
v Reference modification
COBOL name(left-most-character-position: length)
HLL constants
You can use both string constants and numeric constants. Debug Tool accepts both
types of constants in C and C++, COBOL, and PL/I.
Debug Tool commands that resemble HLL commands

To allow you to use familiar commands while in a debug session, Debug Tool
provides an interpretive subset of commands for each language. This consists of
commands that have the same syntax, whether used with Debug Tool or when
writing application programs. You use these commands in Debug Tool as though
you were coding in the original language.
Use the SET PROGRAMMING LANGUAGE command to set the current programming
language to the desired language. The current programming language determines
how commands are parsed. If you SET PROGRAMMING LANGUAGE to AUTOMATIC, every
time the current qualification changes to a module in a different language, the
current programming language is automatically updated.
The following types of Debug Tool commands have the same syntax (or a subset of
it) as the corresponding statements (if defined) in each supported programming
language:
Assignment
These commands allow you to assign a value to a variable or reference.
Conditional
These commands evaluate an expression and control the flow of execution
of Debug Tool commands according to the resulting value.
Declarations
These commands allow you to declare session variables.
Looping
These commands allow you to program an iterative or logical loop as a
Debug Tool command.

Multiway
These commands allow you to program multiway logic in the Debug Tool
command language.
In addition, Debug Tool supports special kinds of commands for some languages.
Related references
“Debug Tool commands that resemble C and C++ commands” on page 207
“Debug Tool commands that resemble COBOL statements” on page 187
Qualifying variables and changing the point of view

Each HLL defines a concept of name scoping to allow you, within a single compile
unit, to know what data is referenced when a name is used (for example, if you
use the same variable name in two different procedures). Similarly, Debug Tool
defines the concepts of qualifiers and point of view for the run-time environment
to allow you to reference all variables in a program, no matter how many
subroutines it contains. The assignment x = 5 does not appear difficult for Debug
Tool to process. However, if you declare x in more than one subroutine, the
situation is no longer obvious. If x is not in the currently executing compile unit,
you need a way to tell Debug Tool how to determine the proper x.
You also need a way to change the Debug Tool’s point of view to allow it to
reference variables it cannot currently see (that is, variables that are not within the
scope of the currently executing block or compile unit, depending upon the HLL’s
concept of name scoping).
Related tasks
“Qualifying variables”
“Changing the point of view” on page 268
Qualifying variables
Qualification is a method you can use to specify to what procedure or load module
a particular variable belongs. You do this by prefacing the variable with the block,
compile unit, and load module (or as many of these labels as are necessary),
separating each label with a colon (or double colon following the load module
specification) and a greater-than sign (:>), as follows:
load_name::>cu_name:>block_name:>object
This procedure, known as explicit qualification, lets Debug Tool know precisely
where the variable is.
If required, load_name is the load module name. It is required only when the
program consists of multiple load modules and when you want to change the
qualification to other than the current load module. load_name can be the Debug
Tool variable %LOAD.
If required, cu_name is the compile unit name. The cu_name is required only when
you want to change the qualification to other than the currently qualified compile
unit. cu_name can be the Debug Tool variable %CU.
If required, block_name is the program block name. The block_name is required only
when you want to change the qualification to other than the currently qualified
block. block_name can be the Debug Tool variable %BLOCK.
Chapter 40. Debugging multilanguage applications 267

For PL/I only:
In PL/I, the primary entry name of the external procedure is the same as the
compile unit name. When qualifying to the external procedure, the procedure
name of the top procedure in a compile unit fully qualifies the block. Specifying
both the compile unit and block name results in an error. For example:
LM::>PROC1:>variable
is valid.
LM::>PROC1:>PROC1:>variable
is not valid.
For C++ only:

You must specify the full function qualification including formal parameters
where they exist. For example:
1. For function (or block) ICCD2263() declared as void ICCD2263(void) within
CU "USERID.SOURCE.LISTING(ICCD226)" the correct block specification
for C++ would include the parenthesis () as follows:
qualify block %load::>"USERID.SOURCE.LISTING(ICCD226)":>ICCD2263()
2. For CU ICCD0320() declared as int ICCD0320(signed long int SVAR1, signed
long int SVAR2) the correct qualification for AT ENTRY is:
AT ENTRY "USERID.SOURCE.LISTING(ICCD0320)":>ICCD0320(long,long)
Use the Debug Tool command DESCRIBE CUS to give you the correct BLOCK or
CU qualification needed.
Use the LIST NAMES command to show all polymorphic functions of a given
name. For the example above, LIST NAMES "ICCD0320*" would list all
polymorphic functions called ICCD0320.
You do not have to preface variables in the currently executing compile unit. These
are already known to Debug Tool; in other words, they are implicitly qualified.
In order for attempts at qualifying a variable to work, each block must have a
name. Blocks that have not received a name are named by Debug Tool, using the
form: %BLOCKnnn, where nnn is a number that relates to the position of the block in
the program. To find out the Debug Tool’s name for the current block, use the
DESCRIBE PROGRAMS command.
Related references
“Qualifying variables and changing the point of view in C and C++” on page 222
“Qualifying variables and changing the point of view in COBOL” on page 195
Changing the point of view

The point of view is usually the currently executing block. You can get to
inaccessible data by changing the point of view using the SET QUALIFY command
with the following operand.
load_name::>cu_name:>block_name
Each time you update any of the three Debug Tool variables %CU, %PROGRAM, or
%BLOCK, all four variables (%CU, %PROGRAM, %LOAD, and %BLOCK) are automatically
updated to reflect the new point of view. If you change %LOAD using SET QUALIFY
LOAD, only %LOAD is updated to the new point of view. The other three Debug Tool
variables remain unchanged. For example, suppose your program is currently

suspended at loadx::>cux:>blockx. Also, the load module loadz, containing the
compile unit cuz and the block blockz, is known to Debug Tool. The settings
currently in effect are:
%LOAD = loadx
%CU = cux
%PROGRAM = cux
%BLOCK = blockx
If you enter any of the following commands:
SET QUALIFY BLOCK blockz;
SET QUALIFY BLOCK cuz:>blockz;
SET QUALIFY BLOCK loadz::>cuz:>blockz;
the following settings are in effect:

%LOAD = loadz
%CU = cuz
%PROGRAM = cuz
%BLOCK = blockz
If you are debugging a program that has multiple enclaves, SET QUALIFY can be
used to identify references and statement numbers in any enclave by resetting the
point of view to a new block, compile unit, or load module.
Related tasks
Chapter 42, “Debugging across multiple processes and enclaves,” on page 277
“Changing the point of view in C and C++” on page 223
“Changing the point of view in COBOL” on page 197
Handling conditions and exceptions in Debug Tool

To suspend program execution just before your application would terminate
abnormally, start your application with the following runtime options:
TRAP(ON)
TEST(ALL,*,NOPROMPT,*)
When a condition is signaled in your application, Debug Tool prompts you and
you can then dynamically code around the problem. For example, you can initialize
a pointer, allocate memory, or change the course of the program with the GOTO
command. You can also indicate to Language Environment’s condition handler,
that you have handled the condition by issuing a GO BYPASS command. Be aware
that some of the code that follows the instruction that raised the condition might
rely on data that was not properly stored or handled.
When debugging with Debug Tool, you can (depending on your host system)
either instruct the debugger to handle program exceptions and conditions, or pass
them on to your own exception handler. Programs also have access to Language
Environment services to deal with program exceptions and conditions.
Related tasks
“Handling conditions in Debug Tool” on page 270
“Handling exceptions within expressions (C and C++ and PL/I only)” on page 271

Handling conditions in Debug Tool
You can use either or both of the two methods during a debugging session to
ensure that Debug Tool gains control at the occurrence of HLL conditions.
If you specify TEST(ALL) as a run-time option when you begin your debug session,
Debug Tool gains control at the occurrence of most conditions.
Note: Debug Tool recognizes all Language Environment conditions that are
detected by the Language Environment error handling facility.
You can also direct Debug Tool to respond to the occurrence of conditions by using
the AT OCCURRENCE command to define breakpoints. These breakpoints halt
processing of your program when a condition is raised, after which Debug Tool is
given control. It then processes the commands you specified when you defined the
breakpoints.
There are several ways a condition can occur, and several ways it can be handled.
When a condition can occur

A condition can occur during your Debug Tool session when:
v A C++ application throws an exception.
v A C and C++ application program executes a raise statement.
v A PL/I application program executes a SIGNAL statement.
v The Debug Tool command TRIGGER is executed.
v Program execution causes a condition to exist. In this case, conditions are not
raised at consistency points (the operations causing them can consist of several
machine instructions, and consistency points usually occur at the beginnings and
ends of statements).
v The setting of WARNING is OFF (for C and C++ and PL/I).
When a condition occurs

When an HLL condition occurs and you have defined a breakpoint with associated
actions, those actions are first performed. What happens next depends on how the
actions end.
v Your program’s execution can be terminated with a QUIT command.
v Control of your program’s execution can be returned to the HLL exception
handler, using the GO command, so that processing proceeds as if Debug Tool
had never been invoked (even if you have perhaps used it to change some
variable values, or taken some other action).
v Control of your program’s execution can be returned to the program itself, using
the GO BYPASS command, bypassing any further processing of this exception
either by the user program or the environment.
v PL/I allows GO TO out of block;, so execution control can be passed to some
other point in the program.
v If no circumstances exist explicitly directing the assignment of control, your
primary commands file or terminal is queried for another command.
If, after the execution of any defined breakpoint, control returns to your program
with a GO, the condition is raised again in the program (if possible and still
applicable). If you use a GOTO to bypass the failing statement, you also bypass your
program’s error handling facilities.

Related references
“Language Environment conditions and their C and C++ equivalents” on page 214
“PL/I conditions and condition handling” on page 201
Handling exceptions within expressions (C and C++ and PL/I

only)
When an exception such as division by zero is detected in a Debug Tool
expression, you can use the Debug Tool command SET WARNING to control Debug
Tool and program response. During an interactive Debug Tool session, such
exceptions are sometimes due to typing errors and so are probably not intended to
be passed to the program. If you do not want errors in Debug Tool expressions to
be passed to your program, use SET WARNING ON. Expressions containing such
errors are terminated, and a warning message is displayed.
However, you might want to pass an exception to your program, perhaps to test
an error recovery procedure. In this case, use SET WARNING OFF.
Related tasks
“Using SET WARNING PL/I command with built-in functions” on page 204
Debugging multilanguage applications

Language Environment simplifies the debugging of multilanguage applications by
providing a single run-time environment and interlanguage communication (ILC).
When the need to debug a multilanguage application arises, you can find yourself
facing one of the following scenarios:
v You need to debug an application written in more than one language, where
each language is supported by Language Environment and can be debugged by
Debug Tool.
v You need to debug an application written in more than one language, where not
all of the languages are supported by Language Environment, nor can they be
debugged by Debug Tool.
When writing a multilanguage application, a number of special considerations

arise because you must work outside the scope of any single language. The
Language Environment initialization process establishes an environment tailored to
the set of HLLs constituting the main load module of your application program.
This removes the need to make explicit calls to manipulate the environment. Also,
termination of the Language Environment environment is accomplished in an
orderly fashion, regardless of the mixture of HLLs present in the application.
Related tasks
“Debugging an application fully supported by Language Environment”
Debugging an application fully supported by Language

Environment
If you are debugging a program written in a combination of languages supported
by Language Environment and compiled by supported compilers, very little is
required in the way of special actions. Debug Tool normally recognizes a change in
programming languages and automatically switches to the correct language when

a breakpoint is reached. If desired, you can use the SET PROGRAMMING LANGUAGE
command to stay in the language you specify; however, you can only access
variables defined in the currently set programming language.
When defining session variables you want to access from compile units of different
languages, you must define them with compatible attributes.
Related tasks
“Using session variables across different languages”
Related references
Debugging an application partially supported by Language

Environment
Sometimes you might find yourself debugging applications that contain compile
units written in languages not supported by either Debug Tool or Language
Environment. For example, you can run programs containing mixtures of
Assembler, C and C++, COBOL, FORTRAN, and PL/I source code with Debug
Tool. You can invoke Debug Tool and perform testing only for the sections of a
multilanguage program written in a supported language and compiled with a
Language Environment-enabled compiler, or relink-edited to take advantage of
Language Environment library routines. If you are debugging a compile unit
written in a supported language and the compile unit calls another unsupported
language, a breakpoint set with AT CALL is triggered. Debug Tool determines the
name of the compile unit, but little else. Your compile unit runs unhindered by
Debug Tool. When program execution returns to a compile unit of a known HLL,
Debug Tool once again gains control and execute commands.
Related tasks
Chapter 32, “Debugging a disassembled program,” on page 235
Using session variables across different languages

While working in one language, you can declare session variables that you can
continue to use after calling in a load module of a different language. The table
below shows how the attributes of session variables are mapped across
programming languages. Session variables with attributes not shown in the table
cannot be accessed from other programming languages. (Some attributes supported
for C and C++ or PL/I session variables cannot be mapped to other languages;
session variables defined with these attributes cannot be accessed outside the
defining language. However, all of the supported attributes for COBOL session
variables can be mapped to equivalent supported attributes in C and C++ and
PL/I, so any session variable that you declare with COBOL can be accessed from C
and C++ and PL/I.)
Machine attributes PL/I attributes C and C++ attributes COBOL attributes Assembler and
disassembly
attributes
byte CHAR(1) unsigned char PICTURE X DS X or
DS C
byte string CHAR(j) unsigned char[j] PICTURE X(j) DS XLj or
DS CLj
halfword FIXED BIN(15,0) signed short int PICTURE S9(j≤4) DS H
USAGE BINARY

Machine attributes PL/I attributes C and C++ attributes COBOL attributes Assembler and
disassembly
attributes
fullword FIXED BIN(31,0) signed long int PICTURE S9(4<j≤9) DS F
USAGE BINARY
floating point FLOAT BIN(21) or float USAGE COMP-1 DS E
FLOAT DEC(6)
long floating point FLOAT BIN(53) or double USAGE COMP-2 DS D
FLOAT DEC(16)
extended floating FLOAT BIN(109) or long double n/a DS L
point FLOAT DEC(33)
fullword pointer POINTER * USAGE POINTER DS A
Note: When registering session variables in PL/I, the DECIMAL type is always the
default. For example, if C declares a float, PL/I registers the variable as a
FLOAT DEC(6) rather than a FLOAT BIN(21).
When declaring session variables, remember that C and C++ variable names are
case-sensitive. When the current programming language is C and C++, only
session variables that are declared with uppercase names can be shared with
COBOL or PL/I. When the current programming language is COBOL or PL/I,
session variable names in mixed or lowercase are mapped to uppercase. These
COBOL or PL/I session variables can be declared or referenced using any mixture
of lowercase and uppercase characters and it makes no difference. However, if the
session variable is shared with C and C++, within C and C++, it can only be
referred to with all uppercase characters (since a variable name composed of the
same characters, but with one or more characters in lowercase, is a different
variable name in C and C++).
Session variables with incompatible attributes cannot be shared between other

programming languages, but they do cause session variables with the same names
to be deleted. For example, COBOL has no equivalent to PL/I’s FLOAT DEC(33) or
C’s long double. With the current programming language COBOL, if a session
variable X is declared PICTURE S9(4), it will exist when the current programming
language setting is PL/I with the attributes FIXED BIN(15,0) and when the current
programming language setting is C with the attributes signed short int. If the
current programming language setting is changed to PL/I and a session variable X
is declared FLOAT DEC(33), the X declared by COBOL will no longer exist. The
variable X declared by PL/I will exist when the current programming language
setting is C with the attributes long double.
Related references
“Debug Tool interpretation of HLL variables and constants” on page 265
Coexistence with other debuggers

Debug Tool can coexist with low-level debugging facilities, such as TSO TEST.
However, coexistence with other HLL debuggers cannot be guaranteed.
C, C++, COBOL, and PL/I are dependent upon Language Environment to provide
debugging information.

Another debugger might provide limited services for an HLL not yet supported by
Debug Tool, but conditions such as attention interrupts and exceptions cause
Language Environment to pass control to an installed Language Environment
debugger.
Related references
“Coexistence with unsupported HLL modules”
Coexistence with unsupported HLL modules

Compile units or program units written in unsupported high- or low-level
languages, or in older releases of HLLs, are tolerated. See Using CODE/370 with VS
COBOL II and OS PL/I for information about two unsupported HLLs that can be
used with Debug Tool.
Related references
“Coexistence with other debuggers” on page 273

Chapter 41. Debugging multithreading programs
You can run your multithreading programs with Debug Tool. When more than one
task is involved in your program, Debug Tool might be started by any or all of
them. Because conflicting use of the terminal or log file, for example, could occur if
Debug Tool is operating on multiple tasks, its use is single-threaded. So, if your
program runs as two tasks (task A and task B) and task A calls Debug Tool, Debug
Tool accepts the request and begins operating on behalf of task A. If, during that
period, task B calls Debug Tool, the request from task B is held until the request
from task A is complete (for example, you issued a STEP or GO command). Debug
Tool is then released and can accept any pending invocation.
Restrictions when debugging multithreading applications

v Debugging applications that create another process is constrained because both
processes compete for the use of the terminal.
v Only the variables and symbol information for compile units in the task that is
being debugged are accessible.
v The LIST CALL command provides a traceback of the compile units only in the
current task.
Related references

Chapter 42. Debugging across multiple processes and
enclaves
There is a single Debug Tool session across all enclaves in a process. Breakpoints
set in one process are restored when the new process begins in the new session.
In full-screen mode or batch mode, you can debug a non-POSIX program that
spans more than one process, but Debug Tool can be active in only one process. In
remote debug mode, you can debug a POSIX program that spans more than one
process. The remote debugger can display each process.
When you are recording the statements that you run, data collection persists across
multiple enclaves until you stop recording. When you replay your statements, the
data is replayed across the enclave boundaries in the same order as they were
recorded.
A commands file continues to execute its series of commands regardless of what

level of enclave is entered.
Related tasks
“Starting Debug Tool within an enclave”
“Viewing Debug Tool windows across multiple enclaves”
“Using breakpoints within multiple enclaves” on page 278
“Ending a Debug Tool session within multiple enclaves” on page 278
“Using Debug Tool commands within multiple enclaves” on page 278
Starting Debug Tool within an enclave

After an enclave in a process activates Debug Tool, it remains active throughout
subsequent enclaves in the process, regardless of whether the run-time options for
the enclave specify TEST or NOTEST. Debug Tool retains the settings specified from
the TEST run-time option for the enclave that activated it, until you modify them
with SET TEST. If your Debug Tool session includes more than one process, the
settings for TEST are reset according to those specified on the TEST run-time option
of the first enclave that activates Debug Tool in each new process.
If Debug Tool is first activated in a nested enclave of a process, and you step or go
back to the parent enclave, you can debug the parent enclave. However, if the
parent enclave contains COBOL but the nested enclave does not, Debug Tool is not
active for the parent enclave, even upon return from the child enclave.
Upon activation of Debug Tool, the initial commands string, primary commands
file, and the preferences file are run. They run only once, and affect the entire
Debug Tool session. A new primary commands file cannot be started for a new
enclave.
Viewing Debug Tool windows across multiple enclaves

When an enclave starts another enclave, the Source or Listing windows and their
related windows (Compact Source, Local Breakpoint, and Local Monitor windows)
of the first enclave are hidden. You cannot open a Source or Listing window for a
compile unit unless that compile unit is in the current enclave.

Using breakpoints within multiple enclaves
When any process is initialized, a termination breakpoint is automatically defined
for the main enclave and each child enclave created by the process while it runs.
Unless you clear or disable this breakpoint, the termination breakpoint is triggered
as each enclave terminates, including the main enclave. Enter the GO or STEP
commands after the first termination breakpoint is encountered to cause your
program to continue running all the child enclaves until the main enclave is
terminated.
Ending a Debug Tool session within multiple enclaves

You cannot specify NOPROMPT as the third suboption in the TEST run-time option for
the next process on the host. This restriction ensures that STATEMENT/LINE, ENTRY,
EXIT, and LABEL breakpoints are properly restored when the next process starts. If
you have not used these breakpoint types, you can specify NOPROMPT.
In a single enclave, QUIT closes Debug Tool.
In a nested enclave, however, QUIT causes Debug Tool to signal a severity 3

condition that corresponds to Language Environment message CEE2529S. The
system is trying to cleanly terminate all enclaves in the process.
Normally, the condition causes the current enclave to terminate. Then, the same
condition will be raised in the parent enclave, which will also terminate. This
sequence continues until all enclaves in the process have been terminated. As a
result, you will see a CEE2529S message for each enclave that is terminated.
For CICS and MVS only: Depending on Language Environment run-time settings,
the application might be terminated with an ABEND 4038. This termination is
normal and should be expected.
Using Debug Tool commands within multiple enclaves

Some Debug Tool commands and variables have a specific scope for enclaves and
processes. The table below summarizes the behavior of specific Debug Tool
commands and variables when you are debugging an application that consists of
multiple enclaves.
Affects entire
Affects current Debug Tool
Debug Tool command enclave only session Comments
%CAAADDRESS X
AT GLOBAL X
AT TERMINATION X
CLEAR AT X X In addition to clearing breakpoints set in the
current enclave, CLEAR AT can clear global
breakpoints.
CLEAR DECLARE X
CLEAR VARIABLES X
Declarations X Session variables are cleared at the termination of
the process in which they were declared.

Affects entire
DISABLE X X In addition to disabling breakpoints set in the
current enclave, DISABLE can disable global
breakpoints.
ENABLE X X In addition to enabling breakpoints set in the
current enclave, ENABLE can enable global
breakpoints.
LIST AT X X In addition to listing breakpoints set in the
current enclave, LIST AT can list global
breakpoints.
LIST CALLS X Applies to all systems except MVS batch and
MVS with TSO. Under MVS batch and MVS with
TSO, LIST CALLS lists the call chain for the current
active thread in the current active enclave.
For programs containing interlanguage

communication (ILC), routines from previous
enclaves are only listed if they are coded in a
language that is active in the current enclave.
Note: Only compile units in the current thread
will be listed for PL/I multitasking applications.
LIST EXPRESSION X You can only list variables in the currently active
thread.
LIST LAST X
LIST NAMES CUS X Applies to compile unit names. In the Debug
Frame window, compile units in parent enclaves
are marked as deactivated.
LIST NAMES TEST X Applies to Debug Tool session variable names.
MONITOR GLOBAL X Applies to Global monitors.
PLAYBACK ENABLE X The PLAYBACK command that informs Debug Tool
to begin the recording session.
PLAYBACK DISABLE X The PLAYBACK command that informs Debug Tool
to stop the recording session.
PLAYBACK START X The PLAYBACK command that suspends execution
of the program and indicates to Debug Tool to
enter replay mode.
PLAYBACK STOP X The PLAYBACK command that terminates replay
mode and resumes normal execution of Debug
Tool.
PLAYBACK BACKWARD X The PLAYBACK command that indicates to Debug
Tool to perform STEP and RUNTO commands
backward, starting from the current point and
going to previous points.
PLAYBACK FORWARD X The PLAYBACK command that indicates to Debug
Tool to perform STEP and RUNTO commands
forward, starting from the current point and
going to the next point.
PROCEDURE X
1
SET AUTOMONITOR X Controls the monitoring of data items at the
currently executing statement.
Chapter 42. Debugging across multiple processes and enclaves 279

Affects entire
1
SET COUNTRY X This setting affects both your application and
Debug Tool.
At the beginning of an enclave, the settings are

those provided by Language Environment or your
operating system. For nested enclaves, the
parent’s settings are restored upon return from a
child enclave.
SET EQUATE1 X
SET INTERCEPT1 X For C, intercepted streams or files cannot be part
of any C I/O redirection during the execution of a
nested enclave. For example, if stdout is
intercepted in program A, program A cannot then
redirect stdout to stderr when it does a system()
call to program B. Also, not supported for PL/I.
SET NATIONAL LANGUAGE1 X This setting affects both your application and
Debug Tool.
At the beginning of an enclave, the settings are

those provided by Language Environment or your
operating system. For nested enclaves, the
parent’s settings are restored upon return from a
child enclave.
SET PROGRAMMING LANGUAGE1 X Applies only to programming languages in which
compile units known in the current enclave are
written (a language is "known" the first time it is
entered in the application flow).
SET QUALIFY1 X Can only be issued for load modules, compile
units, and blocks that are known in the current
enclave.
SET TEST1 X
2
TRIGGER condition X Applies to triggered conditions.2 Conditions can
be either an Language Environment symbolic
feedback code, or a language-oriented keyword or
code, depending on the current programming
language setting.
TRIGGER AT X X In addition to triggering breakpoints set in the
current enclave, TRIGGER AT can trigger global
breakpoints.
Notes:
1. SET commands other than those listed in this table affect the entire Debug Tool
session.
2. If no active condition handler exists for the specified condition, the default
condition handler can cause the program to end prematurely.

Chapter 43. Debugging a multiple-enclave interlanguage
communication (ILC) application
When you debug a multiple-enclave ILC application with Debug Tool, use the SET
PROGRAMMING LANGUAGE to change the current programming language setting. The
programming language setting is limited to the languages currently known to
Debug Tool (that is, languages contained in the current load module).
Command lists on monitors and breakpoints have an implied programming

language setting, which is the language that was in effect when the monitor or
breakpoint was established. Therefore, if you change the language setting, errors
might result when the monitor is refreshed or the breakpoint is triggered.
Debug Tool sets implicit AT TERMINATION breakpoint by default. This breakpoint

gives Debug Tool control at the end of each enclave. If you want a
multiple-enclave application to run (using the GO command) without stopping at
the termination breakpoint, remove the breakpoint with CLEAR AT TERMINATION.
You can set the AT LOAD breakpoint to give Debug Tool control at the specific
program you want to debug.
For example, consider a CICS application that has five programs called PROG1 to
PROG5 and uses EXEC CICS LINK or EXEC CICS XCTL to pass control between
them. If you want to run the application until PROG4 begins, enter the following
commands:
CLEAR AT TERMINATION
AT LOAD PROG4
GO

Part 8. Appendixes

Appendix A. Data sets used by Debug Tool
Debug Tool uses the following data sets:
C and C++ source
This data set is used as input to the compiler, and must be kept in a
permanent PDS member, sequential file, or HFS file. The data set must be a
single file, not a concatenation of files. Debug Tool uses the data set to
show you the program as it is executing.
The C and C++ compilers store the name of the source data set inside the
load module. Debug Tool uses this data set name to access the source.
This data set might not be the original source; for example, the program
might have been preprocessed by the CICS translator. If you use a
preprocessor, you must keep the data set input to the compiler in a
permanent data set for later use with Debug Tool.
As this data set might be read many times by Debug Tool, we recommend
that you do one of the following:
v Define it with the largest block size that your DASD can hold.
v Instruct the system to compute the optimum block size, if your system
has that capability.
COBOL listing
This data set is produced by the compiler and must be kept in a
permanent PDS member, sequential file, or HFS file. Debug Tool uses it to
The COBOL compiler stores the name of the listing data set inside the load
module. Debug Tool uses this data set name to access the listing.
Debug Tool does not use the output that is created by the COBOL LIST
compiler option.
COBOL programs that have been compiled with the SEPARATE suboption
do not need to save the listing file. Instead, you must save the separate
debug file SYSDEBUG.
The VS COBOL II compilers do not store the name of the listing data set.
Debug Tool creates a name in the form userid.cuname.LIST and uses that
name to find the listing.
Because this data set might be read many times by Debug Tool, we
recommend that you do one of the following:
v Instruct the system to compute the optimum blocksize, if your system
EQALANGX file
Debug Tool uses this data set to obtain debug information about assembler
source files. It can be a permanent PDS member or sequential file. You
must create it before you start Debug Tool. You can create it by using the
EQALANGX program. Use the SYSADATA output from the High Level
assembler as input to the EQALANGX program.
PL/I source (Enterprise PL/I only)
This data set is used as input to the compiler, and must be kept in a

permanent PDS member, sequential file, or HFS file. Debug Tool uses it to
The Enterprise PL/I compiler stores the name of the source data set inside
the load module. Debug Tool uses this data set name to access the source.
This data set might not be the original source; for example, the program
might have been preprocessed by the CICS translator. If you use a
preprocessor, you must keep the data set input to the compiler in a
permanent data set, for later use with Debug Tool.
PL/I listing (all other versions of PL/I compiler)
This data set is produced by the compiler and must be kept in a
permanent file. Debug Tool uses it to show you the program as it is
executing.
The PL/I compiler does not store the name of the listing data set. Debug
Tool looks for the listing in a data set with the name in the form of
userid.cuname.LIST.
Debug Tool does not use the output that is created by the PL/I compiler
LIST option; performance improves if you specify NOLIST.
Separate debug file
This data set is produced by the compiler when you compile your program
with the SEPARATE compiler suboption of the TEST compiler option. It
should be kept in a permanent PDS member, sequential file, or HFS file.
The SEPARATE compiler suboption is available on the following compilers:
The COBOL compiler stores the data set name of the separate debug file
inside the load module. Debug Tool uses this data set name to access the
listing and other debug data, such as the symbol table. The DD name used
by the COBOL compiler for the separate debug file is SYSDEBUG.
Preferences file

This data set contains Debug Tool commands that customize your session.
You can use it, for example, to change the default screen colors set by
Debug Tool. It should be kept in a permanent PDS member or a sequential
file.
The default DD name for the Debug Tool preferences file is INSPPREF.
Preferences files are not used in remote debug mode.
Commands file
This data set contains Debug Tool commands that control the debug
session. You can use it, for example, to set breakpoints or set up monitors
for common variables. It should be kept in a permanent PDS member or a
sequential file.
The default DD name for the Debug Tool commands file is INSPIN.
Commands files are not used in remote debug mode.
Log file
Debug Tool uses this file to record the progress of the debugging session.
The results of the execution of commands are saved as comments. This
allows you to use the log file as a commands file in subsequent debugging
sessions. It should be kept in a permanent PDS member or a sequential
file. As this data set is written to by Debug Tool, we recommend you use a
sequential file to relieve any contentions for this file.
The default DD name for the Debug Tool log file is INSPLOG.
Log files are not used in remote debug mode.
Save file
Debug Tool uses this file to store preference settings such as screen colors
and panel layouts at the end of each session. These settings are then
restored at the start of subsequent sessions. It should be kept in a
permanent PDS member or a sequential file. As this data set is written to
by Debug Tool, we recommend you use a sequential file to relieve any
contentions for this file. The file must have a record format of Fixed and a
record length of 80.
The default DD name for the Debug Tool save file is INSPSAFE.
Save files are not used for remote debug sessions.
Save files are not used under CICS.
Related references
“Format for a COBOL source listing and debug file” on page 187
Appendix A. Data sets used by Debug Tool 287

Appendix B. How does Debug Tool locate debug information
and source or listing files?
Debug Tool obtains information (called debug information) it needs about a
compilation unit (CU) by searching through the following sources:
1. In most cases, the debug information is found in the load module. In
conjunction with this information, Debug Tool uses the information in the
source or listing file to display source code on the screen.
2. For COBOL CUs compiled with the SEPARATE suboption of the TEST compiler
option, Debug Tool uses the information stored in a separate file (called a side
file) that contains both the debug information and the information needed to
display source code on the screen.
3. For assembler CUs, Debug Tool uses the information stored in a separate file
(called an EQALANGX file) that contains both the debug information and the
information needed to display source code on the screen.
In all of these cases, there is a default data set name associated with each CU. This
name is either the name of the data set where the compiler processed the source,
listing, or side file or a name constructed from the CU name. The way this default
name is generated differs depending on the source language and compiler used.
See Appendix A, “Data sets used by Debug Tool,” on page 285 for a description of
this default name and how it is generated for each language and compiler.
The source or listing data, side file data, or EQALANGX data is obtained from one
of the following sources:
v the default data set name
v the SET SOURCE command
v the SET DEFAULT LISTINGS command
v the EQADEBUG DD statement
The order in which these are located is different for each type of file. For the
default data set name and the SET DEFAULT LISTINGS command, the EQAUEDAT
user exit might modify the data set name before the file is opened. However, if a
EQADEBUG DD statement in present, the EQAUEDAT user exit is not run.
How does Debug Tool locate source and listing files?

Debug Tool reads the source or listing file for a CU each time it needs to display
information about that CU. While you are debugging your CU, the data set from
which the file is read can change. Each time Debug Tool needs to read a source or
listing file, it searches for the data set in the following order:
1. SET SOURCE command
2. SET DEFAULT LISTINGS command. If the EQAUEDAT user exit is implemented
and a EQADEBUG DD statement is not specified, the data set name might be
modified by the EQAUEDAT user exit.
3. if present, the EQADEBUG DD statement
4. default data set name. If the EQAUEDAT user exit is implemented and a
EQADEBUG DD statement is not specified, the data set name might be

How does Debug Tool locate COBOL side files?
Debug Tool might read from a COBOL side file more than once but it always reads
the side file from the same data set. After Debug Tool locates a valid side file, you
cannot direct Debug Tool to a different side file. When the CU first appears, Debug
Tool looks for the side file in the following order:
4. if present, the EQADEBUG DD statement
The SET SOURCE command can be entered only after the CU name appears as a CU
and the side file is not found in any of the other location. The SET DEFAULT
LISTINGS command can be entered at any time before the CU name appears as a
CU or, if the side file is not found in any of the other possible locations, it can be
entered later.
How does Debug Tool locate EQALANGX files

An EQALANGX file, which contains debug information for an assembler program,
might be read more than once but it is always read from the same data set. After
Debug Tool locates a valid EQALANGX file, you cannot direct Debug Tool to a
different EQALANGX file. After you enter the LOADDEBUGDATA (LDD) command,
Debug Tool looks for the EQALANGX file in the following order:
4. the EQADEBUG DD statement
The SET SOURCE command can be entered any time after the CU name appears as a
disassembly CU or, if the EQALANGX file is not found by the LDD command, after
you enter the LDD command. The SET DEFAULT LISTINGS command can be entered
any time before you enter the LDD command or, if the EQALANGX file is not
found by the LDD command, after you enter the LDD command.

Appendix C. Examples: Preparing programs and modifying
setup files with Debug Tool Utilities
These examples show you how to use Debug Tool Utilities to prepare your
programs and how to create, manage, and use a setup file. The examples guide
you through the following tasks:
1. Creating personal data sets with the correct attributes.
2. Starting Debug Tool Utilities.
3. Compiling or assembling your program by using Debug Tool Utilities. You
must have Debug Tool Utilities and Advanced Functions installed on your
system to run the steps in this task. If you do not have this product installed,
you can build your program through your usual methods and resume this
example with the next step.
4. Modifying and using a setup file to run your program in the foreground or in
batch.
Creating personal data sets

Create the data sets with the names and attributes described below. Allocate 5
tracks for each of the data sets. Partitioned data sets should be specified with 5
blocks for the directory.
Table 8. Names and attributes to use when you create your own data
sets.
Data set name LRECL BLKSIZE RECFM DSORG
prefix.SAMPLE.COBOL 80 * FB PO
prefix.SAMPLE.PLI 80 * FB PO
prefix.SAMPLE.C 80 * FB PO
prefix.SAMPLE.ASM 80 * FB PO
prefix.SAMPLE.DTSF 1280 * VB PO
* You can use any block size that is valid.
Copy the following members of the hlq.SEQASAMP data set into the personal data
sets you just created:
SEQASAMP member name Your sample data set Description of member

EQAWPP1 prefix.SAMPLE.COBOL(WPP1) COBOL source code
EQAWPP3 prefix.SAMPLE.PLI(WPP3) PL/I source code
EQAWPP4 prefix.SAMPLE.C(WPP4) C source code
EQAWPP5 prefix.SAMPLE.ASM(WPP5) Assembler source code
EQAWSU1 prefix.SAMPLE.DTSF(WSU1) setup file for EQAWPP1

Starting Debug Tool Utilities
To start Debug Tool Utilities, do one the following options:
v If Debug Tool Utilities was installed as an option on an existing ISPF panel, then
select that option.
v If Debug Tool Utilities data sets were installed as part of your log on procedure,
enter the following command from ISPF option 6:
EQASTART
v If Debug Tool Utilities was installed as a separate application, enter the
following command from ISPF option 6:
EX ’hlq.SEQAEXEC(EQASTART)’
The Debug Tool Utilities primary panel (EQA@PRIM) is displayed. On the

command line, enter the PANELID command. This command displays the name of
each panel on the upper left corner of the screen. These names are used as
navigation aids in the instructions provided in this section. After you complete
these examples, you can stop the display of these names by entering the PANELID
command.
Compiling or assembling your program by using Debug Tool Utilities

To do the steps in this task, you must have Debug Tool Utilities and Advanced
Functions installed on your system. To compile your program, do the following
steps:
1. In panel EQA@PRIM, select 1. Press Enter.
2. In panel EQAPP, select one of the following option and then press Enter.
v 1 to compile a COBOL program.
v 3 to compile a PL/I program
v 4 to compile a C or C++ program
v 5 to assemble an assembler program
3. One of the following panels is displayed, depending on the language you
selected in step 2:
v EQAPPC1 for COBOL programs. Enter the following information in the
fields indicated:
– Project = prefix
– Group= SAMPLE
– Type=COBOL
– Member=WPP1
v EQAPPC3 for PL/I programs.
– Group= SAMPLE
– Type=PLI
– Member=WPP3
v EQAPPC4 for C and C++ programs.
– Group= SAMPLE
– Type=C
– Member=WPP4
v EQAPPC5 for assembler programs.

– Group= SAMPLE
– Type=ASM
– Member=WPP5
4. If you are preparing an assembler program, enter the location of your CEE
library in the Syslib data set Name field. For example: ’CEE.SCEEMAC’
5. Enter ’/’ to edit options and specify a naming pattern for the output data sets
in the field Data set naming pattern. Press Enter.
selected in step 2 on page 292:
v EQAPPC1A for COBOL programs.
v EQAPPC3A for PL/I programs.
v EQAPPC4A for C and C++ programs.
v EQAPPC5A for assembler programs.
Look at the panel to review the following information:
v test compiler options
v naming patterns for output data sets
Press PF3 (Exit).
v EQAPPC1 for COBOL programs.
Select "F" to process these programs in the foreground. Specify "N" for CICS
translator and "N" for DB2 precompiler. None of these programs contain CICS
or DB2 instructions. Press Enter.
v EQAPPC1B for COBOL programs.
v EQAPPC3B for PL/I programs.
v EQAPPC4B for C and C++ programs.
v EQAPPC5B for assembler programs.
Make a note of the data set name for Object compilation output. For a COBOL
program, the data set name will look similar to the following name:
prefix.SAMPLE.OBJECT(WPP1). You will use this name when you link your
object modules. Press Enter.
9. If panel EQAPPA1 is displayed, press Enter.
v EQAPPC1C for COBOL programs.
v EQAPPC3C for PL/I programs.
v EQAPPC4C for C and C++ programs.
v EQAPPC5C for assembler programs.
Check for a 0 or 4 return code. Type a "b" in the Listing field. Press Enter.
Appendix C. Examples: Preparing programs and modifying setup files with Debug Tool Utilities 293
11. In panel ISRBROBA, browse the file to review the messages. When you are
done reviewing the messages, press PF3 (Exit).
v EQAPPC1C for COBOL programs.
v EQAPPC3C for PL/I programs.
v EQAPPC4C for C and C++ programs.
v EQAPPC5C for assembler programs.
Press PF3 (Exit).
v EQAPPC1B for COBOL programs.
v EQAPPC3B for PL/I programs.
v EQAPPC4B for C and C++ programs.
v EQAPPC5B for assembler programs.
Press PF3 (Exit).
v EQAPPC1 for COBOL programs.
Press PF3 (Exit).
15. In panel EQAPP, press PF3 (Exit) to return to EQA@PRIM panel.
To link your object modules, do the following steps:

2. In panel EQAPP, select L. Press Enter.
3. In panel EQAPPCL, specify "F" to process the programs in the foreground.
Then, choose one of the following options, depending on the language you
v For the COBOL program, use the following values for each field: Project =
prefix, Group= SAMPLE, Type=OBJECT, Member=WPP1
v For the PL/I program, use the following values for each field: Project =
prefix, Group= SAMPLE, Type=OBJECT, Member=WPP3
v For the C program, use the following values for each field: Project = prefix,
Group= SAMPLE, Type=OBJECT, Member=WPP4
v For the assembler program, use the following values for each field: Project
= prefix, Group= SAMPLE, Type=OBJECT, Member=WPP5
4. In panel EQAPPCL, specify the name of the other libraries you need to link to
your program. For example, in the field Syslib data set Name, specify the
prefix of your CEE library: ’CEE.SCEELKED’. Press Enter.
5. In panel EQAPPCLB, make a note of the data set name in the Load link-edit
output field. You will use this name when you modify a setup file. Press
Enter.
6. If panel EQAPPA1 is displayed, press Enter.
7. In panel EQAPPCLC, check for a 0 return code. Type a "V" in the Listing field.
Press Enter.

8. In panel ISREDDE2, review the messages. After you review the messages,
press PF3 (Exit).
9. In panel EQAPPCLC, press PF3 (Exit).
10. In panel EQAPPCLB, press PF3 (Exit).
11. In panel EQAPPCL, press PF3 (Exit).
12. In panel EQAPP, press PF3 (Exit) to return to EQA@PRIM panel.
Modifying and using a setup file

This example describes how to modify a setup file and then use it to run the
examples in the TSO foreground or run the examples in the background by
submitting a MVS batch job.
Run the program in foreground

To modify and run the setup file so your program runs in the foreground, do the
following steps:
2. In panel EQAPFOR, select one of the following choices, depending on which
language you selected in step 2 on page 292:
prefix, Group= SAMPLE, Type=DTSF, Member = WSU1
prefix, Group = SAMPLE, Type=DTSF, Member=WSU3
Group= SAMPLE, Type=DTSF, Member=WSU4
v For the assembler program, use the following values for each field: Project =
prefix, Group= SAMPLE, Type=DTSF, Member=WSU5
Press Enter.
3. In panel EQAPFORS, do the following steps:
a. Replace &LOADDS. with the name of the load data set from step 5 on page
294 of instructions on how to link the object modules.
b. Replace &EQAPRFX. with the prefix your EQAW (Debug Tool) library.
c. Replace &CEEPRFX. with the prefix your CEE (Language Environment)
library.
d. Enter "e" in Cmd field next to CMDS DD name. In the window that is
displayed, if there is a QUIT ; statement at the end of the data set, remove
it. Press PF3 (Exit).
e. Type "run" in command line. Press Enter.
4. Debug Tool is started and the Debug Tool window is displayed. Enter any
valid Debug Tool commands to verify that you can debug the program. Enter
"qq" in the command line to stop Debug Tool and close the Debug Tool
window.
5. In panel EQAPFORS, check the return code message:
v For the COBOL program, the return code (RC) is 0.
v For the PL/I program, the return code (RC) is 1000.
v For the C program, the return code (RC) is 0.
v For the assembler program, the return code (RC) is 0.
Press PF3 (Exit). All the changes made to the setup file are saved.
6. In panel EQAPFOR, press PF3 (Exit) to return to the panel EQA@PRIM.
Appendix C. Examples: Preparing programs and modifying setup files with Debug Tool Utilities 295
Run the program in batch
To modify and run the setup file so that the program runs in batch, do the
following steps:
2. In panel EQAPDEF, review the job card information. If there are any changes
that need to be made, make them. Press PF3 (Exit).
4. In panel EQAPFOR, select one of the following choices, depending on which
language you selected in step 2 on page 292:
prefix, Group = SAMPLE, Type = DTSF, Member =WSU1
prefix, Group = SAMPLE, Type = DTSF, Member =WSU3
Group = SAMPLE, Type = DTSF, Member = WSU4
v For the assembler program, use the following values for each field: Project
= prefix, Group = SAMPLE, Type = DTSF, Member = WSU5
Press Enter.
5. If you ran the steps beginning on page 295 (running the program in
foreground), you can skip this step. In panel EQAPFORS, do the following
steps:
a. Replace &LOADDS. with the name of the load data set from step 5 on page
294 of instructions on how to link the object modules.
b. Replace &EQAPRFX. with the prefix your EQAW (Debug Tool) library.
c. Replace &CEEPRFX. with the prefix your CEE (Language Environment)
library.
6. Enter "e" in the Cmd field next to CMDS DD name. If there is not ’QUIT ;’
statement at the end of the data set, then add the statement. Press PF3 (Exit).
7. Type submit in command line. Press Enter.
8. In panel ISREDDE2, type submit in the command line. Press Enter. Make a
note of the job number that is displayed.
9. In panel ISREDDE2, press PF3 (Exit).
10. In panel EQAPFORS, press PF3 (Exit). The changes you made to the setup file
are saved.
11. In panel EQAPFOR, press PF3 (Exit) to return to EQA@PRIM panel. locate the
job output using the job number recorded. Check for zero return code and the
command log output at the end of the job output.

Appendix D. Notes on debugging in batch mode
Debug Tool can run in batch mode, creating a noninteractive session.
In batch mode, Debug Tool receives its input from the primary commands file, the
USE file, or the command string specified in the TEST run-time option, and writes
its normal output to a log file.
Note: You must ensure that you specify a log data set.
Commands that require user interaction, such as PANEL, are invalid in batch mode.
You might want to run a Debug Tool session in batch mode if:
v You want to restrict the processor resources used. Batch mode generally uses
fewer processor resources than interactive mode.
v You have a program that might tie up your terminal for long periods of time.
With batch mode, you can use your terminal for other work while the batch job
is running.
v You are debugging an application in its native batch environment, such as
MVS/JES or CICS batch.
When Debug Tool is reading commands from a specified data set or file and no
more commands are available in that data set or file, it forces a GO command until
the end of the program is reached.
When debugging in batch mode, use QUIT to end your session.
Related tasks
“Starting Debug Tool in batch” on page 81

Appendix E. Notes on debugging in remote debug mode
Debug Tool can run in remote debug mode, by using TCP/IP to connect to a
remote debugger installed on your workstation. If you are using the VisualAge
Remote Debugger or IBM Distributed Debugger, which is shipped with most
VisualAge products, you must specify the VADTCPIP& suboption of the TEST
run-time option when you start your program. If you are using the Compiled
language debugger, which is shipped with WebSphere Studio Enterprise Developer,
you must specify the TCPIP& suboption of the TEST run-time option.
When you use the TCPIP& suboption, verify that the port ID you specify matches
the port number being used by the remote debugger (Compiled language
debugger). The default port number that the Compiled language debugger uses is
8001 and the default port number that Debug Tool uses is 8000. To make the port
numbers match, use 8001 as the port number in your TEST run-time options string.
For example, TEST(ALL,’*’,PROMPT,’TCPIP&8001:’)
When you use the VADTCPIP& suboption, consider the following possible errors:
v The tcpip_workstation_id or port_id parameters must be syntactically and
functionally correct. If they are not and you try to start a remote debug mode
session, Debug Tool starts a full-screen mode session. For example, if you try to
start a remote debug mode session from TSO or a CICS program by using
incorrect parameters, a full-screen mode session is displayed on your 3270 type
terminal. This error is recorded in the MVS SDSF log as an allocation failure.
v If the tcpip_workstation_id or port_id parameters are not syntactically and
functionally correct and you try to debug batch program, Debug Tool terminates
and the batch program runs as though no debug session was started. This error
occurs when, for example, you run a JES batch job or CICS batch transaction.
This error is recorded in the MVS SDSF log as an allocation failure.
v If your z/OS or OS/390 environment is not using the default TCP/IP data set
named TCPIP.TCPIP.DATA and you try to start a remote debug mode session to
debug a batch program, Debug Tool terminates. The batch program runs as
though no debug session was started. This error is recorded in the MVS SDSF
log as an allocation error.
To fix this error, specify the SYSTCPD DDNAME with the appropriate TCP/IP
data set name. For example,
//SYSTCPD DD DISP=SHR,DSN=MY.TCPIP.DATA
v For TCP/IP sessions, the remote debug daemon must be started at the
workstation before you start Debug Tool. Refer to the remote debugger
information for help on using the remote debug daemon.
Tip on using the IBM Distributed Debugger

The IBM Distributed Debugger has several features that help you monitor and
debug programs. In this section we describe how you can use the IBM Distributed
Debugger to monitor a variable in an optimized COBOL program.
After you start the IBM Distributed Debugger and start your optimized COBOL
program, do the following steps:
1. Step into your program by using the Step Into button.

2. Click on Monitors in the menu bar, then click on Monitor Expression. The
Monitor Expression window is displayed.
3. Type in the name of the variable you want to monitor in the field labeled
″Enter the expression to be evaluated″.
4. Click on OK. The variable name and it’s current value is displayed in the
Monitors window.
5. Step through your program until you reach a statement that alters the value of
the variable you are monitoring. If you attempt to run the statement, a
Debugger Message window displays the following message:
Error occurred: EQA2421E The assignment was not performed because
the assigned value might not be used by the program,
due to optimization.
6. Enter the SET WARNING OFF command in the input line of the Command Log
window. The Command Log window displays a message that the SET WARNING
OFF command was received.
7. Step through the statement. A Debugger Message window displays the
following message:
Error occurred: EQA2420W The assignment was performed but the assigned value
might not be used by the program, due to optimization.
The new value of the variable you are monitoring is displayed in the Monitors
window.

Appendix F. Syntax of the TEST Compiler option
Debug Tool allows you to debug applications written in C, C++, COBOL, and
PL/I. In order to debug your applications, you must compile them with the TEST
compiler option. If you do not compile your applications with the TEST option,
then you can debug them only by using the disassembly view.
This chapter describes the TEST compiler option for C, C++, COBOL, and PL/I. For
more information on how to use the compiler options, refer to the chapters in
Part 2, “Preparing your program for debugging,” on page 19. For a listing of all the
compiler options available for each programming language, see the documentation
provided with each programming language compiler.
The suboptions of the TEST compiler option control the generation of symbol tables
and program hooks that Debug Tool needs to debug your programs. The choices
that you make when compiling your program affect the amount of Debug Tool
function available during your debug session. When a program is under
development, you should compile the program with TEST(ALL) to get the full
capability of Debug Tool.
Related tasks
z/OS C/C++ Programming Guide
COBOL for OS/390 & VM Programming Guide
VisualAge PL/I for OS/390 Programming Guide
Enterprise PL/I for z/OS and OS/390 Programming Guide
Related references
COBOL for OS/390 & VM Language Reference
Enterprise PL/I for z/OS and OS/390 Language Reference
VisualAge PL/I Language Reference
Syntax for the C TEST compiler option

The syntax for the C TEST compiler option is:
NOTEST
TEST
,
BLOCK
( NOBLOCK )
LINE
NOLINE
PATH
NOPATH
SYM
NOSYM
ALL
NONE
;

The following list explains what is produced by each option and suboption and
how Debug Tool uses the information when you debug your program:
NOTEST
Specifies that no debugging information is to be generated. That is, no hooks
are compiled into your program, no symbol tables are created, and Debug Tool
does not have access to any symbol information.
v You cannot step through program statements. You can suspend execution of
the program only at the initialization of the main compile unit.
v You cannot examine or use any program variables.
v You can list storage and registers.
v You cannot use the Debug Tool command GOTO.
TEST
Produces debugging information for Debug Tool to use during debugging. The
extent of the information provided depends on which suboptions are selected.
The following restrictions apply when using TEST:
v The maximum number of lines in a single source file cannot exceed 131,072.
v The maximum number of include files that have executable statements
cannot exceed 1024.
BLOCK
Inserts hooks only at block entry and exit points into your program’s
object. A block is any number of data definitions, declarations, or
statements enclosed within a single set of braces. BLOCK also creates hooks
for nested blocks. If the SYM suboption is specified, symbol tables are
generated for variables local to these nested blocks.
v You can only gain control at entry and exit points of blocks.
v Issuing a command such as STEP causes your program to run until it
reaches the exit point.
NOBLOCK
Prevents symbol information and hooks from being generated for nested
blocks.
LINE
Hooks are generated at most executable statements. Hooks are not
generated for:
v Lines that identify blocks (lines containing braces)
v Null statements
v Labels
NOLINE
Suppresses the generation of hooks at statements (line numbers).
PATH
Hooks are generated at all path points (if-then-else, calls, etc.)
v This option does not influence the generation of hooks at entry and exit
points for nested blocks. The BLOCK suboption must be specified if such
hooks are desired.
v Debug Tool can gain control only at path points and block entry and exit
points. If you attempt to step through your program, Debug Tool gains
control only at statements that coincide with path points, giving the
appearance that not all statements are executed.
v The Debug Tool command GOTO is valid only for statements and labels
coinciding with path points.

NOPATH
No hooks are generated at path points.
SYM
Generates symbol tables in the program’s object which give Debug Tool
access to variables and other symbol information.
v You can reference all program variables by name, allowing you to
examine them or use them in expressions.
v You can use the Debug Tool command GOTO to branch to a label
(paragraph or section name).
NOSYM
Suppresses the generation of symbol tables. Debug Tool does not have
access to any symbol information.
v You cannot reference program variables by name.
v You cannot use commands such as LIST or DESCRIBE to access a variable
or expression.
v You cannot use commands such as CALL or GOTO to branch to another
label (paragraph or section name).
ALL
Hooks are inserted and a symbol table is generated. Hooks are generated
at all statements, all path points (if-then-else, calls, and so on), and at all
function entry and exit points.
ALL is equivalent to TEST(LINE, BLOCK, PATH, SYM).
NONE
Generates hooks only at function entry and exit points. Hooks at block and
line points are not inserted, and the symbol tables are suppressed.
TEST(NONE) is equivalent to TEST(NOLINE, NOBLOCK, NOPATH, NOSYM).
Syntax for the C++ TEST compiler option

The syntax for the C++ TEST compiler option is:
NOTEST (1)
TEST ( )
HOOK
NOHOOK
Notes:
1 The HOOK and NOHOOK options are available only with OS/390 C/C++, Version
2 Release 4, or later.
The following list explains what is produced by each option and how Debug Tool
uses them when debugging your program:
NOTEST
Specifies that no debugging information is to be generated. That is, no hooks
are compiled into your program, no symbol tables are created, and Debug Tool
does not have access to any symbol information.
v You cannot step through program statements. You can suspend execution of
the program only at the initialization of the main compile unit.
Appendix F. Syntax of the TEST Compiler option 303

v You cannot use the Debug Tool command GOTO.
TEST
following restrictions apply when using the TEST option:
v The maximum number of lines in a single source file cannot exceed 131,072.
v The maximum number of include files that have executable statements
cannot exceed 1024.
HOOK
Generates some or all possible hook information, depending on NOOPT or OPT.
This option is only available on Version 2, Release 4 C and C++ or later.
NOHOOK
No hook information is generated. This option is available only with OS/390
C/C++, Version 2 Release 4, or later.
Syntax for the COBOL TEST compiler option

The syntax for the COBOL TEST compiler option is:
NOTEST
(ALL, SYM)
TEST
(1)
, NOSEPARATE
( ALL , SYM )
BLOCK (1)
NONE , SEPARATE
PATH NOSYM
STMT (1)
, NOSEPARATE
;
Notes:
1 The SEPARATE and NOSEPARATE suboptions are available for programs compiled
only with Enterprise COBOL for z/OS and OS/390 or COBOL for OS/390 &
VM compilers.
The TEST compiler suboptions control the production of debugging information

such as symbol tables and hooks that Debug Tool needs to debug your program.
The suboptions you choose can affect the size of your load module:
v To get the full capabilities of Debug Tool, compile your program with
TEST(ALL,SYM).
v To get most of the capabilities of Debug Tool and a smaller load module,
compile your programs with TEST(NONE,SYM,SEPARATE). You can then use the
Dynamic Debug facility to debug your program.
If you compile your program with the TEST or NOTEST options and their
corresponding suboptions, Debug Tool can do the following:
NOTEST
Specifies that no debug information is to be generated: no hooks are compiled
into your program, no symbol tables are created, and Debug Tool does not
have access to any symbol information. Using NOTEST produces the following
results:

v You cannot step through program statements.
v You can suspend execution of the program only at the initialization of the
main compile unit.
v You can include calls to CEETEST in your program to allow you to suspend
program execution and issue Debug Tool commands.
v The source listing produced by the compiler cannot be used; therefore, no
listing is available during a debug session. Using the SET DEFAULT LISTINGS
command can not make a listing available.
v Because a statement table is not available, you cannot set any statement
breakpoints or use commands such as GOTO or QUERY location.
TEST
extent of the information provided depends on which of the following
suboptions are selected.
ALL
Generates all hooks, including hooks at all statement, path, date
processing, and program entry and exit points. If you use this suboption,
the size of your program increases significantly.
v The COBOL compiler only generates hooks for date processing
statements when the DATEPROC compiler option is specified. A date
processing statement is any statement that references a date field, or any
EVALUATE or SEARCH statement WHEN phrase that references a date field.
v You can set breakpoints at all statements and path points, and step
through your program.
v Debug Tool can gain control of the program at all statements, path
points, date processing statements, labels, and block entry and exit
points, allowing you to enter Debug Tool commands.
v Branching to statements and labels using the Debug Tool command GOTO
is allowed.
BLOCK
Hooks are inserted at all block entry and exit points.
v Debug Tool gains control at entry and exit of your program, methods,
and nested programs.
v Debug Tool can be explicitly started at any point with a call to CEETEST.
reaches the next entry or exit point.
v GOTO can be used to branch to statements that coincide with block entry
and exit points.
NONE
No hooks are inserted in the program.
v You can use the GOTO command only if the program is compiled with
one of the following compilers:
– Enterprise COBOL for z/OS and OS/390
– COBOL for OS/390 & VM
v A call to CEETEST can be used at any point to start Debug Tool.
PATH
Hooks are inserted at all path points and at all program entry and exit

points. A path point is anywhere in a program where the logic flow is not
necessarily sequential or can change. Some examples of path points are
IF-THEN-ELSE constructs, PERFORM loops, ON SIZE ERROR phrases, and CALL
statements.
v Debug Tool can gain control only at path points and block entry and exit
points. If you attempt to step through your program, Debug Tool gains
control only at statements that coincide with path points, giving the
appearance that not all statements are executed.
v A call to CEETEST can be used at any point to start Debug Tool.
v The Debug Tool command GOTO is valid for all statements and labels
coinciding with path points.
STMT
Hooks are inserted at every statement and label, at every date processing
statement, and at all entry and exit points.
v The COBOL compiler generates compiled-in hooks for date processing
statements only when the DATEPROC compiler option is specified. A date
processing statement is any statement that references a date field, or any
EVALUATE or SEARCH statement WHEN phrase that references a date field.
v You can set breakpoints at all statements and step through your
program.
v Debug Tool cannot gain control at path points unless they are also at
statement boundaries.
v Branching to all statements and labels using the Debug Tool command
GOTO is allowed.
SYM
Generates symbol tables in the program’s object that give Debug Tool
access to variables and other symbol information.
v You can reference all program variables by name, which allows you to
examine them or use them in expressions.
v You can use the PLAYBACK ENABLE command with the DATA parameter.
v You can use the SET AUTOMONITOR ON command.
v SYM is required to support labels (paragraph or section names) as GOTO
targets.
SEPARATE
Saves the symbolic table information in a separate debug file. This
suboption is available only if you compile with the following
compilers:
NOSEPARATE
The symbolic table information is stored in the object. NOSEPARATE is
the default. This suboption is available only if you compile with the

NOSYM
Suppresses the generation of dictionary tables. Debug Tool does not have
access to any symbol information. Using NOSYM produces the following
results:
or expression.
v You cannot use commands such as CALL variable to branch to another
program, or GOTO to branch to another label (paragraph or section name).
Specifying TEST with no suboptions is equivalent to TEST(ALL, SYM, NOSEPARATE).
Related references
COBOL for OS/390 & VM Programming Guide
Syntax for the PL/I and Enterprise PL/I TEST compiler options
The syntax for the PL/I TEST compiler option is:
NOTEST
TEST
NONE
( BLOCK )
STMT SYM
PATH , NOSYM
ALL
SYM
NOSYM
NONE
, BLOCK
STMT
PATH
ALL
;
The syntax for the Enterprise PL/I TEST compiler option is:
NOTEST
TEST
NONE
( STMT )
ALL SYM
, NOSYM
SYM
NOSYM
NONE
, STMT
ALL
;
The following list explains each option and suboption and the capabilities of
Debug Tool when your program is compiled using these options:

NOTEST
Specifies that no debugging information is generated: no hooks are compiled
into your program, no dictionary tables are created, and Debug Tool does not
have access to any symbol information. Using NOTEST produces the following
results:
v You can include calls to PLITEST or CEETEST in your program so you can
suspend running your program and issue Debug Tool commands.
v You cannot step through program statements. You can suspend running
your program only at the initialization of the main compile unit.
v Because hooks at the statement level are not inserted, you cannot set any
statement breakpoints or use commands such as GOTO or QUERY LOCATION.
v The source listing produced by the compiler cannot be used; therefore, no
listing is available during a debug session.
TEST
extent of the information provided depends on which of the following
suboptions are selected:
ALL
Generates all compiled-in hooks, including all statement, path, and
program entry and exit hooks.
v You can set breakpoints at all statements and path points, and STEP
through your program.
v Debug Tool can gain control of the program at all statements, path
points, labels, and block entry and exit points, allowing you to enter
Debug Tool commands.
v Enables branching to statements and labels using the Debug Tool
command GOTO.
BLOCK
Hooks are inserted at all block entry and exit points.
v Enables Debug Tool to gain control at block boundaries: block entry and
block exit.
v You can gain control only at entry and exit points of your program and
all entry and exit points of internal program blocks.
v A call to PLITEST or CEETEST can be used to start Debug Tool at any
point in your program.
reaches the next block entry or exit point.
v Hooks are not inserted into an empty ON-unit or an ON-unit consisting of
a single GOTO statement.
NONE
No hooks are inserted in the program.
v A call to PLITEST or CEETEST can be used to start Debug Tool at any
point in your program.
PATH
Hooks are inserted at all path points:
v Before the THEN part of an IF statement.
v Before the ELSE part of an IF statement.

v Before the first statement of all WHEN clauses of a SELECT-group.
v Before the OTHERWISE statement of a SELECT-group.
v At the end of a repetitive DO statement, just before the Do-group is to be
executed.
v At every CALL or function reference, both before and after control is
passed to the routine.
v Before the statement following a user label, excluding labeled FORMAT
statements. If a statement has multiple labels, only one hook is inserted.
Specifying PATH also causes BLOCK hooks to be inserted.

STMT
Hooks are inserted before most executable statements and labels. STMT also
causes BLOCK hooks to be inserted.
v You can set breakpoints at all statements and step through your
program.
v Debug Tool cannot gain control at path points unless they are also at
statement boundaries.
v Branching to all statements and labels using the Debug Tool command
GOTO is allowed.
SYM
Generates a symbol table in the program’s object file. The symbol table is
required for examining program variables or program control constants by
name.
v You can reference all program variables by name, which allows you to
examine them or use them in expressions and use the DATA parameter of
the PLAYBACK ENABLE command.
v Enables support for the SET AUTOMONITOR ON command.
v Enables the support for labels as GOTO targets.
NOSYM
Suppresses the generation of a symbol table. Debug Tool does not have
access to any symbol information that causes the following results:
or expression.
v You cannot use commands such as CALL variable to branch to another
program, or GOTO to branch to another label (procedure or block name).
Compiling with TEST(STMT), TEST(PATH), or TEST(ALL) causes a statement number

table to be generated. If the STMT compiler option is in effect, specifying TEST
causes the GOSTMT compiler option to be in effect. If the NUMBER compiler option is
in effect, specifying TEST causes the GONUMBER compiler option to be in effect.
Related references
PL/I for MVS and VM Programming Guide
VisualAge PL/I for OS/390 Programming Guide

Notices
This information was developed for products and services offered in the U.S.A.
IBM might not offer the products, services, or features discussed in this document
in other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter in
this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with the local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS

PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or implied warranties in certain

transactions; therefore, this statement might not apply to you.
This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Copyright license
This information contains sample application programs in source language, which
illustrates programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or functions of these programs.
Programming interface information

This book is intended to help you debug application programs. This publication
documents intended Programming Interfaces that allow you to write programs to
obtain the services of Debug Tool.
Trademarks and service marks

The following terms, denoted by an asterisk (*) on the first occurrence in this
publication, are trademarks or service marks of International Business Machines
Corporation in the United States or other countries:
Other company, product, and service names, which may be denoted by a double
asterisk (**), may be trademarks or service marks of others.
Java™ and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a trademark of UNIX System Laboratories, licensed exclusively by

X/Open Company, Ltd.
Windows® and Windows NT® are registered trademarks of Microsoft® Corporation

in the United States, other countries, or both.

Bibliography
Diagnosis Guide, SC27-1459
Debug Tool publications
Language Reference, SC27-1460
Debug Tool for z/OS and OS/390 Licensed Program Specifications, GC27-1456
Debug Tool for z/OS Commands Summary, Messages and Codes, SC27-1461
SC18-9009
Migration Guide, GC27-1458
Debug Tool for z/OS Customization Guide,
SC18-9008 Programming Guide, SC27-1457
Program Directory for Debug Tool for z/OS, VisualAge PL/I for OS/390
GI10-8544
Compiler and Run-Time Migration Guide,
Debug Tool for z/OS Reference and Messages, SC26-9474
SC18-9010
Debug Tool for z/OS User’s Guide, SC18-9012
Debug Tool Utilities and Advanced Functions Licensed Program Specifications, GC26-9471
Coverage Utility User’s Guide and Messages, Messages and Codes, SC26-9478
SC18-9011 Programming Guide, SC26-9473
Program Directory for Debug Tool Utilities and
Advanced Functions for z/OS, GI10-8545 PL/I for MVS & VM
Compile-Time Messages and Codes, SC26-3229
High level language publications Compiler and Run-Time Migration
GuideSC26-3118
z/OS C and C++
Installation and Customization under MVS,
GC09-4913
SC26-3119
Curses, SA22-7820,
Licensed Program Specifications, GC26-3116
Programming Guide, SC09-4765
Programming Guide, SC26-3113
Run-Time Library Reference, SA22-7821
Reference Summary, SX26-3821
User’s Guide, SC09-4767
Enterprise COBOL for z/OS and OS/390 Related publications

Migration Guide, GC27-1409 z/OS Language Environment
Customization, GC27-1410 Concepts Guide, SA22-7567
Licensed Program Specifications, GC27-1410 Customization, SA22-7564
Language Reference, SC27-1408 Debugging Guide, GA22-7560
Programming Guide, SC27-1412 Programming Guide, SA22-7561
Programming Reference, SA22-7562
COBOL for OS/390 & VM
Run-Time Migration Guide, GA22-7565
GC26-4764 Vendor Interfaces, SA22-7568
Customization under OS/390, GC26-9045 Writing Interlanguage Communication
Applications, SA22-7563
Programming Guide, SC26-9049 z/OS
MVS JCL Reference, SA22-7597
Enterprise PL/I for z/OS and OS/390
MVS JCL User’s Guide, SA22-7598

MVS System Commands, SA22-7627 SK3T-4269
OS/390 Online publications can also be downloaded from

MVS JCL Reference, GC28-1757 the IBM Web site. Visit the IBM Web site for each
product to find online publications for that
MVS JCL User’s Guide, GC28-1758
product.
MVS System Commands, GC28-1781
TSO/E
Command Reference, SA22-7782
Programming Guide, SA22-7788
System Programming Command Reference,
SA22-7793
User’s Guide, SA22-7794
CICS
Application Programming Guide, SC34-5993
Application Programming Primer, SC33-0674
Application Programming Reference, SC34-5994
IMS
IMS Application Programming: Database
Manager, SC26-8727
IMS Application Programming: EXEC DLI
Commands for CICS & IMS, SC26-8726
IMS Application Programming: Transaction
Manager, SC26-8729
DB2 UDB for OS/390 and z/OS

Administration Guide, SC26-9931
Application Programming and SQL Guide,
SC26-9933
Command Reference, SC26-9934
Data Sharing: Planning and Administration,
SC26-9935
Installation Guide, GC26-9936
Messages and Codes, GC26-9940
Reference for Remote DRDA* Requesters and
Servers, SC26-9942
Release Planning Guide, SC26-9943
SQL Reference, SC26-9944
Utility Guide and Reference, SC26-9945
Softcopy publications
Online publications are distributed on CD-ROMs
and can be ordered through your IBM
representative. Debug Tool for z/OS User’s Guide,
Debug Tool for z/OS Customization Guide, and
Debug Tool for z/OS Reference and Messages are
distributed on the following collection kit:

Glossary
This glossary defines technical terms and breakpoint. A place in a program, usually specified by
abbreviations used in Debug Tool for z/OS User’s a command or a condition, where execution can be
Guide documentation. If you do not find the term interrupted and control given to the user or to Debug
you are looking for, refer to the IBM Glossary of Tool.
Computing Terms, located at the IBM Terminology
web site: C
http://www.ibm.com/ibm/terminology
century window (COBOL). The 100-year interval in
which COBOL assumes all windowed years lie. The
A start of the COBOL century window is defined by the
COBOL YEARWINDOW compiler option.
active block. The currently executing block that
invokes Debug Tool or any of the blocks in the CALL command list. A grouping of commands that can be
chain that leads up to this one. used to govern the startup of Debug Tool, the actions
of Debug Tool at breakpoints, and various other
active server. A server that is being used by a remote debugging actions.
debug session. Contrast with inactive server. See also
server. compile. To translate a program written in a high
level language into a machine-language program.
alias . An alternative name for a field used in some
high-level programming languages. compile unit. A sequence of HLL statements that
make a portion of a program complete enough to
animation. The execution of instructions one at a time compile correctly. Each HLL product has different rules
with a delay between each so that any results of an for what comprises a compile unit.
instruction can be viewed.
compiler. A program that translates instructions
attention interrupt. An I/O interrupt caused by a written in a high level programming language into
terminal or workstation user pressing an attention key, machine language.
or its equivalent.
condition. Any synchronous event that might need to
attention key. A function key on terminals or be brought to the attention of an executing program or
workstations that, when pressed, causes an I/O the language routines supporting that program.
interrupt in the processing unit. Conditions fall into two major categories: conditions
detected by the hardware or operating system, which
attribute. A characteristic or trait the user can specify. result in an interrupt; and conditions defined by the
programming language and detected by
Autosave. A choice allowing the user to automatically
language-specific generated code or language library
save work at regular intervals.
code. An example of a hardware condition is division
by zero. An example of a software condition is
B end-of-file. See also exception.
batch. Pertaining to a predefined series of actions conversational. A transaction type that accepts input
performed with little or no interaction between the user from the user, performs a task, then returns to get more
and the system. Contrast with interactive. input from the user.
batch job. A job submitted for batch processing. See currently qualified. See qualification.
batch. Contrast with interactive.
batch mode. An interface mode for use with the MFI

D
Debug Tool that does not require input from the
data type. A characteristic that determines the kind of
terminal. See batch.
value that a field can assume.
block. In programming languages, a compound
data set. The major unit of data storage and retrieval,
statement that coincides with the scope of at least one
consisting of a collection of data in one of several
of the declarations contained within it.
prescribed arrangements and described by control
information to which the system has access.

date field. A COBOL data item that can be any of the dynamic link library (DLL). A file containing
following: executable code and data bound to a program at load
v A data item whose data description entry includes a time or run time. The code and data in a dynamic link
DATE FORMAT clause. library can be shared by several applications
simultaneously. See also load module.
v A value returned by one of the following intrinsic
functions:
DATE-OF-INTEGER E
DATE-TO-YYYYMMDD
DATEVAL enclave. An independent collection of routines in
DAY-OF-INTEGER Language Environment, one of which is designated as
DAY-TO-YYYYDDD the MAIN program. The enclave contains at least one
YEAR-TO-YYYY thread and is roughly analogous to a program or
YEARWINDOW routine. See also thread.
v The conceptual data items DATE and DAY in the
entry point. The address or label of the first
ACCEPT FROM DATE and ACCEPT FROM DAY
instruction executed on entering a computer program,
statements, respectively.
routine, or subroutine. A computer program can have a
v The result of certain arithmetic operations. number of different entry points, each perhaps
corresponding to a different function or purpose.
The term date field refers to both expanded date field and
windowed date field. See also nondate.. exception. An abnormal situation in the execution of a
program that typically results in an alteration of its
date processing statement. A COBOL statement that normal flow. See also condition.
references a date field, or an EVALUATE or SEARCH
statement WHEN phrase that references a date field. execute. To cause a program, utility, or other machine
function to carry out the instructions contained within.
DBCS. See double-byte character set. See also run.
debug. To detect, diagnose, and eliminate errors in execution time. See run time.
programs.
execution-time environment. See run-time environment.
DTCN. Debug Tool Control utility, a CICS transaction
that enables the user to identify which CICS programs expanded date field. A COBOL date field containing
to debug. an expanded (four-digit) year. See also date field and
expanded year.
Debug Tool procedure. A sequence of Debug Tool
commands delimited by a PROCEDURE and a expanded year. In COBOL, four digits representing a
corresponding END command. year, including the century (for example, 1998).
Appears in expanded date fields. Compare with
Debug Tool variable. A predefined variable that windowed year.
provides information about the user’s program that the
user can use during a session. All of the Debug Tool expression. A group of constants or variables
variables begin with %, for example, %BLOCK or %CU. separated by operators that yields a single value. An
expression can be arithmetic, relational, logical, or a
default. A value assumed for an omitted operand in a character string.
command. Contrast with initial setting.
double-byte character set (DBCS). A set of characters F

in which each character is represented by two bytes.
Languages such as Japanese, which contain more file. A named set of records stored or processed as a
symbols than can be represented by 256 code points, unit. An element included in a container: for example,
require double-byte character sets. Because each an MVS member or a partitioned data set. See also data
character requires two bytes, the typing, displaying, set.
and printing of DBCS characters requires hardware and
programs that support these characters. frequency count. A count of the number of times
statements in the currently qualified program unit have
dynamic. In programming languages, pertaining to been run.
properties that can only be established during the
execution of a program; for example, the length of a full-screen mode. An interface mode for use with a
variable-length data object is dynamic. Contrast with nonprogrammable terminal that displays a variety of
static. information about the program you are debugging.

H load module. A program in a form suitable for
loading into main storage for execution. In this
document this term is also used to refer to a Dynamic
high level language (HLL). A programming language
Load Library (DLL).
such as C, COBOL, or PL/I.
HLL. See high level language. M

hook. An instruction inserted into a program by a
minor node. In VTAM, a uniquely defined resource
compiler when you specify the TEST compile option.
within a major node.
Using a hook, you can set breakpoints to instruct
Debug Tool to gain control of the program at selected multitasking. A mode of operation that provides for
points during its execution. concurrent performance, or interleaved execution of
two or more tasks.
I
N
inactive block. A block that is not currently executing,
or is not in the CALL chain leading to the active block. nonconversational. A transaction type that accepts
See also active block, block. input, performs a task, and then ends.
initial setting. A value in effect when the user’s nondate. A COBOL data item that can be any of the
Debug Tool session begins. Contrast with default. following:
interactive. Pertaining to a program or system that v A data item whose date description entry does not
alternately accepts input and then responds. An include the DATE FORMAT clause
interactive system is conversational; that is, a v A literal
continuous dialog exists between the user and the v A reference modification of a date field
system. Contrast with batch.
v The result of certain arithmetic operations that may
I/O . Input/output. include date field operands; for example, the
difference between two compatible date fields.
L The value of a nondate may or may not represent a

date.
Language Environment. An IBM software product
that provides a common run-time environment and
common run-time services for IBM high level language O
compilers.
Options. A choice that lets the user customize objects
library routine. A routine maintained in a program or parts of objects in an application.
library.
line mode. An interface mode for use with a P

nonprogrammable terminal that uses a single command
line to accept Debug Tool commands. panel. In Debug Tool, an area of the screen used to
display a specific type of information.
line wrap. The function that automatically moves the
display of a character string (separated from the rest of parameter. Data passed between programs or
a line by a blank) to a new line if it would otherwise procedures.
overrun the right margin setting.
partitioned data set (PDS). A data set in direct access
link-edit. To create a loadable computer program storage that is divided into partitions, called members,
using a linkage editor. each of which can contain a program, part of a
program, or data.
linkage editor. A program that resolves
cross-references between separately compiled object path point. A point in the program where control is
modules and then assigns final addresses to create a about to be transferred to another location or a point in
single relocatable load module. the program where control has just been given.
listing. A printout that lists the source language PDS. See partitioned data set.
statements of a program with all preprocessor
prefix area. The eight columns to the left of the
statements, includes, and macros expanded.
program source or listing containing line numbers.
Statement breakpoints can be set in the prefix area.
Glossary 317
primary entry point. See entry point. array or array element, or a structure or structure
element. Any of the above can be pointer-qualified
procedure. In a programming language, a block, with where applicable.
or without formal parameters, whose execution is
invoked by means of a procedure call. A set of related run. To cause a program, utility, or other machine
control statements. For example, an MVS CLIST. function to execute. An action that causes a program to
begin execution and continue until a run-time
process. The highest level of the Language exception occurs. If a run-time exception occurs, the
Environment program management model. It is a user can use Debug Tool to analyze the problem. A
collection of resources, both program code and data, choice the user can make to start or resume regular
and consists of at least one enclave. execution of a program.
Profile. A choice that allows the user to change some run time. Any instant when a program is being
characteristics of the working environment, such as the executed.
pace of statement execution in the Debug Tool.
run-time environment. A set of resources that are
program. A sequence of instructions suitable for used to support the execution of a program.
processing by a computer. Processing can include the
use of an assembler, a compiler, an interpreter, or a run unit. A group of one or more object programs that
translator to prepare the program for execution, as well are run together.
as to execute it.
program unit. See compile unit. S

program variable. A predefined variable that exists SBCS. See single-byte character set.
when Debug Tool was invoked.
semantic error. An error in the implementation of a
pseudo-conversational transaction. The result of a program’s specifications. The semantics of a program
technique in CICS called pseudo-conversational refer to the meaning of a program. Unlike syntax
processing in which a series of nonconversational errors, semantic errors (since they are deviations from a
transactions gives the appearance (to the user) of a program’s specifications) can be detected only at run
single conversational transaction. See conversational and time. Contrast with syntax error.
nonconversational.
sequence number. A number that identifies the
records within an MVS file.
Q
session variable. A variable the user declares during
qualification. A method used to specify to what the Debug Tool session by using Declarations.
procedure or load module a particular variable name,
function name, label, or statement id belongs. The SET single-byte character set (SBCS). A character set in
QUALIFY command changes the current implicit which each character is represented by a one-byte code.
qualification.
Single Point of Control. The control interface that
sends commands to one or more members of an
R IMSplex and receives command responses.
record. A group of related data, words, or fields source. The HLL statements in a file that make up a
treated as a unit, such as one name, address, and program.
telephone number.
Source window. A Debug Tool window that contains
record format. The definition of how data is a display of either the source code or the listing of the
structured in the records contained in a file. The program being debugged.
definition includes record name, field names, and field
descriptions, such as length and data type. The record SPOC. See 318.
formats used in a file are contained in the file
static. In programming languages, pertaining to
description.
properties that can be established before execution of a
reference. In programming languages, a language program; for example, the length of a fixed-length
construct designating a declared language object. A variable is static. Contrast with dynamic.
subset of an expression that resolves to an area of
step. One statement in a computer routine. To cause a
storage; that is, a possible target of an assignment
computer to execute one or more statements. A choice
statement. It can be any of the following: a variable, an
the user can make to execute one or more statements in
the application being debugged.

storage. A unit into which recorded text can be
entered, in which it can be retained, and from which it
V
can be retrieved. The action of placing data into a
variable. A name used to represent a data item whose
storage device. A storage device.
value can be changed while the program is running.
subroutine. A sequenced set of instructions or
VTAM. See “Virtual Telecommunications Access
statements that can be used in one or more computer
Method.”
programs at one or more points in a computer
program. Virtual Telecommunications Access Method (VTAM).
(1) IBM software that controls communication and the
suffix area. A variable-sized column to the right of the
flow of data in an SNA network by providing the SNA
program source or listing statements, containing
application programming interfaces and SNA
frequency counts for the first statement or verb on each
networking functions. An SNA network includes
line. Debug Tool optionally displays the suffix area in
subarea networking, Advanced Peer-to-Peer
the Source window. See also prefix area.
Networking (APPN), and High-Performance Routing
syntactic analysis. An analysis of a program done by (HPR). Beginning with Release 5 of the OS/390
a compiler to determine the structure of the program operating system, the VTAM for MVS/ESA function
and the construction of its source statements to was included in Communications Server for OS/390;
determine whether it is valid for a given programming this function is called Communications Server for
language. See also syntax checker, syntax error. OS/390 - SNA Services. (2) An access method
commonly used by MVS to communicate with
syntax. The rules governing the structure of a terminals and other communications devices.
programming language and the construction of a
statement in a programming language. W
syntax error. Any deviation from the grammar (rules)
windowed date field. A COBOL date field containing
of a given programming language appearing when a
a windowed (two-digit) year. See also date field and
compiler performs a syntactic analysis of a source
windowed year.
program. See also syntactic analysis.
windowed year. In COBOL, two digits representing a
T year within a century window (for example, 98).
Appears in windowed date fields. See also century
session variable. See session variable. window (COBOL).
Compare with expanded year.
thread. The basic line of execution within the
Language Environment program model. It is word wrap. See line wrap.
dispatched with its own instruction counter and
registers by the system. Threads can execute,
concurrently with other threads. The thread is where
actual code resides. It is synonymous with a CICS
transaction or task. See also enclave.
thread id. A small positive number assigned by

Debug Tool to a Language Environment task.
token. A character string in a specific format that has

some defined significance in a programming language.
trigraph. A group of three characters which, taken

together, are equivalent to a single special character. For
example, ??) and ??( are equivalent to the left (<) and
right (>) brackets.
U
utility. A computer program in general support of
computer processes; for example, a diagnostic program,
a trace program, or a sort program.
Glossary 319
Index
Special characters assembler programs
assembling, requirements 38
breakpoints (continued)
halting when certain functions are
__ctest() function 75 requirements for debugging 37 called (continued)
%CONDITION variable using Debug Tool Utilities to assemble in PL/I 136
for PL/I 201 and create 39 recording, using SET
%PATHCODE variable assembler, definition of xiii AUTOMONITOR 108
for C and C++ 209 assembling your program, requirements setting a line 109
for PL/I 200 for 38 setting, in C++ 225
values for COBOL 192 assigning values to variables 189, 209 using within multiple enclaves 278
#pragma 33 AT commands
specifying TEST compiler option 33 AT CALL
specifying TEST run-time option
with 67
breakpoints, for C++ 226
AT ENTRY
C
C
breakpoints, for C++ 225
debugging a program in full-screen
AT EXIT
A breakpoints, for C++ 225
mode
calling a C function from Debug
ABEND 4038 278 attention interrupt
Tool 146
abnormal end of application, setting effect of during Dynamic Debug 118
capturing output to stdout 146
breakpoint at 269 effect of during interactive
debugging a DLL 147
accessing PL/I program variables 202 sessions 118
displaying raw storage 147
ALLOCATE command how to initiate 118
displaying strings 147
managing file allocations 116 required Language Environment
finding storage overwrite
ambiguous names 115 run-time options 118
errors 148
applications 253 attributes of variables 272
finding uninitialized storage
assembler errors 149
debugging a program in full-screen getting a function traceback 147
mode B halting on line if condition
defining CU as assembler 166 batch mode 64 true 145
displaying variable or storage 168 debugging CICS programs in 250 halting when certain functions are
finding storage overwrite debugging DB2 programs in 243 called 144
errors 170 debugging IMS programs in 248 modifying value of variable 144
getting a function traceback 170 description of 5 setting breakpoint to halt 150
identifying a CU 166 starting Debug Tool in 81 tracing run-time path for code
identifying assembler in a different using Debug Tool in 297 compiled with TEST 148
CU 167 binding DB2 programs 43 when not all parts compiled with
loading debug information 166 blanks, significance of 184 TEST 145
modifying variables or blocks and block identifiers sample program for debugging 141
storage 168 using, for C 220 syntax of TEST compiler option 301
multiple CUs in single breakpoint C and C++
assembly 167 clearing 17 AT ENTRY/EXIT breakpoints 225
stopping at assembler routine implicit 64 blocks and block identifiers 220
call 168 using DISABLE and ENABLE 16 commands
stopping when condition is breakpoints summary 207
true 169 before calling a NULL function equivalents for Language
when not all parts have debug in C 150 Environment conditions 214
information 169 in C++ 161 function calls for 212
restrictions 233 before calling an invalid program, in notes on using 182
using Language Environment COBOL 130 reserved keywords 213
services 233 before calling an undefined program, C++ 121
while debugging MAIN in PL/I 140 AT CALL breakpoints 226
program 233 halting if a condition is true debugging a program in full-screen
with STORAGE run-time in C 145 mode
option 233 in C++ 156 calling a C++ function from Debug
sample program for debugging 163 in COBOL 126 Tool 158
self-modifying code, restrictions 233, in PL/I 137 capturing output to stdout 158
237 halting when certain COBOL routines debugging a DLL 158
assembler program are called 124 displaying raw storage 158
loading debug information 231 halting when certain functions are displaying strings 158
locating EQALANGX 231 called finding storage overwrite
making assembler CUs known to in C 144 errors 160
Debug Tool 232 in C++ 155

C++ (continued) COBOL (continued) commands (continued)
debugging a program in full-screen debugging a program in full-screen prefix, using in Debug Tool 102
mode (continued) mode truncating 182
finding uninitialized storage capturing I/O to system TSO, using to debug DB2
errors 160 console 127 program 243
getting a function traceback 159 displaying raw storage 128 commands (system), entering in Debug
halting on a line if condition finding storage overwrite Tool 101
true 156 errors 130 commands file 64, 287
modifying value of variable 155 generating a run-time paragraph example of specifying 82
setting a breakpoint to halt 155, trace 129 using log file as 107
161 modifying the value of a using session log as 65
tracing the run-time path 159 variable 125 commands, Debug Tool
viewing and modifying data setting a breakpoint to halt 124 COBOL compiler options in
members 157 setting breakpoint to halt 130 effect 188
when not all parts compiled with stopping on line if condition entering on the session panel 100
TEST 157 true 126 entering using program function
examining objects 227 tracing the run-time path 128 keys 102
overloaded operator 225 when not all parts compiled with order of processing 101
sample program for debugging 121, TEST 127 retrieving with RETRIEVE
151 debugging COBOL classes 197 command 103
setting breakpoints 225 debugging VS COBOL II that resemble COBOL statements 187
stepping through C++ programs 225 programs 198 comments, inserting into command
syntax of TEST compiler option 303 finding listing 198 stream 184
template in C++ 225 FACTORY 197 common_parameters, when to use 9
CAF (call access facility), using to start list of compilers that support compile unit 100
DB2 program 244 SEPARATE 187 general description 267
call access facility (CAF), using to start listing files 187 name area, Debug Tool 100
DB2 program 244 note on using H constant 185 qualification of, for C and C++ 222
capturing output to stdout notes on using 182 compiling
in C 146 OBJECT 197 a C program on an HFS file
in C++ 158 optimized programs, debugging 258 system 32
CEEBXITA 47 paragraph trace, generating a COBOL a C++ program on an HFS file
CEETEST run-time 129 system 35
description 69 preparing, programs to debug 25 an OS/VS COBOL program 27
examples, for C 71 reserved keywords 189 considerations 21
examples, for COBOL 72 restrictions on accessing, data 112 DB2 programs for debugging 41
examples, for PL/I 73 run-time options 67 Enterprise PL/I program on HFS file
Starting Debug Tool with 69 syntax of TEST compiler option 304 system 29
using 248 variables, using with Debug Tool 189 IMS programs 53
CEEUOPT run-time options module 42 COBOL listing, data set 285 OS PL/I 30
CEEUOPT to start Debug Tool under coexistence of Debug Tool with other PL/I for MVS & VM program 30
CICS, using 88 debuggers 273 programs, introduction to 11
changing the value of a variable, coexistence with unsupported HLL condition
introduction to 16 modules 274 handling of 201, 270
changing window layout in the session colors Language Environment, C and C++
panel 172 changing in session panel 174 equivalents 214
character set 181 command considerations
characters, searching 105 syntax diagrams xiii before compiling and debugging 21
CICS command format when using the TEST run-time
debug modes under 249 for COBOL 188 option 63
pseudo-conversational program 250 command line, Debug Tool 100 constants
requirements for using Debug Tool command sequencing, full-screen Debug Tool interpretation of
in 249 mode 101 HLL 265
restoring breakpoints 250 commands entering 185
restrictions for debugging 250 abbreviating 182 HLL 266
saving breakpoints 250 DTSU, using to debug DB2 PL/I 204
starting Debug Tool under 86 program 243 using in expressions, for COBOL 194
starting the log file 251 for C and C++, Debug Tool constructor, stepping through 225
CICS, starting Debug Tool under 79 subset 207 continuation character 101
closing automonitor section of Monitor for PL/I, Debug Tool subset 199 for COBOL 188
window 113 getting online help for 185 using in full-screen 183
closing Debug Tool session panel interpretive subset continuing lines 183
windows 173 description 266 continuous display
COBOL list of Debug Tool Advanced See monitoring
command format 188 Functions 7 Convert and Compile option 27
Convert and Compile option 27 multiline 183 copying
PLAYBACK 14 JCL into a setup file using DTSU 60

creating Debug Tool (continued) destructor, stepping through 225
setup file using Debug Tool list of supported compilers 3 diagnostics, expression, for C and
Utilities 59 list of supported subsystems 3 C++ 215
CURSOR command multilanguage programs, using 271 disassembly
using 104 optimized programs, using with 257 changing program in disassembly
cursor commands PL/I commands, interpretive view 238
CLOSE 173 subset 199 differences between SET ASSEMBLER
CURSOR 104 starting at different points 64 and SET DISASSEMBLY 231, 235
FIND 105 starting under CICS 79, 86 displaying registers 238
OPEN 173 starting under IMS 248 displaying storage 238
SCROLL 95, 105 starting under MVS in TSO 79 modifying registers 238
SIZE 173 starting your program with 83 modifying storage 238
using in Debug Tool 102 starting, by using Debug Tool performing single-step
WINDOW ZOOM 173 Utilities 59 operations 237
customizing stopping, session 17 restrictions on what you can
PF keys 171 terminology xii debug 239
Profile panel 63 using in batch mode 297 self-modifying code, restrictions 233,
profile settings 175 using in remote debug mode 299 237
session settings 171 Debug Tool Advanced Functions, list setting breakpoints 237
of 7 what you can do is disassembly
Debug Tool Setup Utility 59 view 235
D Debug Tool Utilities
creating and managing setup files 8
disassembly view, description of 236
disassembly view, how to start 236
DATA parameter
creating private message region for displaying
restrictions on accessing COBOL
IMS program 54 environment information 222
data 112
creating setup file for IMS halted location 106
data sets
program 54 lines at top of window, Debug
COBOL listing 285
how to use, to link-edit 39 Tool 105
PL/I listing 286
overview of code coverage tasks 8 raw storage
PL/I source 285
overview of IMS program preparation in C 147
separate debug file 286
tasks 9 in C++ 158
specifying 107
overview of program preparation in COBOL 128
used by Debug Tool 285
tasks 8 in PL/I 138
DB2
preparing an IMS program by source or listing file in full-screen
compiling programs for
using 53 mode 98
debugging 41
specifying TEST run-time options for strings
DB2 programs for debugging 41
IMS program 54 in C 147
linking programs 42
starting your program 62 in C++ 158
using Debug Tool with 243
using to assemble and create 39 value of variable one time 112
DB2 stored procedures
Debug Tool Utilities and Advanced values of COBOL variables 191
preparing for debugging 45
Functions variable value 112
starting Debug Tool from 85
introduction 7 displaying the value of a variable,
using Debug Tool with 245
tasks it helps you with 7 introduction to 15
DBCS
Debug Tool Utilities, list of 7 displaying variable value
using with C 182
debuggers, coexistence with other 273 See LIST commands
using with COBOL 191
debugging DLL debugging
using with Debug Tool
CICS programs 249 in C 147
commands 181
COBOL classes 197 in C++ 158
ddname
considerations 21 documents, licensed ix
creating a log file in Debug Tool 107
DB2 programs 243 DOWN, SCROLL command 105
debug session
DB2 stored procedures 245 DTCN
ending 119
DLL creating a profile 47
recording 98
in C 147 data entry verification 50
starting 83
in C++ 158 description 86
starting your program 83
IMS programs 247 modifying Language Environment
Debug Tool
in full-screen mode 93 options 50
C and C++ commands, interpretive
ISPF applications 253 overview 87
subset 207
multithreading programs 275 preparing to start Debug Tool 47
COBOL commands, interpretive
optimized programs, prevention 26 using repository profile items 87
subset 187
UNIX System Services programs 261 DTSU
commands, subset 266
declaring session variables See Debug Tool Setup Utility
condition handling 270
for C 210 dual terminal mode (CICS) 249
data sets 285
for COBOL 193 Dynamic Debug
evaluation of HLL expressions 265
DESCRIBE ALLOCATIONS command activating 21, 22, 26
exception handling, for C and C++
managing file allocations 116 attention interrupts, support for 118
and PL/I 271
DESCRIBE command
interfaces 4
using 222
interpretation of HLL variables 265
Index 323
E examples (continued)
changing point of view, general 268
finding (continued)
storage overwrite errors (continued)
editing COBOL in PL/I 140
setup file using Debug Tool Setup %HEX function 195 uninitialized storage errors
Utility 59 %STORAGE function 195 in C 149
elements, unsupported, for PL/I 205 assigning values to COBOL in C++ 160
enclave variables 189 FREE command
multiple, debugging interlanguage changing point of view 197 managing file allocations 116
communication application in 281 displaying results of expression freeform input, PL/I statements 202
starting 277 evaluation 194 full-screen mode
ending displaying values of COBOL continuation character, using in 183
debug session 119 variables 191 CURSOR 102
Debug Tool within multiple qualifying variables 196 CURSOR command 104
enclaves 278 using constants in debugging in 93
entering expressions 194 description of 5
commands on session panel 100 declaring variables, for COBOL 193 introduction to 11
file allocation statements into setup displaying program variables 208 PANEL COLORS 174
file 60 modifying setup files by using Debug PANEL LAYOUT 172
program parameters into setup Tool Utilities 291 PANEL PROFILE 175
file 60 PL/I screen 12
run-time option into setup file 60 in PL/I 136 SCROLL 105
entering multiline commands without sample program for WINDOW CLOSE 173
continuation 184 debugging 133 WINDOW OPEN 173
entering PL/I statements, freeform 202 PLITEST calls for PL/I 75 WINDOW SIZE 173
Enterprise PL/I, definition of xii preparing programs by using Debug WINDOW ZOOM 173
EQADCCXT 47 Tool Utilities 291 full-screen mode through a VTAM
EQADCCXT user exit 65, 87 remote debug mode 67 terminal
EQADTCN2 51 specifying TEST run-time option with description of 5
EQALANGX file #pragma 67 starting a debugging session 85
how to create 38 TEST run-time option 66 function calls, for C and C++ 212
EQALANGX files, how Debug Tool using #pragma for TEST compiler function, calling C and C++ from Debug
locates 289, 290 option 33 Tool
EQASTART, entering command 9 using constants 185 C 146
EQUATE, SET command using continuation characters 183 C++ 158
description 171 using qualification 222 function, unsupported for PL/I 205
error numbers in Log window 117 exception handling for C and C++ and functions
evaluating expressions PL/I 271 PL/I 204
COBOL 193 EXEC CICS RETURN functions, Debug Tool
HLL 265 under CICS 250 %HEX
evaluation of expressions executing using with COBOL 195
C and C++ 215 See running %STORAGE
examining C++ objects 227 expressions using with COBOL 195
examples diagnostics, for C and C++ 215 using with COBOL 195
assembler displaying values, for C and
sample program for C++ 208
debugging 163
C
displaying values, for COBOL 194
evaluation for C and C++ 211, 215
G
sample program for global data 228
evaluation for COBOL 193
debugging 141 global scope operator 228
evaluation of HLL 265
C and C++ evaluation, operators and operands
assigning values to variables 209 for C 213
blocks and block identifiers 221 for PL/I 204 H
expression evaluation 211 using constants in, for COBOL 194 H constant (COBOL) 185
monitoring and modifying halted location, displaying 106
registers and storage 228 header fields, Debug Tool session
referencing variables and setting
breakpoints 221 F panel 94
help, online
scope and visibility of objects 221 FIND command
for command syntax 185
C++ using with windows 105
hexadecimal format, displaying values
displaying attributes 227 finding
in 114
sample program for characters or strings 105
hexadecimal format, displaying variable
debugging 121, 151 renamed source, listing or separate
values in 112
setting breakpoints 226 debug file 117
hexadecimal format, how to display
CEDF procedure 89 storage overwrite errors
value of variable 114
CEETEST calls, for PL/I 73 in assembler 170
hexadecimal format, how to monitor
CEETEST function calls, for C 71 in C 148
value of variable 114
CEETEST function calls, for in C++ 160
COBOL 72 in COBOL 130

hexadecimal format, monitoring values
in 114
INTERRUPT, Language Environment
run-time option 118
M
HFS, compiling a C program on 32 invoking managing file allocations 116
HFS, compiling a C++ program on 35 See starting message retrieval tool, LookAt x
HFS, compiling Enterprise PL/I program ISPF modifying
on 29 starting 102 value of variable 115
highlighting, changing in Debug Tool value of variable by typing over 115
session panel 174 modifying value of a C variable 144
MONITOR command
history, Debug Tool command 103
retrieving previous commands 103
J viewing output from, Debug Tool 97
JCL to create EQALANGX file 38 MONITOR LIST command, using to
HOOK C++ TEST suboption 304
hooks monitor variables 113
compiling with 21 Monitor window
compiling with, C 31 K description 97
compiling with, COBOL 25 keywords, abbreviating 182 opening and closing 116, 173
compiling with, PL/I 29 monitoring 113
compiling without, COBOL 21 monitoring storage in C++ 228
more than one language, debugging
removing from application 255, 256
removing, implications of 22
L programs with 271
Language Environment moving around windows in Debug
rules for placing 33, 36
conditions, C and C++ Tool 104
equivalents 214 moving the cursor, Debug Tool 104
EQADCCXT user exit 65, 87 multilanguage programs, using with
I run-time options, precedence 65 Debug Tool 271
I/O, COBOL Language Environment-conforming multiline commands
capturing to system console 127 program 37 continuation character, using in 183
improving Debug Tool performance 255 LDD command, example 231 without continuation character 184
IMS LEFT, SCROLL command 105 multiple enclave
preparing licensed documents ix using breakpoints 278
by using Debug Tool Utilities 53 line breakpoint, setting 109 multiple enclaves
programs, compiling 53 line continuation ending Debug Tool 278
programs, debugging for C 183 interlanguage communication
interactively 247 for COBOL 184 application, debugging 281
programs, linking 55 link-edit assembler program starting 277
using Debug Tool with 247 how to, by using Debug Tool multithreading 275
information, displaying Utilities 39 restrictions 275
environmental 222 linking MVS
input areas, order of processing, Debug CEEBXITA 47 starting Debug Tool using TEST
Tool 101 DB2 programs 42 run-time option 83
INSPIN 287 IMS programs 55 MVS POSIX programs, debugging 261
INSPLOG LIST %HEX command 114 MVS, starting Debug Tool under 79
creating the log file 107 LIST command
default DD name to store log file 287 use to display value of variable one
example of using 81
INSPSAFE
time 112
LIST commands
N
default DD name to store preference LIST STORAGE navigating session panel windows 104
settings 287 using with PL/I 202 NOTEST suboption of TEST run-time
example of using 81 listing option 63
using to save profile settings 177 file, finding renamed 117
using to save session panel files, for COBOL 187
colors 174 find, VS COBOL II 198 O
interfaces listing files, how Debug Tool locates 289 objects
batch mode 5 literal constants, entering 185 C and C++, scope of 218
full-screen mode 5 log file 107, 287 opening Debug Tool session panel
full-screen mode through a VTAM creating 107 windows 173
terminal 5 default names 107 operators and operands for C 213
remote debug mode 5 using 107 OPTIMIZE compiler option 257
interfaces, description of 4 using as a commands file 107 optimized programs, debugging
interLanguage communication (ILC) Log window COBOL 258
application, debugging 281 description 98 options module, CEEUOPT run-time 42
interlanguage programs, using with error numbers in 117 output
Debug Tool 271 retrieving lines from 104 C, capturing to stdout 146
interpretive subset log, session 65 C++, capturing to stdout 158
general description 266 LookAt message retrieval tool x overloaded operator 225
of C and C++ commands 207 low-level debugging 228 overwrite errors, finding storage
of COBOL statements 187 in assembler 170
of PL/I commands 199 in C 148
in C++ 160
Index 325
overwrite errors, finding storage point of view, changing qualification (continued)
(continued) description 268 general description 267
in COBOL 130 for C and C++ 223 qualifying variables
in PL/I 140 with COBOL 197 with COBOL 195
positioning lines at top of windows 105
precompiling DB2 programs 41
P preference file 50, 63
preferences file 286
R
panel recording
customizing with 177
header fields, session 94 breakpoints using SET
prefix area
Profile 175 AUTOMONITOR 108
Debug Tool 100
PANEL command (full-screen mode) number of times each source line
prefix commands
changing session panel colors and runs 108
prefix area on session panel 100
highlighting 174 restrictions on, statements 111
using in Debug Tool 102
paragraph trace, generating a COBOL session with the log file 107
prepare an assembler program, steps
run-time 129 statements, introduction to 13
to 37
performance, improving Debug Tool 255 statements, using PLAYBACK
preparing
PF keys ENABLE command 110
a PL/I program for debugging 29
defining 171 stopping, using PLAYBACK DISABLE
COBOL programs for debugging 25
using 102 command 111
DB2 stored procedures 45
PF4 key, using 112 recording a debug session 98
to replay recorded statements using
PL/I 133 referencing variables, implications of 22
PLAYBACK START command 111
built-in functions 204 remote debug mode
previous commands, retrieving 103
condition handling 201 description of 5
profile settings, changing in Debug
constants 204 examples of 67
Tool 175
debugging a program in full-screen list of supported remote debuggers 4
program
mode using Debug Tool in 299
CICS, debugging 249
displaying raw storage 138 removing statement and symbol
compiling an IMS 53
finding storage overwrite tables 256
DB2, debugging 243
errors 140 replaying
hook
getting a function traceback 138 statements, introduction to 13
compiling with, C 31
halting on line if condition is replaying recorded statements 111
compiling with, COBOL 25
true 137 replaying statements
compiling with, PL/I 29
modifying value of variable 136 changing direction of 111
removing 255, 256
setting a breakpoint to halt 136 direction of 111
rules for placing 33, 36
setting breakpoint to halt 140 restrictions on 111
IMS, debugging 247
tracing run-time path for code stopping using PLAYBACK STOP
linking an IMS 55
compiled with TEST 138 command 111
multithreading, debugging 275
when not all parts compiled with using PLAYBACK commands 109
preparation
TEST 137 using PLAYBACK START
considerations, size and
expressions 204 command 111
performance 255, 256
notes on using 182 requirements
TEST compiler option, for C 31
preparing a program for for debugging CICS programs 249
TEST compiler option, for C++ 35
debugging 29 reserved keywords
TEST compiler option, for
run-time options 67 for C 213
COBOL 25
sample program for debugging 133 for COBOL 189
TEST compiler option, for
session variables 202 RESIDENT compiler option 26
PL/I 29
statements 199 resources to collect 23
TEST compiler option, for VS
structures, accessing 203 restrictions 188
COBOL II 26
syntax of TEST compiler option 307 accessing COBOL data, for 112
reducing size 255
PL/I listing, data set 286 arithmetic expressions, for
source, displaying with Debug
PL/I source, data set 285 COBOL 193
Tool 96
PLAYBACK commands debugging VS COBOL II
starting for a debug session 79
introduction to 14 programs 198
stepping through 109
PLAYBACK BACKWARD expression evaluation, for
UNIX System Services,
using 111 COBOL 193
debugging 261
PLAYBACK DISABLE location of source on HFS 29, 32, 35
variables
using 111 modifying variables in Monitor
accessing for C and C++ 208
PLAYBACK ENABLE window 115
variables, accessing for COBOL 189
using 110 recording and replaying statements,
pseudo-conversational program, saving
PLAYBACK FORWARD for 111
settings 250
using 111 string constants in COBOL 194
PX constant (PL/I) 185
PLAYBACK START when debugging multilanguage
using 111 applications 275
PLAYBACK STOP when debugging under CICS 250
using 111 Q when using a continuation
PLITEST 75 qualification character 188
description, for C and C++ 222 when using TEST 302, 304

restrictions (continued) session panel, while debugging starting (continued)
while debugging assembler assembler 232 Debug Tool from DB2 stored
programs 233 session settings procedures 85
RETRIEVE command changing in Debug Tool 171 Debug Tool in full-screen mode,
using 103 session variables introduction to 12
retrieving commands declaring, for COBOL 193 your program from Debug Tool
with RETRIEVE command 103 SET AUTOMONITOR ON command, Utilities 62
retrieving lines from Log or Source example 114 starting a full-screen debug session 83
windows 104 SET commands starting Debug Tool
RIGHT, SCROLL command 105 SET AUTOMONITOR __ctest(), using 75
RUN subcommand 244 using to record breakpoints 108 batch mode 81
run time viewing output from 97 DB2 program with TSO 244
environment, displaying attributes SET AUTOMONITOR ON from a program 69
of 222 monitoring values of starting your program for a debug
option, TEST(ERROR, ...), for variables 113 session 79
PL/I 202 SET DEFAULT SCROLL under CICS 79, 86, 88
options module, CEEUOPT 42 using 95 under CICS, using CEEUOPT 88
run-time options SET EQUATE under IMS 248
specifying the STORAGE option 67 using 171 under MVS in TSO 79
specifying the TRAP(ON) option 67 SET INTERCEPT using the TEST run-time option 63
specifying with COBOL and PL/I 67 using with C and C++ with PLITEST 75
running a program 109 programs 216 with the CEETEST function call 69
running in batch mode SET PFKEY within an enclave 277
considerations, TEST run-time using in Debug Tool 102 Starting Debug Tool
option 64 SET QUALIFY at different points 64
running your program, introduction using with COBOL 197 starting Debug Tool Utilities 9
to 14 using, for C and C++ 223 starting interactive function calls
RUNTO command SET REFRESH in C 146
using, to replay recorded using 253 starting your program 83
statements 111 SET SCROLL DISPLAY OFF statement tables, removing 256
using 95 statements
SET WARNING PL/I 199, 202
S setting
using with PL/I 204 recording and replaying, introduction
to 13
save file 287
line breakpoint 109 stdout, capturing output to
saving
setting breakpoints, in C++ 225 in C 146
setup file using Debug Tool
setting breakpoints, introduction to 15 in C++ 158
Utilities 61
settings STEP command
scope of objects in C and C++ 218
changing Debug Tool profile 175 using, to replay recorded
scroll area, Debug Tool 100
changing Debug Tool session 171 statements 111
SCROLL command
setup file stepping
using 104
copying JCL into, using DTSU 60 through a program 109
searching for characters or strings 105
creating, using Debug Tool through C++ programs 225
self-modifying code, restrictions for
Utilities 59 stepping, introduction to 13
debugging 233, 237
editing, using DTSU 59 stopping
separate debug file 25
saving, using Debug Tool Utilities 61 Debug Tool session 17
separate debug file, data set 286
setup files storage
separate debug file, finding
overview of 8 classes, for C 219
renamed 117
side files, how Debug Tool locates 289 storage errors, finding
session
single terminal mode (CICS) 249 overwrite
variables, for PL/I 202
size, reducing program 255 in assembler 170
session panel
sizing session panel windows 173 in C 148
changing colors and highlighting
source file in window, changing 105 in C++ 160
in 174
source file, finding renamed 117 in COBOL 130
changing window layout 172
source files, how Debug Tool locates 289 in PL/I 140
command line 100
Source window uninitialized
description 93
changing source files 105 in C 149
header fields 94
description 96 in C++ 160
navigating 104
displaying halted location 106 STORAGE run-time option,
opening and closing windows 173
retrieving lines from 104 specifying 67
order in which Debug Tool accepts
source, program storage, raw
commands from 101
displaying with Debug Tool 96 C, displaying 147
PF keys
start Debug Tool, implications of when C++, displaying 158
initial settings 103
to 22 COBOL, displaying 128
using 102
starting PL/I, displaying 138
windows
a debugging session in full-screen stored procedures
scrolling 105
mode through a VTAM terminal 85 DB2, debugging 245
Index 327
string substitution, using 171 TRAP(ON) run-time option, VS COBOL II, finding list for 198
strings specifying 67 VTAM
C, displaying 147 trigraph 182 starting a debugging session through
C++, displaying 158 trigraphs a, terminal 85
searching for in a window 105 using with C 182
substitution, using string 171 TSO
symbol tables, removing 256
syntax diagrams
starting Debug Tool using TEST
run-time option 83
W
warning, for PL/I 204
how to read xiii TSO command
what you need to debug 23
SYSDEBUG 286 using to debug DB2 program 243
window id area, Debug Tool 100
SYSTCPD 299 TSO, starting Debug Tool under 79
window, error numbers in 117
system commands, issuing, Debug
windows, Debug Tool session panel
Tool 101
changing configuration 172
U opening and closing 173
uninitialized storage errors, finding resizing 173
T in C 149 zooming 173
template in C++ 225 in C++ 160 workstation debugging
terminology, Debug Tool xii UNIX System Services See remote debug mode
TEST compiler option compiling a C program on 32
benefit of using 301 compiling a C++ program 35
debugging C when only a few parts
are compiled with 145
compiling a Enterprise PL/I program
on 29
Z
zooming a window, Debug Tool 173
debugging C++ when only a few using Debug Tool with 261
parts are compiled with 157 unsupported
debugging COBOL when only a few HLL modules, coexistence with 274
parts are compiled with 127 PL/I language elements 205
debugging PL/I when only a few UP, SCROLL command 105
parts are compiled with 137 USE file 64
for C 31 using Debug Tool
for C++ 35 finding renamed source, listing, or
for COBOL 25 separate debug file 117
for DB2 41
for PL/I 29
restrictions 302
specifying NUMBER option with 26
V
values
suboptions 25
assigning to C and C++
syntax of C 301
variables 209
syntax of C++ 303
assigning to COBOL variables 189
syntax of COBOL 304
variable
syntax of PL/I 307
modifying value
using #pragma statement to
in C 144
specify 33
in C++ 155
using for IMS 53
in COBOL 125
TEST run-time option
in PL/I 136
as parameter on RUN
using SET AUTOMONITOR ON
subcommand 244
command to monitor value of 113
example of 66
value, displaying 112
for PL/I 202
variables
specifying with #pragma 67
accessing program, for C and
suboption processing order 63
C++ 208
this pointer, in C++ 157
accessing program, for COBOL 189
trace, generating a COBOL run-time
assigning values to, for C and
paragraph 129
C++ 209
traceback, COBOL routine 128
assigning values to, for COBOL 189
traceback, function
compatible attributes in multiple
in assembler 170
languages 272
in C 147
displaying, for C and C++ 208
in C++ 159
displaying, for COBOL 191
in PL/I 138
HLL 266
tracing run-time path
qualifying 267
in C 148
session
in C++ 159
declaring, for C and C++ 210
in COBOL 128
session, for PL/I 202
in PL/I 138
viewing and modifying data members in
TRAP, Language Environment run-time
C++ 157
option 118, 269
VS COBOL II programs, debugging 198

Readers’ Comments — We’d Like to Hear from You
Debug Tool for z/OS
Debug Tool Utilities and Advanced Functions for z/OS
User’s Guide
Version 4 Release 1
Publication No. SC18-9012-00
Overall, how satisfied are you with the information in this book?
Very Satisfied Satisfied Neutral Dissatisfied Very

Dissatisfied
Overall satisfaction h h h h h
How satisfied are you that the information in this book is:
Very Satisfied Satisfied Neutral Dissatisfied Very

Dissatisfied
Accurate h h h h h
Complete h h h h h
Easy to find h h h h h
Easy to understand h h h h h
Well organized h h h h h
Applicable to your tasks h h h h h
Please tell us how we can improve this book:
Thank you for your responses. May we contact you? h Yes h No
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you.
Name Address
Company or Organization
Phone No.
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You Cut or Fold
SC18-9012-00 Along Line
_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation
Department H150/090
International Business Machines Corporation
555 Bailey Ave.
San Jose, CA
95141-9989
_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC18-9012-00 Along Line

Printed in USA
SC18-9012-00

Debug Tooluser

Uploaded by

Copyright:

Available Formats

Debug Tooluser

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Debug Tooluser

Uploaded by

Copyright:

Available Formats

Debug Tool for z/OS

Debug Tool Utilities and Advanced Functions for

First Edition (September 2003)

© Copyright IBM Corp. 1992, 2003 iii

Chapter 15. Starting Debug Tool by Part 4. Debugging your programs in

iv Debug Tool Version 4 Release 1 User’s Guide

vi Debug Tool Version 4 Release 1 User’s Guide

Chapter 31. Debugging an assembler Chapter 37. Debugging ISPF

Chapter 43. Debugging a Bibliography . . . . . . . . . . . . 313

viii Debug Tool Version 4 Release 1 User’s Guide

Who might use this document

The following operating systems and subsystems are supported:

Accessing z/OS licensed documents on the Internet

To register for access to the z/OS licensed documents:

© Copyright IBM Corp. 1992, 2003 ix

Using LookAt to look up message explanations

You can access LookAt from the Internet at:

How this document is organized

x Debug Tool Version 4 Release 1 User’s Guide

About this document xi

Terms used in this document

Debug Tool C and C++ COBOL PL/I equivalent assembler

xii Debug Tool Version 4 Release 1 User’s Guide

How to read syntax diagrams

Keywords, variables, and operators may be displayed as required, optional, or

About this document xiii

Variables appear in lowercase italics. They represent KEYWORD variable

xiv Debug Tool Version 4 Release 1 User’s Guide

An arrow returning to the left above the main path of the

How to send your comments

About this document xv

© Copyright IBM Corp. 1992, 2003 1

© Copyright IBM Corp. 1992, 2003 3

Debug Tool interfaces

4 Debug Tool Version 4 Release 1 User’s Guide

Remote debug mode

The Compiled language debugger is the remote debugger available through

Chapter 1. Debug Tool: overview 5

6 Debug Tool Version 4 Release 1 User’s Guide

© Copyright IBM Corp. 1992, 2003 7

Debug Tool Utilities: creating and managing setup files

Debug Tool Utilities: converting, compiling, and linking

Debug Tool Utilities: preparing assembler programs

Debug Tool Utilities: conducting code coverage

8 Debug Tool Version 4 Release 1 User’s Guide

Starting Debug Tool Utilities

To start Debug Tool Utilities, do one the following:

Chapter 2. Debug Tool Utilities and Advanced Functions: introduction 9

Compiling or assembling your program with the proper compiler

© Copyright IBM Corp. 1992, 2003 11

Starting Debug Tool

SOURCE: EMPLOOK --1----+----2----+----3----+----4----+----5----+ LINE: 1 OF 349

The screen is divided into four sections:

12 Debug Tool Version 4 Release 1 User’s Guide

Stepping through a program

Recording and replaying statements

Chapter 3. Debugging a program in full-screen mode: introduction 13

To begin recording, enter the following command:

To replay the statements that you record: