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.
This document contains descriptions of the commands,
functions, and variables available through Debug Tool, as well as the
messages that you might see as you use Debug Tool. Many Debug Tool commands
are similar to statements from the supported high-level languages
(HLLs). This document also describes the TEST runtime
option, syntax elements that are common for all commands, and syntax
elements for expressions written in assembler, disassembly, and non-Language Environment COBOL.
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:
- Chapter 1 describes the syntax of the TEST runtime
option.
- Chapters 2, 3, 4, and 5 describe the complete syntax of the Debug Tool commands.
- Chapter 6 describes the complete syntax of the EQAOPTS
commands.
- Chapters 7 and 8 describe the syntax of Debug Tool built-in
functions and variables.
- Chapters 9, 10, 11, 12, 13 and 14 lists all the messages
that Debug Tool and other tools shipped with Debug Tool might display.
- Appendix A. Debug Tool commands supported in remote debug mode has a list of commands
that are supported in remote debug mode. This topic also contains instructions
on how you can enter these commands.
- Appendix B. Changes in behavior of some commands describes changes
to default behavior, including a comparison of the previous behavior
and the new behavior, and with which version and release of Debug Tool the
change was introduced.
- Appendix C. Support resources and problem solving information describes the resources available to
help you solve any problems you might have with Debug Tool.
- Appendix D. Accessibility 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 Reference and Messages 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.