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 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:
- 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 through
a VTAM® 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 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 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 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 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 the features and tools available to people
with physical disabilities that help them use Debug Tool and Debug Tool documents.
- Appendix I describes the resources that are available to help
you solve any problems you might encounter with Debug Tool.
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 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:
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.
|
This information center is powered by Eclipse technology. (http://www.eclipse.org)