Rational Developer for System z, Version 7.6

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:

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.

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®:

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:

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:
  1. The PL/I program must be compiled with and run in one of the following environments:

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:

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, 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.

Table 1. Syntax examples
Item Syntax example
Required item.

Required items appear on the main path of the horizontal line. You must specify these items.

Read syntax diagramSkip visual syntax diagram>>-KEYWORD--required_item--------------------------------------><
 
Required choice.

A required choice (two or more items) appears in a vertical stack on the main path of the horizontal line. You must choose one of the items in the stack.

Read syntax diagramSkip visual syntax diagram>>-KEYWORD--+-required_choice1-+-------------------------------><
            '-required_choice2-'
 
Optional item.

Optional items appear below the main path of the horizontal line.

Read syntax diagramSkip visual syntax diagram>>-KEYWORD--+---------------+----------------------------------><
            '-optional_item-'
 
Optional choice.

An optional choice (two or more items) appears in a vertical stack below the main path of the horizontal line. You may choose one of the items in the stack.

Read syntax diagramSkip visual syntax diagram>>-KEYWORD--+------------------+-------------------------------><
            +-optional_choice1-+
            '-optional_choice2-'
 
Default.

Default items appear above the main path of the horizontal line. The remaining items (required or optional) appear on (required) or below (optional) the main path of the horizontal line. The following example displays a default with optional items.

Read syntax diagramSkip visual syntax diagram            .-default_choice1--.
>>-KEYWORD--+------------------+-------------------------------><
            +-optional_choice2-+
            '-optional_choice3-'
 
Variable.

Variables appear in lowercase italics. They represent names or values.

Read syntax diagramSkip visual syntax diagram>>-KEYWORD--variable-------------------------------------------><
 
Repeatable item.

An arrow returning to the left above the main path of the horizontal line indicates an item that can be repeated.

A character within the arrow means you must separate repeated items with that character.

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.

Read syntax diagramSkip visual syntax diagram            .-----------------.
            V                 |
>>-KEYWORD----repeatable_item-+--------------------------------><
 
Read syntax diagramSkip visual syntax diagram            .-,---------------.
            V                 |
>>-KEYWORD----repeatable_item-+--------------------------------><
 
Fragment.

The -| fragment |- symbol indicates that a labelled group is described below the main syntax diagram. Syntax is occasionally broken into fragments if the inclusion of the fragment would overly complicate the main syntax diagram.

Read syntax diagramSkip visual syntax diagram>>-KEYWORD--| fragment |---------------------------------------><
 
fragment:
 
|--+-,required_choice1----------------------+-------------------|
   |                   .-,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:

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.


Terms of use | Feedback

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