About this document
Debug Tool combines the richness
of the z/OS® environment 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) with Language Environment and
assembler programs either with or without Language Environment.
Throughout this document, the HLLs are referred to as C, C++, COBOL,
and PL/I.
Debug Tool runs on the z/OS operating
system and supports the following subsystems:
- CICS®
- DB2®
- IMS™
- JES batch
- TSO
- UNIX System Services in remote debug mode
or full-screen mode using a dedicated 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:
- Sign in to Resource
Link using your Resource
Link user ID and password.
- 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.
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 of the IBM 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 use LookAt from the following locations to find IBM message explanations for z/OS elements and features, z/VM®, VSE/ESA, and Clusters for AIX® and Linux:
- The Internet. You can access IBM message
explanations directly from the LookAt Web site at http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/.
- Your z/OS TSO/E host system.
You can install code on your z/OS or z/OS.e systems to access IBM message explanations, using
LookAt from a TSO/E command line (for example, TSO/E prompt, ISPF,
or z/OS UNIX System Services running OMVS).
- Your Microsoft Windows workstation. You can
install code to access IBM message
explanations on the z/OS Collection (SK3T-4269), using LookAt from a Microsoft Windows command
prompt (also known as the DOS command line).
- Your wireless handheld device. You can use the LookAt Mobile Edition
with a handheld device that has wireless access and an Internet browser
(for example, Internet Explorer for Pocket PCs, Blazer, or Eudora
for Palm OS, or Opera for Linux handheld
devices). Link to the LookAt Mobile Edition from the LookAt Web site.
You can obtain code to install LookAt on your host system or Microsoft Windows workstation from a disk on your z/OS Collection (SK3T-4269), or from the LookAt Web
site (click Download, and select the platform,
release, collection, and location that suit your needs). More information
is available in the LOOKAT.ME files available during the download
process.
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:
- 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 describes a simple scenario of how to use Debug Tool in
full-screen mode, introducing you to some basic commands that
you might use frequently.
- Part 2 groups together information about how to prepare programs
for debugging. The following list describes each chapter:
- Chapter 3 describes how to choose compiler options, debugging
mode, and runtime options so that you can prepare programs for debugging.
It also describes your options for debugging COBOL programs compiled
with compilers that are now out-of-service.
- Chapter 4 describes how to implement the choices you made in chapter
3.
- Chapter 5 describes how to prepare a non-Language Environment COBOL
program.
- Chapter 6 describes how to prepare an assembler program.
- Chapter 7 describes how to prepare a DB2 program.
- Chapter 8 describes how to prepare a DB2 stored
procedures program.
- Chapter 9 describes how to prepare a CICS program.
- Chapter 10 describes how to prepare an IMS program.
- Chapter 11 describes how to include a call to the TEST runtime
option into a program.
- Part 3 groups together information that describes the different
methods you can use to start Debug Tool. The following list describes
each chapter:
- Chapter 12 describes how to write the TEST runtime
option to indicate how and when you want to start Debug Tool.
- Chapter 13 describes how to start Debug Tool from Debug Tool Utilities.
- Chapter 14 describes how to start Debug Tool from a program.
- Chapter 15 describes how to start Debug Tool for your batch or TSO
programs.
- Chapter 16 describes how to start Debug Tool from CICS programs.
- Chapter 17 describes how to start Debug Tool in full-screen mode.
- Chapter 18 describes how to start Debug Tool in full-screen mode using a dedicated terminal. This chapter
also describes some tips to starting Debug Tool from a stored procedure.
- 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 19 provides overview information about full-screen mode.
- Chapter 20 provides a sample COBOL program to describe how to
debug it in full-screen mode.
- Chapter 21 provides a sample OS/VS COBOL program as representative
of non-Language Environment COBOL programs 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 and save those changes, as well as other settings,
into files.
- 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 non-Language Environment COBOL
programs.
- Chapter 30 describes how to use Debug Tool commands to debug PL/I
programs.
- Chapter 31 describes how to use Debug Tool commands to debug C or
C++ programs.
- Chapter 32 describes how to use Debug Tool commands to debug assembler
programs.
- Chapter 33 describes how to use Debug Tool commands to debug disassembly
programs.
- Part 6 groups together information about debugging DB2, DB2 stored
procedures, IMS, CICS, ISPF, UNIX System Services, and production-level programs.
- Chapter 34 describes how to debug a DB2 program.
- Chapter 35 describes how to debug a DB2 stored
procedure.
- Chapter 36 describes how to debug an IMS program.
- Chapter 37 describes how to debug a CICS program.
- Chapter 38 describes how to debug an ISPF program.
- Chapter 39 describes how to debug a production-level program.
- Chapter 40 describes how to debug a program running in the UNIX System Services shell.
- Chapter 41 describes how to debug programs that do not start or
run in Language Environment.
- Part 7 groups together information about how to debug programs
written in multiple language or running in multiple processes.
- Chapter 42 describes how to debug a program written in multiple
languages.
- Chapter 43 describes the restrictions when you debug a multithreaded
program.
- Chapter 44 describes how to debug a program that runs across multiple
processes and enclaves.
- Chapter 45 describes how to debug a multiple-enclave interlanguage
communication (ILC) application.
- Chapter 46 describes how to debug programs that are
called by Java native methods.
- Chapter 47 describes how to instruct Debug Tool to handle
problems created by program names or the large size of programs.
- Part 8 groups together appendixes. The following list describes
each appendix:
- Appendix A describes the data sets that Debug Tool uses to retrieve
and store information.
- Appendix B describes the process Debug Tool uses to locate source,
listing, or side files.
- Appendix C describes the compiler options you should choose to
create programs that can be used by all the Problem Determination
Tools, eliminating recompiles when you want to switch tools.
- Appendix D 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 E provides information about debugging a program in batch
mode.
- Appendix F describes how to use the DTST transaction
to display and modify CICS storage.
- Appendix G describes how to use Load Module Analyzer,
a stand-alone program that is shipped with Debug Tool.
- Appendix H describes how you can use the DTNP transaction,
supplied by Debug Tool, to load a new copy of a program into an active CICS region.
- Appendix I describes how to install IBM Debug Tool DTCN and DTSP Profile Manager plug-in.
- Appendix J describes the resources that are available
to help you solve any problems you might encounter with Debug Tool.
- Appendix K describes the features and tools available
to people with physical disabilities that help them use Debug Tool and Debug Tool documents.
The last several topics 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 term |
C and C++ equivalent |
COBOL or non-Language Environment COBOL
equivalent |
PL/I equivalent |
assembler |
| Compile unit |
C and C++ source file |
Program or class |
- Program
- PL/I source file for Enterprise PL/I
- A package statement or the name of the main procedure for Enterprise PL/I1
|
CSECT |
| Block |
Function or compound statement |
Program, nested program, method or PERFORM group
of statements |
Block |
CSECT |
| Label |
Label |
Paragraph name or section name |
Label |
Label |
Notes:
- The PL/I program must be compiled with and run in one of the following
environments:
- Compiled with Enterprise PL/I for z/OS,
Version 3.6 or later, and run with the following versions of Language Environment:
- Language Environment Version 1.9, or later
- Language Environment Version 1.6, Version 1.7, or Version 1.8, with the PTF
for APAR PK33738 applied
- Compiled with Enterprise PL/I for z/OS,
Version 3.5, with the PTFs for APARs PK35230 and PK35489 applied and
run with the following versions of Language Environment:
- Language Environment Version 1.9, or later
- Language Environment Version 1.6, Version 1.7, or Version 1.8, with the PTF
for APAR PK33738 applied
Debug Tool provides facilities that apply only to programs compiled
with specific levels of compilers. Because of this, Debug Tool User’s Guide uses the following terms:
- assembler
- Refers to assembler programs with debug information assembled
by using the High Level Assembler (HLASM).
- COBOL
- Refers to the all COBOL compilers supported by Debug Tool except
the COBOL compilers described in the term
non-Language Environment COBOL.
- 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.
- Enterprise PL/I
- Refers to the Enterprise PL/I for z/OS and OS/390® and the VisualAge® PL/I for OS/390 compilers.
- non-Language Environment COBOL
- Refers to any of the following COBOL programs:
- Programs compiled with the IBM OS/VS
COBOL compiler.
- Programs compiled with the VS COBOL II compiler with the NOTEST compiler
option and linked with a non-Language Environment library.
As you read through the information in this document, remember
that OS/VS COBOL programs are non-Language Environment programs, even though
you might have used Language Environment libraries to link and run your program.
VS COBOL II programs are non-Language Environment programs when you
compile them with the NOTEST compiler option and link them
with a non-Language Environment library. VS COBOL II programs are Language Environment programs
when you compile them with the TEST compiler option and
link them with the Language Environment library.
Read the information regarding non-Language Environment programs for instructions
on how to start Debug Tool and debug non-Language Environment COBOL programs,
unless information specific to non-Language Environment COBOL is provided.
- PL/I
- Refers to all levels of PL/I compilers. Exceptions will be noted
in the text that describe which specific PL/I compiler is being referenced.
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:
- Keywords - a command name or any other literal information.
- Variables - variables are italicized, appear in lowercase and
represent the name of values you can supply.
- Delimiters - delimiters indicate the start or end of keywords,
variables, or operators. For example, a left parenthesis is a delimiter.
- Operators - operators include add (+), subtract (-), multiply
(*), divide (/), equal (=), and other mathematical operations that
may need to be performed.
- Fragment references - a part of a syntax diagram, separated from
the diagram to show greater detail.
- 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
- 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.
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:
- 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.
- Send your comments by email to comments@us.ibm.com.
Be sure to include the name of the book, the part number of the book,
the version of Debug Tool, and, if applicable, the specific location of
the text you are commenting on (for example, a page number or table
number).
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.