Planning your debug session
Before you begin debugging, create a plan that can help you make
the following choices:
- The compiler or assembler options and suboptions you need to use
when you compile or assemble programs.
- The debugging mode (batch, full-screen, full-screen mode using a dedicated terminal, or remote debug mode)
that you will use to interact with Debug Tool.
- The method or methods you can use to start Debug Tool.
- If you have older COBOL programs, as listed in the COBOL and CICS Command Level Conversion Aid for OS/390 & MVS & VM: User's Guide, how you want to debug them.
To help you create your plan, do the following tasks:
- Use Table 5 to record
the compiler options and suboptions that you will use for your programs.
The table contains compiler options that can provide the most debugging
capability with the smallest program size for a general set of compilers.
See Choosing compiler options for debugging for
the following information:
- The prerequisites required for a compiler option and suboption.
- Additional tasks that you might need to do to make a compiler
option and suboption work at your site.
- Information about how a compiler option and suboption might affect
program size and Debug Tool functionality.
- If you are using other Problem Determination Tools,
information on how to choose compiler options so that you create output
that can be used by the other Problem Determination Tools.
-
Use Table 3 to record
the debugging mode you will use. See Choosing a debugging mode to learn
about prerequisites and tasks you must do to make the debugging mode
work.
- Use Table 11 to
record the methods you will use to specify TEST runtime
options. See Choosing a method or methods for starting Debug Tool to help you
determine which method will work best for your programs.
- If you have older COBOL programs (as listed in the COBOL and CICS Command Level Conversion Aid for OS/390 & MVS & VM: User's Guide) that you want to debug, you must decide between
the following options:
- Leave them in their old source and possibly have to debug them
as non-Language Environment COBOL programs.
- Convert them to the 1985 COBOL Standard level.
See Choosing how to debug old COBOL programs for more
information.
After you have completed these tasks, use the information you collected
to follow the instructions in Updating your processes so you can debug programs with Debug Tool.
Compiler options affects the size of your load module and the amount
of Debug Tool functionality available to you. Debug Tool uses information
such as hooks and symbol tables to gain control of a program, run
the program statement-by-statement or line-by-line,
and display information about your program.
To learn more about how hooks and symbol tables help Debug Tool debug
your program, read the following topics:
To learn more about how the compiler options affect Debug Tool functionality,
read the following topics:
Table 5. Record the compiler options you need to use in this table. The options you use work with Debug Tool for z/OS, Version 10.1 or later.
| Compiler or assembler |
Compiler options you will use |
| OS/VS COBOL, Version 1 Release 2.4 |
NOTEST,SOURCE,DMAP,PMAP,VERB,XREF,NOLST,NOBATCH,NOSYMDMP,NOCOUNT or
______________________________________________________________
|
| VS COBOL II Version 1 Release 3 and Version 1 Release
4 (for programs compiled with the TEST compiler option
and linked with the Language Environment library.) |
TEST or
______________________________________________________________
|
| VS COBOL II Version 1 Release 3 and Version 1 Release
4 (for programs compiled with the NOTEST compiler option
and linked with a non-Language Environment library.) |
NOTEST,NOOPTIMIZE,SOURCE,MAP,XREF,LIST(or OFFSET) or
______________________________________________________________
|
| AD/Cycle® COBOL/370 Version 1 Release 1 |
TEST(ALL,SYM) or
______________________________________________________________
|
| COBOL for MVS™ &
VM |
TEST(ALL,SYM) or
______________________________________________________________
|
| COBOL for OS/390® &
VM |
TEST(NONE,SYM,SEPARATE) or
______________________________________________________________
|
| Enterprise COBOL for z/OS and OS/390, Version 3 |
TEST(NONE,SYM,SEPARATE) or
______________________________________________________________
|
| Enterprise COBOL for z/OS®, Version
4.1 or later |
TEST(NOHOOK,SEPARATE,EJPD) or
______________________________________________________________
|
| OS PL/I Version 2 Release 1, Version 2 Release
2, and Version 2 Release 3 |
TEST(ALL,SYM) or
______________________________________________________________
|
| PL/I for MVS &
VM |
TEST(ALL,SYM) or
______________________________________________________________
|
| Enterprise PL/I, Version 3.1 through Version 3.3 |
TEST(ALL,SYM) or
______________________________________________________________
|
| Enterprise PL/I, Version 3.4 |
TEST(ALL,NOHOOK,SYM) or
______________________________________________________________
|
| Enterprise PL/I, Version 3.5 or later |
TEST(ALL,NOHOOK,SYM,SEPARATE) or
______________________________________________________________
|
| Enterprise PL/I, Version 3.7 |
TEST(ALL,NOHOOK,SYM,SEPARATE,SOURCE) or
______________________________________________________________
|
| Enterprise PL/I, Version 3.8 or later |
TEST(ALL,NOHOOK,SYM,SEPARATE) and LISTVIEW or
______________________________________________________________
|
- AD/Cycle C/370™ Version
1 Release 1
- C/C++ for MVS/ESA Version
3 Release 1 or later
- C++ feature of OS/390 Version 2 Release 6 or later
- C++ feature of z/OS, Version 1.5 or earlier
|
TEST or
______________________________________________________________
|
- C feature of OS/390 Version 2 Release 6 or later
- C feature of z/OS, Version 1.5 or earlier
|
TEST(HOOK) or
______________________________________________________________
|
| C/C++ feature of z/OS, Version
1.6 or later |
DEBUG(FORMAT(DWARF)) or
______________________________________________________________
|
| IBM® High Level Assembler (HLASM),
Version 1 Release 4, Version 1 Release 5, Version 1 Release 6 |
ADATA |
Choosing TEST or NOTEST compiler suboptions for COBOL programs
This topic describes the combination of TEST compiler option and
suboptions you need to specify to obtain the desired debugging scenario.
This topic assumes you are compiling your COBOL program with Enterprise
COBOL for z/OS, Version 3.4, or later; however, the topics
provide information about alternatives to use for older versions of
the COBOL compiler.
The COBOL compiler provides the TEST compiler option
and its suboptions to control the following actions:
- The generation and placement of hooks and symbol tables.
- The placement of debug information into the object file or a separate
debug file.
The following instructions help you choose the combination of TEST compiler
suboptions that provide the functionality you need to debug your program:
-
Choose a debugging scenario,
keeping in mind your site's resources, from the following list:
- Scenario A: If you are compiling with Enterprise
COBOL for z/OS, Version 4.1 or later, you can get the most Debug Tool functionality
and a small program size by using TEST(NOHOOK,SEPARATE).
You need to have the Dynamic Debug facility installed and you might need the
Authorized Debug facility installed.
If you want to compile your program with the OPT(STD) or OPT(FULL) compiler
option, you must also specify the EJPD suboption of the TEST compiler
option to be able to do the following tasks:
- Use the GOTO or JUMPTO commands.
- Modify variables with predictable results.
When you use the EJPD suboption, you might lose some
optimization.
If you are using other Problem Determination
Tools, review the information in Enterprise COBOL for z/OS Version
4 programs to make sure
you specify all the compiler options you need to create the files
needed by all the Problem Determination Tools.
- Scenario B: If you are compiling with any of the following compilers,
you can get the most Debug Tool functionality and a small program size
by using TEST(NONE,SYM,SEPARATE):
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ63234.
You need to have the Dynamic Debug facility installed and you might need
the Authorized Debug facility installed.
If you want to compile your program with optimization
and be able to get the most Debug Tool functionality, you must compile
it with one of the following combination of compiler options:
- OPT(STD) TEST(NONE,SYM)
- OPT(STD) TEST(NONE,SYM,SEPARATE)
- OPT(FULL) TEST(NONE,SYM)
- OPT(FULL) TEST(NONE,SYM,SEPARATE)
For these types of programs, you can modify variables, but
the results might be unpredictable.
If you
are using other Problem Determination Tools, review the information
in Enterprise COBOL for z/OS Version
3 and COBOL for OS/390 and
VM programs to make sure you specify all the compiler options
you need to create the files needed by all the Problem Determination
Tools.
- Scenario C: To get all Debug Tool functionality but have a larger
program size and do not want debug information in a separate debug file,
compile with one of the following compiler options for the compilers
specified:
- TEST(HOOK,NOSEPARATE) with Enterprise COBOL for z/OS,
Version 4.1.
- TEST(ALL,SYM,NOSEPARATE) with any of the following
compilers:
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ40298
If you are using other Problem Determination Tools,
review the information in Enterprise COBOL for z/OS Version
4 programs or Enterprise COBOL for z/OS Version
3 and COBOL for OS/390 and
VM programs to
make sure you specify all the compiler options you need to create
the files needed by all the Problem Determination Tools.
- Scenario D: If you are using COBOL for OS/390 & VM, Version 2 Release 1,
or earlier, and you want to get all Debug Tool functionality, use TEST(ALL,SYM).
If you are using other Problem Determination Tools, review
the topic that corresponds to the compiler that you are using from
the following list to make sure you specify all the compiler options
you need to create the files needed by all the Problem Determination
Tools:
- Scenario E: You can get some Debug Tool functionality by compiling
with the NOTEST compiler option. This requires that you
debug your program in disassembly mode.
If you are using
other Problem Determination Tools, review the topic that corresponds
to the compiler that you are using from the following list to make
sure you specify all the compiler options you need to create the files
needed by all the Problem Determination Tools:
- For COBOL programs using IMS™, include
the IMS interface module DFSLI000 from the IMS RESLIB
library.
- For scenarios A, B and E, do the following steps:
- If you use the Dynamic Debug facility to place hooks into programs that
reside in read-only storage, verify with your system administrator
that the Authorized Debug facility has been installed and that you
are authorized to use it.
- Verify that the Dynamic Debug facility is installed on your system.
- After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility
by entering the QUERY DYNDEBUG command.
- Verify that the separate debug file is a non-temporary file and is available
during the debug session. The listing does not need to be saved.
- Verify whether you need to do any of the following tasks:
After you have chosen the compiler options and suboptions, see Planning your debug session to determine
the next task you must complete.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- Description of the TEST compiler option in Enterprise COBOL for z/OS Programming Guide
The following table explains the effects of the NOTEST compiler
option, the TEST compiler option, and some of the suboptions of the
TEST compiler option on Debug Tool behavior or the availability of features,
which are not described in Enterprise COBOL for z/OS Programming Guide:
Table 6. Description of the effects that the COBOL NOTEST compiler option and some of the TEST compiler suboptions have on Debug Tool.
| Name of compiler option or suboption |
Description of the effect |
| NOTEST |
- You cannot step through program statements.
- You can suspend execution of the program only at the initialization
of the main compile unit.
- You can include calls to CEETEST in your program to
allow you to suspend program execution and issue Debug Tool commands.
- You cannot examine or use any program variables.
- You can list storage and registers.
- 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.
- Because a statement table is not available, you cannot set any
statement breakpoints or use commands such as GOTO or QUERY location.
However, you can still debug your program using the disassembly
view. To learn how to use the disassembly view, see Debugging a disassembled program. |
| NONE and NOHOOK |
- You can use the GOTO or JUMPTO commands
when you debug a non-optimized program if you compile with
one of the following compilers:
- Enterprise COBOL for z/OS, Version 4.1
- any release of Enterprise COBOL for z/OS and OS/390,
Version 3
- any release of COBOL for OS/390 &
VM, Version 2
You can use the GOTO or JUMPTO command
when you debug an optimized program if you compile your program with
Enterprise COBOL for z/OS, Version 4.1, and specify the EJPD suboption
of the TEST compiler option. When you specify the EJPD suboption,
you might lose some optimization.
- A call to CEETEST can be used at any point to start Debug Tool.
|
| EJPD |
You
can modify variables in an optimized program that was compiled with
one the following compilers:
- Enterprise COBOL for z/OS,
Version 4.1
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 2 or later
- Enterprise COBOL for z/OS and OS/390, Version 3 Release 1 with APAR PQ63235 installed
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ63234 installed
However, results might be unpredictable. To obtain more predictable
results, compile your program with Enterprise COBOL for z/OS, Version 4.1, and specify
the EJPD suboption of the TEST compiler option.
However, variables that are declared with the VALUE clause to initialize
them cannot be modified. |
| NOSYM |
- You cannot reference program variables by name.
- You cannot use commands such as LIST or DESCRIBE to
access a variable or expression.
- You cannot use commands such as CALL variable to branch
to another program, or GOTO to branch to another label
(paragraph or section name).
If you are compiling with Enterprise COBOL for z/OS,
Version 4.1, the compiler ignores SYM or NOSYM and
always creates a symbol table. |
| STMT |
- 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.
- You can set breakpoints at all statements and step through your
program.
- Debug Tool cannot gain control at path points unless they are also
at statement boundaries.
- Branching to all statements and labels using the Debug Tool command GOTO is
allowed.
If you are compiling with Enterprise COBOL
for z/OS, Version 4.1, the compiler treats the STMT suboption
as if it were the HOOK suboption, which is equivalent to
the ALL suboption for any release of Enterprise COBOL for z/OS and OS/390,
Version 3, or COBOL for OS/390 & VM, Version 2. |
| PATH |
- 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.
- A call to CEETEST can be used at any point to start Debug Tool.
- The Debug Tool command GOTO is valid for all statements
and labels coinciding with path points.
If you are compiling with Enterprise COBOL
for z/OS, Version 4.1, the compiler treats the PATH suboption
as if it were the HOOK suboption, which is equivalent to
the ALL suboption for any release of Enterprise COBOL for z/OS and OS/390,
Version 3, or COBOL for OS/390 & VM, Version 2. |
| BLOCK |
- Debug Tool gains control at entry and exit of your program, methods,
and nested programs.
- Debug Tool can be explicitly started at any point with a call to CEETEST.
- Issuing a command such as STEP causes your program
to run until it reaches the next entry or exit point.
- GOTO can be used to branch to statements that coincide
with block entry and exit points.
If you are compiling with Enterprise COBOL
for z/OS, Version 4.1, the compiler treats the BLOCK suboption
as if it were the HOOK suboption, which is equivalent to
the ALL suboption for any release of Enterprise COBOL for z/OS and OS/390,
Version 3, or COBOL for OS/390 & VM, Version 2. |
| ALL |
- You can set breakpoints at all statements and path points, and
step through your program.
- 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.
- Branching to statements and labels using the Debug Tool command GOTO is
allowed.
If you are compiling with Enterprise COBOL
for z/OS, Version 4.1, the compiler treats the ALL suboption
as if it were the HOOK suboption, which is equivalent to
the ALL suboption for any release of Enterprise COBOL for z/OS and OS/390,
Version 3, or COBOL for OS/390 & VM, Version 2. |
Choosing TEST or NOTEST compiler suboptions for PL/I programs
This topic describes the combination of TEST compiler option and
suboptions you need to specify to obtain the desired debugging scenario.
This topic assumes you are compiling your PL/I program with Enterprise PL/I for z/OS,
Version 3.5, or later; however, the topics provide information about
alternatives to use for older versions of the PL/I compiler.
The PL/I compiler provides the TEST compiler option
and its suboptions to control the following actions:
- The generation and placement of hooks and symbol tables.
- The placement of debug information into the object file or separate debug file.
Debug Tool does not support debugging optimized PL/I programs.
Do not use compiler options other than NOOPTIMIZE,
The following instructions help you choose the combination of TEST
compiler suboptions that provide the functionality you need to debug
your program:
-
Choose a debugging scenario, keeping
in mind your site's resources, from the following list:
- Scenario A: If you are using Enterprise PL/I for z/OS, Version
3.8 or later, and you want to get the most Debug Tool functionality and
a small program size, use TEST(ALL,NOHOOK,SYM,SEPARATE) and
the LISTVIEW(SOURCE) compiler option. Verify that your
site installed the Dynamic Debug facility, and, if you need to debug programs
that are loaded into protected storage, installed the Authorized Debug
facility.
Consider the following options:
- You can specify
any of the LISTVIEW sub-options (SOURCE, AFTERALL, AFTERCICS, AFTERMACRO,
or AFTERSQL), as described in Enterprise PL/I for z/OS Programming Guide, to
display either the original source or the source after the specified
preprocessor.
- If you are debugging in full-screen mode
and you want to debug programs with INCLUDE files that have executable
code, specify the LISTVIEW(AFTERMACRO) compiler option
and, if you do not specify the MACRO compiler option, specify
the PP(MACRO(INCONLY)) compiler option.
- If you are debugging in remote debug mode
and you want to automonitor variables in INCLUDE files, specify the LISTVIEW(AFTERMACRO) compiler
option and, if you do not specify the MACRO compiler option,
specify the PP(MACRO(INCONLY)) compiler option.
If you are using other Problem Determination
Tools, see Enterprise PL/I Version 3.5 and later programs to make sure you specify all the
compiler options you need to create the files needed by all the Problem
Determination Tools.
- Scenario B: If you are using Enterprise PL/I for z/OS, Version
3.7, and you want to get the most Debug Tool functionality and a small
program size, use TEST(ALL,NOHOOK,SYM,SEPARATE,SOURCE).
Verify that your site installed the Dynamic Debug facility, and, if you need
to debug programs that are loaded into protected storage, installed
the Authorized Debug facility.
Consider the following options:
- You can substitute SOURCE with AFTERALL, AFTERCICS, AFTERMACRO,
or AFTERSQL, as described in Enterprise PL/I for z/OS Programming Guide.
- If you are debugging in full-screen mode
and you want to debug programs with INCLUDE files that have executable
code, specify the TEST(ALL,NOHOOK,SYM,SEPARATE,AFTERMACRO) compiler
options and, if you do not specify the MACRO compiler option,
specify the PP(MACRO(INCONLY)) compiler option.
- If you are debugging in remote debug mode
and you want to automonitor variables in INCLUDE files, specify the TEST(ALL,NOHOOK,SYM,SEPARATE,AFTERMACRO) compiler
options and, if you do not specify the MACRO compiler option,
specify the PP(MACRO(INCONLY)) compiler option.
If you are using other Problem Determination
Tools, see Enterprise PL/I Version 3.5 and later programs to make sure you specify all the
compiler options you need to create the files needed by all the Problem
Determination Tools.
- Scenario C: If you are using Enterprise PL/I for z/OS, Version
3.5 or 3.6, and you want to get most Debug Tool functionality and a small
program size, use TEST(ALL,NOHOOK,SYM,SEPARATE). You need
to have the Dynamic Debug facility installed and you might need to install
the Authorized Debug facility.
If you are using other
Problem Determination Tools, see Enterprise PL/I Version 3.5 and later programs to make sure
you specify all the compiler options you need to create the files
needed by all the Problem Determination Tools.
- Scenario D: If you are using Enterprise PL/I for z/OS, Version
3.4, and you want to debug your program without compiled-in
hooks, use TEST(ALL,NOHOOK,SYM). You need to have the Dynamic Debug facility
installed and you might need to install the Authorized Debug facility.
If you are using other Problem Determination Tools, see Enterprise PL/I Version 3.4 and earlier programs to make sure you specify all the compiler options
you need to create the files needed by all the Problem Determination
Tools.
- Scenario E: If you are using Enterprise PL/I for z/OS, Version
3.3 or earlier, and you want to get all Debug Tool functionality, use TEST(ALL,SYM).
If you are using other Problem Determination Tools, see Enterprise PL/I Version 3.4 and earlier programs or PL/I for MVS and VM and
OS PL/I programs to make sure you specify
all the compiler options you need to create the files needed by all
the Problem Determination Tools.
- Scenario F: You can get some Debug Tool functionality by compiling
with the NOTEST compiler option. This requires that you
debug your program in disassembly mode.
If you are using
other Problem Determination Tools, review the topic that corresponds
to the compiler that you are using from the following list to make
sure you specify all the compiler options you need to create the files
needed by all the Problem Determination Tools:
- For scenarios A, B, C, E, and F, do the following steps:
- If you use the Dynamic Debug facility to place hooks into programs that
reside in read-only storage, verify with your system administrator
that the Authorized Debug facility has been installed and that you
are authorized to use it.
- Verify that the Dynamic Debug facility is installed on your system.
- After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility
by entering the QUERY DYNDEBUG command.
- Verify that the separate debug file is a non-temporary file and is available
during the debug session.
- Verify whether you need to do any of the following tasks:
-
When you compile a program,
do not associate SYSIN with an in-stream data set (for example //SYSIN
DD *) because Debug Tool requires access to a permanent data set for the
source of the program you are debugging.
- If you are compiling a PL/I for MVS & VM or OS PL/I program and
to be able to view your listing while debugging in full-screen mode,
you must compile the program with the SOURCE compiler option.
The SOURCE compiler option is required to generate a listing
file. You must direct the listing to a non-temporary 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. In addition, you must link your program with the Language Environment SCEELKED library;
do not use the OS PL/I PLIBASE or SIBMBASE library.
If Debug Tool cannot
find the listing at this location, see Changing which file appears in the Source window.
After you have chosen the compiler options and suboptions, see Planning your debug session to determine the next task you must complete.
Table 7. Description of the effects that the PL/I NOTEST compiler option and the TEST compiler suboptions have on Debug Tool.
| Name of compiler option or suboption |
Description of the effect |
| NOTEST |
Some behaviors or features change when
you debug a PL/I program compiled with the NOTEST compiler
option. The following list describes these changes:
- You can list storage and registers.
- You can include calls to PLITEST or CEETEST in your program so
you can suspend running your program and issue Debug Tool commands.
- You cannot step through program statements. You can suspend running
your program only at the initialization of the main compile unit.
- You cannot examine or use any program variables.
- Because hooks at the statement level are not inserted, you cannot
set any statement breakpoints or use commands such as GOTO or QUERY
LOCATION.
- The source listing produced by the compiler cannot be used; therefore,
no listing is available during a debug session.
However, you can still debug your program using the disassembly
view. To learn how to use the disassembly view, see Debugging a disassembled program. |
| NOHOOK |
Some behaviors or features
change when you debug a PL/I program compiled with the NOHOOK suboption
of the TEST compiler option. The following list describes
these changes:
- For Debug Tool to generate overlay hooks, one of the suboptions
ALL, PATH, STMT or BLOCK must be in effect, but HOOK need not be specified,
and NOHOOK would be recommended.
- If NOHOOK is specified, ENTRY and EXIT breakpoints are the only
PATH breakpoints at which Debug Tool stops.
|
| NONE |
When you compile a PL/I
program with the NONE suboption of the TEST compiler
option, you can start Debug Tool at any point in your program by writing
a call to PLITEST or CEETEST in your program. |
| SYM |
Some behaviors or features
change when you debug a PL/I program compiled with the SYM suboption
of the TEST compiler option. The following list describes
these changes:
- 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.
- Enables support for the SET AUTOMONITOR ON command.
- Enables the support for labels as GOTO targets.
|
| NOSYM |
Some behaviors or features
change when you debug a PL/I program compiled with the NOSYM suboption
of the TEST compiler option. The following list describes
these changes:
- You cannot reference program variables by name.
- You cannot use commands such as LIST or DESCRIBE to access a variable
or expression.
- You cannot use commands such as CALL variable to branch to another
program, or GOTO to branch to another label (procedure or block name).
|
| BLOCK |
Some behaviors or features
change when you debug a PL/I program compiled with the BLOCK suboption
of the TEST compiler option. The following list describes
these changes:
- Enables Debug Tool to gain control at block boundaries: block
entry and block exit.
- When Dynamic Debug is not active and you use the HOOK compiler
option, you can gain control only at the entry and exit points of
your program and all entry and exit points of internal program blocks.
When you enter the STEP command, for example, your program
runs until it reaches the next block entry or exit point.
- When Dynamic Debug is active, you can set breakpoints at all statements
and step through your program.
- You cannot gain control at path points unless you also specify PATH.
- A call to PLITEST or CEETEST can be used to start Debug Tool at
any point in your program.
- Hooks are not inserted into an empty ON-unit or an ON-unit consisting
of a single GOTO statement.
|
| STMT |
Some behaviors or features
change when you debug a PL/I program compiled with the STMT suboption
of the TEST compiler option. The following list describes
these changes:
- You can set breakpoints at all statements and step through your
program.
- Debug Tool cannot gain control at path points unless they are also
at statement boundaries, unless you also specify PATH.
- Branching to all statements and labels using the Debug Tool command
GOTO is allowed.
|
| ALL |
Some behaviors or features
change when you debug a PL/I program compiled with the ALL suboption
of the TEST compiler option. The following list describes
these changes:
- You can set breakpoints at all statements and path points, and
STEP through your program.
- 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.
- Enables branching to statements and labels using the Debug Tool
command GOTO.
|
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- Description of the TEST compiler option in Enterprise PL/I for z/OS Programming Guide.
Choosing TEST or DEBUG compiler suboptions for C programs
This topic describes the combination of TEST or DEBUG compiler
options and suboptions you need to specify to obtain the desired debugging
scenario. This topic assumes you are compiling your C program with z/OS C/C++,
Version 1.6, or later; however, the topics provide information about
alternatives to use for older versions of the C compiler.
Choosing between TEST and DEBUG compiler
options
If you are compiling with z/OS C/C++, Version 1.5 or earlier, you must choose
the TEST compiler option.
The C/C++ compiler
option DEBUG was introduced with z/OS C/C++ Version 1.5. Debug Tool supports the DEBUG compiler
option in z/OS C/C++ Version
1.6 or later. The DEBUG compiler option replaces the TEST compiler
option that was available with previous versions of the compiler.
If you are compiling with z/OS C/C++, Version 1.6 or later, choose the DEBUG compiler
option and take advantage of the following benefits:
- For C++ programs, you can specify the HOOK(NOBLOCK) compiler
option, which can improve debug performance.
- For C and C++ programs, if you specify the FORMAT(DWARF) suboption
of the DEBUG compiler option, the load modules are smaller;
however, you must save the .dbg file in addition to the source file. Debug Tool needs
both of these files to debug your program.
- For C and C++ programs compiled with z/OS XL
C/C++, Version 1.10 or later, if you specify the FORMAT(DWARF) suboption
of the DEBUG compiler option, the load modules are smaller
and you can create .mdbg files with captured source. Debug Tool needs
only the .mdbg file to debug your program.
Choosing DEBUG compiler suboptions for C programs
This topic describes the debugging scenarios available, and how
to create a particular debugging scenario by choosing the correct DEBUG compiler
suboptions.
The C compiler provides the DEBUG compiler option and
its suboptions to control the following actions:
- The generation and placement of hooks and symbol tables.
- The placement of debug information into the object file or separate
debug file.
Debug Tool does not support debugging optimized C programs.
Do not use any OPTIMIZE compiler options other than NOOPTIMIZE or
OPTIMIZE(0).
The following instructions help you choose the combination of DEBUG compiler
suboptions that provide the functionality you need to debug your program:
-
Choose a debugging scenario,
keeping in mind your site's resources, from the following list:
- Scenario A: To get the most Debug Tool functionality,
a smaller program size, and better performance, use one of the following
combinations:
- Scenario A1: DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location)) and
you create .mdbg files
- Scenario A2: DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location)) and
you use only .dbg files
- Scenario B: To get all Debug Tool functionality but have a larger
program size and do not want the debug information in a separate file,
use the following combination:
DEBUG(FORMAT(ISD),HOOK(LINE,NOBLOCK,PATH),SYMBOL)
- Scenario C: You can get some Debug Tool functionality by compiling
with the NODEBUG compiler option. This requires that you
debug your program in disassembly mode.
For all scenarios, if you are using other Problem
Determination Tools, see z/OS XL C and C++ programs to make sure you specify
all the compiler options you need to create the files needed by all
the Problem Determination Tools.
- For the scenario you selected, verify that you
have the following resources:
- For scenario A, do the following tasks:
- If you create an .mdbg
file, do the following tasks:
- Verify
that you have applied the following PTFs for the products you are
running:
- For z/OS XL C/C++, Version
1.10: UK50219, UK50245, UK50246, UK50645
- For z/OS XL C/C++, Version
1.11: UK51669, UK51670, UK51671
- For z/OS Run-Time Library
Extension, Version 1.10, (UTIL, CDA, DBGLD): UK50221, UK50652, UK50220,
UK50252
- For z/OS Language Environment, Version
1.10: UK51883
- For z/OS Run-Time Library
Extension, Version 1.10, (UTIL, CDA, DBGLD): UK51674, UK51673, UK52065,
UK51803
- Specify the EQAXOPT MDBG,YES option in the EQAOPTS options file
(which requires Debug Tool to search for a .dbg file in a .mdbg file)1.
- Verify that the .dbg files are non-temporary files.
- Create the .mdbg file with captured source by using the -c
option for the dbgld command or the CAPSRC option on the CDADBGLD
utility.
- Verify that the .mdbg file is a non-temporary file.
- If you use only
.dbg files, verify that the .dbg files are non-temporary files and
specify the EQAXOPT MDBG,NO option in the EQAOPTS options file2.
- For scenario C, do the following steps:
- If you are running on z/OS Version 1.6 or Version 1.7, verify
that Language Environment PTF for APAR PK12833 is installed.
- If you use the Dynamic Debug facility to place hooks into programs that
reside in read-only storage, verify with your system administrator
that the Authorized Debug facility has been installed and that you
are authorized to use it.
- Verify that the Dynamic Debug facility is installed on your system.
- After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility
by entering the QUERY DYNDEBUG command.
- Verify whether you need to do any of the following tasks:
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- Description of the DEBUG compiler option in z/OS XL C/C++ User’s Guide
Choosing TEST or NOTEST compiler suboptions for C programs
This topic describes the debugging scenarios available, and how
to create a particular debugging scenario by choosing the correct TEST compiler
suboptions.
The C compiler provides the TEST compiler option and
its suboptions to control the generation and placement of hooks and
symbol tables.
Debug Tool does not support debugging optimized C programs.
Do not use compiler options other than NOOPTIMIZE,
The following instructions help you choose the combination of TEST compiler
suboptions that provide the functionality you need to debug your program:
-
Choose a debugging scenario, keeping
in mind your site's resources, from the following list:
- Scenario A: To get all Debug Tool functionality but have a larger
program size (compared to using DEBUG(FORMAT(DWARF))),
use TEST(ALL,HOOK,SYMBOL).
- Scenario B: You can get some Debug Tool functionality by compiling
with the NOTEST compiler option. This requires that you
debug your program in disassembly mode.
- Scenario C: If you are debugging programs
running in ALCS, you must compile with the HOOK suboption
of the TEST compiler option.
For all scenarios, if you are using other Problem
Determination Tools, see z/OS XL C and C++ programs to make sure you specify
all the compiler options you need to create the files needed by all
the Problem Determination Tools.
- For scenario B, do the following steps:
- If you are running on z/OS Version 1.6 or Version 1.7, verify
that Language Environment PTF for APAR PK12833 is installed.
- If you use the Dynamic Debug facility to place hooks into programs that
reside in read-only storage, verify with your system administrator
that the Authorized Debug facility has been installed and that you
are authorized to use it.
- Verify that the Dynamic Debug facility is installed on your system.
- After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility
by entering the SET DYNDEBUG OFF command.
- Verify whether you need to do any of the following tasks:
Table 8. Description of the effects that the C NOTEST compiler option and the TEST compiler suboptions have on Debug Tool.
| Name of compiler option or suboption |
Description of the effect |
| NOTEST |
The following list explains the effect the NOTEST
compiler option will have on how Debug Tool behaves or the availability
of features, which are not described in z/OS XL C/C++ User’s Guide:
- You cannot step through program statements. You can suspend execution
of the program only at the initialization of the main compile unit.
- You cannot examine or use any program variables.
- You can list storage and registers.
- You cannot use the Debug Tool command GOTO.
However, you can still debug your program using the disassembly
view. To learn how to use the disassembly view, see Debugging a disassembled program. |
| TEST |
The following list explains the effect some of
the suboptions of the TEST compiler option will have on how Debug Tool behaves
or the availability of features, which are not described in z/OS XL C/C++ User’s Guide:
- The maximum number of lines in a single source file cannot exceed
131,072.
- The maximum number of include files that have executable statements
cannot exceed 1024.
|
| NOSYM |
The following list explains
the effect the NOSYM suboption of the TEST compiler
option will have on how Debug Tool behaves or the availability of features,
which are not described in z/OS XL C/C++ User’s Guide.
- You cannot reference program variables by name.
- You cannot use commands such as LIST or DESCRIBE to
access a variable or expression.
- You cannot use commands such as CALL or GOTO to
branch to another label (paragraph or section name).
|
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- Description of the TEST compiler option in z/OS XL 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.
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:
- The hook for function entry is placed before any initialization
or statements for the function.
- The hook for function exit is placed just before actual function
return.
- The hook for nested block entry is placed before any statements
or initialization for the block.
- The hook for nested block exit is placed after all statements
for the block.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- z/OS XL C/C++ User’s Guide
Rules for placement of hooks in statements and path points
The following rules apply to the placement of hooks for statements
and path points:
- Label hooks are placed before the code and all other statement
or path point hooks for the statement.
- The statement hook is placed before the code and path point hook
for the statement.
- A path point hook for a statement is placed before the code for
the statement.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- z/OS XL C/C++ User’s Guide
Choosing TEST or DEBUG compiler suboptions for C++ programs
This topic describes the combination of TEST or DEBUG compiler
options and suboptions you need to specify to obtain the desired debugging
scenario. This topic assumes you are compiling your C++ program with z/OS C/C++,
Version 1.6, or later; however, the topics provide information about
alternatives to use for older versions of the C++ compiler.
Choosing between TEST and DEBUG compiler
options
If you are compiling with z/OS C/C++, Version 1.5 or earlier, you must choose
the TEST compiler option.
The C/C++ compiler
option DEBUG was introduced with z/OS C/C++ Version 1.5. Debug Tool supports the DEBUG compiler
option in z/OS C/C++ Version
1.6 or later. The DEBUG compiler option replaces the TEST compiler
option that was available with previous versions of the compiler.
If you are compiling with z/OS C/C++, Version 1.6 or later, choose the DEBUG compiler
option and take advantage of the following benefits:
- For C++ programs, you can specify the HOOK(NOBLOCK) compiler
option, which can improve debug performance.
- For C and C++ programs, if you specify the FORMAT(DWARF) suboption
of the DEBUG compiler option, the load modules are smaller;
however, you must save the .dbg file in addition to the source file. Debug Tool needs
both of these files to debug your program.
- For C and C++ programs compiled with z/OS XL
C/C++, Version 1.10 or later, if you specify the FORMAT(DWARF) suboption
of the DEBUG compiler option, the load modules are smaller
and you can create .mdbg files with captured source. Debug Tool needs
only the .mdbg file to debug your program.
Choosing DEBUG compiler suboptions for C++ programs
This topic describes the debugging scenarios available, and how
to create a particular debugging scenario by choosing the correct DEBUG compiler
suboptions.
The C++ compiler provides the DEBUG compiler option
and its suboptions to control the following actions:
- The generation and placement of hooks and symbol tables.
- The placement of debug information into the object file or separate
debug file.
Debug Tool does not support debugging optimized C programs.
Do not use any OPTIMIZE compiler options other than NOOPTIMIZE or
OPTIMIZE(0).
The following instructions help you choose the combination of DEBUG compiler
suboptions that provide the functionality you need to debug your program:
-
Choose a debugging scenario,
keeping in mind your site's resources, from the following list:
- Scenario A: To get the most Debug Tool functionality,
a smaller program size, and better performance, use one of the following
combinations:
- Scenario A1: DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location)) and
you create .mdbg files
- Scenario A2: DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location)) and
you use only .dbg files
- Scenario B: To get all Debug Tool functionality but have a larger
program size and do not want the debug information in a separate file,
use the following combination:
DEBUG(FORMAT(ISD),HOOK(LINE,NOBLOCK,PATH),SYMBOL)
- Scenario C: You can get some Debug Tool functionality by compiling
with the NODEBUG compiler option. This requires that you
debug your program in disassembly mode.
For all scenarios, if you are using other Problem
Determination Tools, see z/OS XL C and C++ programs to make sure you specify
all the compiler options you need to create the files needed by all
the Problem Determination Tools.
- For the scenario you selected, verify that you
have the following resources:
- For scenario A, do the following tasks:
- If you create an .mdbg
file, do the following tasks:
- Verify
that you have applied the following PTFs for the products you are
running:
- For z/OS XL C/C++, Version
1.10: UK50219, UK50245, UK50246, UK50645
- For z/OS XL C/C++, Version
1.11: UK51669, UK51670, UK51671
- For z/OS Run-Time Library
Extension, Version 1.10, (UTIL, CDA, DBGLD): UK50221, UK50652, UK50220,
UK50252
- For z/OS Language Environment, Version
1.10: UK51883
- For z/OS Run-Time Library
Extension, Version 1.10, (UTIL, CDA, DBGLD): UK51674, UK51673, UK52065,
UK51803
- Specify the EQAXOPT MDBG,YES option in the EQAOPTS options file
(which requires Debug Tool to search for a .dbg file in a .mdbg file)3.
- Verify that the .dbg files are non-temporary files.
- Create the .mdbg file with captured source by using the -c
option for the dbgld command or the CAPSRC option on the CDADBGLD
utility.
- Verify that the .mdbg file is a non-temporary file.
- If you use only
.dbg files, verify that the .dbg files are non-temporary files and
specify the EQAXOPT MDBG,NO option in the EQAOPTS options file4.
- For scenario C, do the following steps:
- If you are running on z/OS Version 1.6 or Version 1.7, verify
that Language Environment PTF for APAR PK12833 is installed.
- If you use the Dynamic Debug facility to place hooks into programs that
reside in read-only storage, verify with your system administrator
that the Authorized Debug facility has been installed and that you
are authorized to use it.
- Verify that the Dynamic Debug facility is installed on your system.
- After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility
by entering the QUERY DYNDEBUG command.
- Verify whether you need to do any of the following tasks:
After you have chosen the compiler options and suboptions, see Planning your debug session to determine the next task you must complete.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- Description of the DEBUG compiler option in z/OS XL C/C++ User’s Guide
Choosing TEST or NOTEST compiler options for C++ programs
This topic describes the debugging scenarios available, and how
to create a particular debugging scenario by choosing the correct TEST compiler
suboptions.
The C++ compiler provides the TEST compiler option and
its suboptions to control the generation and placement of hooks and
symbol tables.
Debug Tool does not support debugging optimized C++ programs.
Do not use compiler options other than NOOPTIMIZE,
The following instructions help you choose the combination of TEST compiler
suboptions that provide the functionality you need to debug your program:
-
Choose a debugging scenario, keeping
in mind your site's resources, from the following list:
- Scenario A: To get all Debug Tool functionality but have a larger
program size (compared to using DEBUG(FORMAT(DWARF))),
use TEST.
- Scenario B: You can get some Debug Tool functionality by compiling
with the NOTEST compiler option. This requires that you
debug your program in disassembly mode.
- Scenario C: If you are debugging programs
running in ALCS, you must compile with the HOOK suboption
of the TEST compiler option.
For all scenarios, if you are using other Problem
Determination Tools, see z/OS XL C and C++ programs to make sure you specify
all the compiler options you need to create the files needed by all
the Problem Determination Tools.
- Verify whether you need to do any of the following tasks:
After you have chosen the compiler options and suboptions, see Planning your debug session to determine the next task you must complete.
Table 9. Description of the effects that the C++ NOTEST and TEST compiler option have on Debug Tool.
| Name of compiler option or suboption |
Description of the effect |
| NOTEST |
The following list explains the effect of the NOTEST compiler
has on Debug Tool behavior, which are not described in z/OS XL C/C++ User’s Guide:
- You cannot step through program statements. You can suspend execution
of the program only at the initialization of the main compile unit.
- You cannot examine or use any program variables.
- You can list storage and registers.
- You cannot use the Debug Tool command GOTO.
However, you can still debug your program using the disassembly
view. To learn how to use the disassembly view, see Debugging a disassembled program. |
| TEST |
The following list explains the effect the TEST compiler
has on Debug Tool behavior, which are not described in z/OS XL C/C++ User’s Guide:
- The maximum number of lines in a single source file cannot exceed
131,072.
- The maximum number of include files that have executable statements
cannot exceed 1024.
|
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- Description of the TEST compiler option in z/OS XL C/C++ User’s Guide
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:
- The hook for function entry is placed before any initialization
or statements for the function.
- The hook for function exit is placed just before actual function
return.
- The hook for nested block entry is placed before any statements
or initialization for the block.
- The hook for nested block exit is placed after all statements
for the block.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- z/OS XL C/C++ User’s Guide
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:
- Label hooks are placed before the code and all other statement
or path point hooks for the statement.
- The statement hook is placed before the code and path point hook
for the statement.
- A path point hook for a statement is placed before the code for
the statement.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- z/OS XL C/C++ User’s Guide
Understanding how hooks work and why you need them
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 or NOHOOK, the compiler inserts
hooks into your program.
How the Dynamic Debug facility can help you get maximum performance
without hooks
In the following situations, you can compile or create a program
without hooks. Then, you can use the Dynamic Debug facility to insert hooks
at runtime whenever you set a breakpoint or enter the STEP command:
- Assembler, disassembly, and non-Language Environment COBOL programs
do not contain hooks.
- If you use Enterprise COBOL for z/OS, Version
4.1, you can compile your programs without hooks by using the TEST(NOHOOK) compiler
option.
- If
you use one of the following compilers, you can compile your programs
without hooks by using the TEST(NONE) compiler option:
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1, with APAR PQ40298
- If you use the Enterprise PL/I for z/OS, Version
3.4 or later, compiler, you can compile your programs without hooks
by using the TEST(NOHOOK) compiler option.
The Dynamic Debug facility can also help improve the performance of Debug Tool while
debugging programs compiled with any of the following compilers:
- any COBOL compiler supported by Debug Tool
- any PL/I compiler supported by Debug Tool
- any C/C++ compiler supported by Debug Tool
When you compile with one the following compilers and have the
compiler insert hooks, you can enhance the program's performance while
you debug it by using the Dynamic Debug facility:
- any COBOL compiler supported by Debug Tool
- any PL/I compiler supported by Debug Tool
- any C/C++ compiler supported by Debug Tool
When you start Debug Tool, the Dynamic Debug facility is activated. Debug Tool will
use the hooks inserted by the Dynamic Debug facility instead of the hooks inserted
by the compiler. This means that some path breakpoints might be unavailable.
If you need to use those breakpoints, deactivate the Dynamic Debug
facility by entering the SET DYNDEBUG OFF command. Debug Tool will
then use the hooks inserted by the compiler instead of the hooks inserted
by the Dynamic Debug facility.
Understanding what symbol tables do and why saving them elsewhere
can make your application smaller
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 or assemble your programs
with one of the following compilers or assembler:
- Enterprise COBOL for z/OS, Version 4.1
- Enterprise COBOL for z/OS and OS/390, Version 3
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ40298
- OS/VS COBOL Version 1, Release 2.4
- Enterprise PL/I for z/OS, Version 3 Release 5 or later
- High Level Assembler for MVS &
VM & VSE, Release 4 or later
Saving symbol tables in a separate debug file can reduce the size
of the load module for your program.
For C and C++ programs, debug tables can be saved in a separate debug file (.dbg
file) by specifying the FORMAT(DWARF) suboption of the DEBUG compiler
option. Debug Tool supports the DEBUG compiler option shipped
with z/OS C/C++ Version 1.6 or later.
Choosing a debugging mode
Use the following list to determine which debugging mode to use
for your programs:
- For TSO programs
- Choose full-screen mode. If you want to use a supported
remote debugger, choose remote debug mode.
- For JES batch programs
- If you want to interact with your batch program, choose full-screen mode using a dedicated terminal.
If you want to interact with your batch program using a supported
remote debugger, choose remote debug mode. If you don't want to interact
with your batch program, use batch mode and specify commands through
a commands file and review results in a log file.
- For UNIX® System Services programs
- Choose full-screen mode using a dedicated terminal. If you want to use a supported remote debugger,
choose remote debug mode.
- For CICS® programs
- If you want to interact with Debug Tool on a 3270 device, choose
full-screen mode and one of the following terminal modes:
- Single terminal mode: The application program and Debug Tool share
the same terminal. Use this terminal mode to debug a transaction that
interacts with a 3270 terminal. When you create your CADP or DTCN
profile, set the Display Device to the terminal ID that the application
program uses.
- Screen control mode: Debug Tool displays its screens on a terminal
running the DTSC transaction.
If you use screen control mode, the
DTSC transaction runs in the same region as your application program
on a terminal of your choice, and displays Debug Tool screens on behalf
of the task you are debugging, which might not have its own terminal.
Use
screen control mode to debug application programs which are not typically
associated with a terminal, and which are running in an MRO environment.
Screen
control mode works in the following manner:
- Enter DTSC on the terminal that you want to use to
display Debug Tool. This terminal can be connected directly to the region
where the application program runs, or connected to the region with
CRTE or Transaction Routing. If you use Transaction Routing, you must
ensure that DTSC runs in the same region as the application program
using it.
- Set the Display Device in your DTCN or CADP profile to the terminal
running the DTSC transaction.
- Start the application program.
- Press Enter on the terminal running the DTSC transaction to connect
to Debug Tool.
- Separate terminal mode (formerly called
Dual Terminal Mode): Debug Tool dynamically
starts the CDT# transaction on a terminal.
Use separate terminal
mode to debug application programs which are not typically associated
with a terminal, and your terminal is connected directly to the region
running your application program.
Separate terminal mode works
in the following manner:
- Set the Display Device in your DTCN or CADP profile to an available
terminal and that terminal can be located by the CICS region running Debug Tool.
- Start the application program.
If you want to debug your program with a remote debugger,
select remote debug mode. Make note of the TCP/IP address of your remote
debugger because you will need it when you update your CADP or DTCN
profile.
If you do not use single terminal mode and your program
sends a screen to the terminal without the WAIT option, CICS Terminal Control holds that
screen until the program runs an EXEC CICS SEND
or EXEC CICS RECEIVE statement.
If you want to debug programs that use Distributed
Program Link (DPL), you can select one of the following debugging
modes:
- For DB2® programs
- Choose full-screen mode using a dedicated terminal. If you want to use a supported remote debugger,
choose remote debug mode.
- For DB2 Stored Procedures
- Choose full-screen mode using a dedicated terminal. If you want to use a supported remote debugger,
choose remote debug mode.
- For IMS TM programs
- Choose full-screen mode using a dedicated terminal. If you want to use a supported remote debugger,
choose remote debug mode.
- For IMS batch programs
- If you want to interact with your IMS batch
programs, choose full-screen mode using a dedicated terminal. If you want to interact with your IMS batch
programs with a supported remote debugger, choose remote debug mode. If
you do not want to interact with your IMS batch
program, choose batch mode and specify commands through a commands
file and review results in a log file.
- For IMS BTS programs
- If you want your program and your debugging session to run on
a single screen, choose full-screen mode. If you want your BTS data
to display on your TSO terminal and your debugging session to display
on another terminal, choose full-screen mode using a dedicated terminal. If you want your BTS data to
display on your TSO terminal and your debugging session to display
on a supported remote debugger, choose remote debug mode.
- For ALCS programs
- You must choose remote debug mode.
Refer to the following topics for more information
related to the material discussed in this topic.
- Related
references
- IMS/VS Batch Terminal
Simulator Program Reference and Operations Manual
Debugging in browse mode
When you debug in some production environments, it might be necessary
to restrict your ability to change storage contents and execution
flow. Debugging in browse mode enables you to debug your programs
while restricting your ability to change storage contents and execution
flow. Debug Tool uses the RACF® authority
of the current user, an entry in the EQAOPTS load module, or both
to determine whether to operate in browse mode.
When you debug in browse mode, you can not do the following actions:
- Modify the contents of memory or registers
- Alter the sequence of program execution
You can use the QUERY BROWSE MODE command to determine
if browse mode is active.
C and C++ programs cannot be run in browse mode. If you
try to run a C or C++ program in browse mode, Debug Tool writes a message
to the system log and terminates with a U1991 abend.
For information on how to install and control browse mode, see Debug Tool Customization Guide.
Browse mode debugging in full screen, line, and
batch mode
If you are debugging in full screen, line, or batch mode; browse
mode is active; and you enter any of the following commands, Debug Tool displays
a message that the command is not permitted in browse mode:
- ALLOCATE command
- Assignment command (assembler and disassembly)
- Assignment command (non-Language Environment COBOL)
- Assignment command (PL/I)
- CALL %CECI command
- CALL entry_name (COBOL)
- CALL %FM command
- CALL %HOGAN command
- CLEAR LOG command
- COMPUTE command
- FREE command
- GO BYPASS command
- GOTO command
- GOTO LABEL command
- INPUT command
- JUMPTO command
- JUMPTO LABEL command
- MEMORY command (Debug Tool displays the Memory window,
but you cannot modify anything)
- MOVE command
- QUIT command
- QUIT expression command
- QQUIT command
- SET INTERCEPT command
- SET command (COBOL)
- STORAGE command
- SYSTEM command
- TRIGGER command
- TSO command
If you enter a command with an expression or condition that
might alter any storage, register, or similar data, or the command
invokes any user-written function or alters the sequence of execution, Debug Tool displays
a message that the command is not permitted in browse mode:
- do/while
- DO command (PL/I)
- EVALUATE command (COBOL)
- expression command (C and C++)
- for command (C and C++)
- %IF command
- IF command
- LIST expression command
- switch command
- while command
Browse mode debugging in remote debug mode
When you use the remote debugger and browse mode is active, the
remote debugger does not allow you to do the following actions:
- JumpTo Location - Source window RMB action
- Change Value - Expression, Variable, and Registers RMB
action
- Typing over memory in the Memory window
In addition, the remote debugger enforces following restrictions:
- Change Value - the remote debugger does not allow Registers
RMB action and displays an error message
- Terminate Button - the program terminates with an abend
(instead, click on Disconnect to continue running the program without
the debugger)
Also, the remote debugger does not allow you to enter the following
Debug Console commands:
- JUMPTO (and JUMPTO in the Action field of
the Add a Breakpoint window)
- SET INTERCEPT
- QUIT
If an abend occurs while debugging in remote debug mode and browse
mode is active, the remote debugger does not give you any continuation
options. You can not continue program execution after the abend occurs.
Controlling browse mode
Browse mode can be controlled (activated or deactivated) by changing RACF access, customizing EQAOPTS,
both of these, or neither of these. To control browse mode through RACF access, change your RACF access to the following RACF Facilities:
- For CICS:
EQADTOOL.BROWSE.CICS
- For non-CICS: EQADTOOL.BROWSE.MVS
To control browse mode through EQAOPTS, set the EQAXOPT BROWSE
option to either ON or OFF.
The following table shows how combinations of these control methods
(by RACF access or by customizing
EQAOPTS) can activate or deactivate browse mode. For instructions
using these controls see Debug Tool Customization Guide.
Table 10. How different combinations of RACF access and EQAXOPT BROWSE settings activate or deactivate browse mode.
| Status of RACF access |
Setting
of EQAXOPT BROWSE option |
| Not set (use RACF status) |
ON |
OFF |
| facility (access) not defined |
normal mode (browse mode is not active) |
browse mode is active |
normal mode |
| ACCESS=NONE |
Cannot use Debug Tool |
Cannot use Debug Tool |
Cannot use Debug Tool |
| ACCESS=READ |
browse mode is active |
browse mode is active |
browse mode is active |
| ACCESS=UPDATE (or higher) |
normal mode |
browse mode is active |
normal mode |
Table 11 indicates
that there are several different methods to start Debug Tool for each
type of program. In this topic, you will read about the circumstances
in which each applicable method works for each type of program. Then
you can select which method would work best for your site. After you
complete this topic, you will have selected the methods that work
best for your programs.
Table 11. Methods for specifying the TEST runtime options and the programs that support these methods.
|
Use the EQADBCXT user exit routine |
Use the EQADICXT user exit routine |
Use the EQADDCXT user exit routine |
Use the DFSBXITA user exit |
Use the CADP transaction |
Use the DTCN transaction |
Use the DB2 catalog |
From within a program by coding a call to CEETEST,
__ctest(), or PLITEST |
Through CEEUOPT or CEEROPT |
Use the CEEOPTS DD statement in JCL or CEEOPTS
allocation in TSO |
Use the parameters on the EXEC statement when
you start your program |
Use the parameters on the RUN statement
when you start your program |
Use the parameters on the CALL statement
when you start your program |
Through the EQASET transaction3 |
Through the EQANMDBG program4 |
| TSO |
|
|
|
|
|
|
|
X |
X |
X |
|
|
X |
|
X4 |
| JES batch |
X |
|
|
|
|
|
|
X |
X |
X |
X |
|
|
|
X4 |
| UNIX System Services |
|
|
|
|
|
|
|
X |
X |
X |
|
|
|
|
|
| CICS |
|
|
|
|
X |
X |
|
X |
X1 |
|
|
|
|
|
|
| DB2 |
|
|
|
|
|
|
|
X |
X1 |
X |
|
X |
|
|
|
| DB2 stored procedures (PROGRAM TYPE=MAIN) |
|
|
X |
|
|
|
X2 |
X |
X1,2 |
|
|
|
|
|
|
| DB2 stored procedures (PROGRAM TYPE=SUB) |
|
|
|
|
|
|
X |
X |
|
|
|
|
|
|
|
| IMS TM |
|
X |
|
X |
|
|
|
X |
X |
|
|
|
|
X3 |
|
| IMS batch |
X |
|
|
X |
|
|
|
X |
X |
|
|
|
|
|
X4 |
| IMS BTS |
X |
X |
|
X |
|
|
|
X |
X |
|
|
|
|
|
X4 |
|
Notes:
- You cannot use CEEROPT to specify TEST runtime options.
- The DB2 catalog method always takes precedence over
CEEUOPT.
- This method is only for non-Language Environment assembler programs.
- This method is only for non-Language Environment programs.
|
The following list describes the methods for starting Debug Tool for
each type of program. As you read through this list, select the method
that best applies to your situation and record your selection on your
copy of Table 11.
- For TSO programs
- For programs that start in Language Environment, choose the CEEOPTS
allocation in TSO for the most flexible method of specifying the runtime
options.
Choose the parameters on the CALL statement option
if you have a small number of runtime options or need to invoke EQANMDBG
for a non-Language Environment program.
If you choose to code a call to
CEETEST, __ctest(), or PLITEST, you will have to recompile your program
every time you want to change the options.
- For JES batch programs
- For programs that start in Language Environment, choose the CEEOPTS
DD statement in your JCL for the most flexible method of specifying
runtime options.
Choose the parameters on the EXEC statement
option if you have a small number of runtime options or need to invoke
EQANMDBG for a non-Language Environment program.
If you choose to
code a call to CEETEST, __ctest(), or PLITEST, you will have to recompile
your program every time you want to change the options.
- For UNIX System Services programs
- Specify the TEST runtime options by setting the _CEE_RUNOPTS
environment variable. If you choose to code a call to CEETEST, __ctest(),
or PLITEST, you will have to recompile your program every time you
want to change the options.
- For CICS programs
- Choose either the DTCN or CADP transaction to create and store
a profile that contains the TEST runtime options. If you
choose to code a call to CEETEST, __ctest(), or PLITEST, you will
have to recompile your program every time you want to change the options.
- For DB2 programs
- Choose the CEEOPTS DD statement in JCL or CEEOPTS allocation
in TSO for the most flexible method of specifying runtime options.
Choose
the parameters on the RUN statement option if you have a small number
of runtime options.
If you choose to code a call to CEETEST,
__ctest(), or PLITEST, you will have to recompile your program every
time you want to change the options.
- For DB2 stored procedures that have the
PROGRAM TYPE of MAIN
- Choose through the Language Environment EQADDCXT exit routine. You can
run the stored procedure with your own set of suboptions. Another
user can run or debug the stored procedure with his own set of suboptions.
Therefore, multiple users can run or debug the stored procedure at
the same time.
If the exit routine is not available at your site,
choose the DB2 catalog. However, you are limited to specifying
one specific set of suboptions, which means that every user that runs
or debugs that stored procedure uses the same set of suboptions.
If
you select both methods, the Language Environment exit routine takes precedence
over the DB2 catalog.
- For DB2 stored procedures that have the
PROGRAM TYPE of SUB
- Choose through the DB2 catalog. You are limited to specifying
one set of suboptions, which means that every user that runs or debugs
that stored procedure uses the same set of suboptions.
- For IMS TM programs
- Choose through the EQADICXT user exit routine. If your program
is a non-Language Environment assembler program, choose through the EQASET
transaction.
If the EQADICXT user exit routine is not available
at your site, choose through the DFSBXITA user exit routine.
If
the EQADICXT or DFSBXITA user exit routines are not available at your
site, choose through CEEUOPT or CEEROPT.
If none of the previous
options are available at your site, choose to code a call to CEETEST,
__ctest(), or PLITEST. However, you will have to recompile your program
every time you want to change the options.
- For IMS batch programs
- Choose through the EQADBCXT user exit routine. If your program
is a non-Language Environment program, choose through the EQANMDBG program.
If
the EQADBCXT user exit routine is not available at your site, choose
through the DFSBXITA user exit routine, however, you must specify
PROGRAM rather than TRANSACTION.
If the EQADBCXT or DFSBXITA
user exit routines are not available at your site, choose through
CEEUOPT or CEEROPT.
If none of the previous options are available
at your site, choose to code a call to CEETEST, __ctest(), or PLITEST.
However, you will have to recompile your program every time you want
to change the options.
- For IMS BTS programs
- Choose through the EQADICXT user exit routine. If your program
is a non-Language Environment program, choose through the EQANMDBG program.
If
the EQADICXT user exit routine is not available at your site, choose
through the EQADBCXT user exit routine.
If the EQADBCXT user
exit routine is not available at your site, choose through the DFSBXITA
user exit routine.
If the EQADICXT, EQADBCXT, or DFSBXITA user
exit routines are not available at your site, choose through CEEUOPT
or CEEROPT.
If none of the previous options are available at
your site, choose to code a call to CEETEST, __ctest(), or PLITEST.
However, you will have to recompile your program every time you want
to change the options.
After you have identified the method or methods you will use to
start Debug Tool, see Planning your debug session to determine the next task you
must complete.
Choosing how to debug old COBOL programs
Programs compiled with the OS/VS COBOL compiler can be debugged
by doing one of the following:
- Debug them as non-Language Environment COBOL programs.
- Convert them to the 1985 COBOL Standard level and compile
them with the Enterprise COBOL for z/OS and OS/390 or COBOL for OS/390 & VM compiler. You can use
the Load Module Analyzer to identify OS/VS COBOL programs in a load
module, then use COBOL and CICS Command Level Conversion Aid
(CCCA) to convert the programs.
To convert an OS/VS COBOL program to 1985 COBOL Standard, do the
following steps:
- Identify the OS/VS COBOL programs in your load module by using
the Load Module Analyzer. For instructions on using Load Module Analyzer,
see Appendix H. Debug Tool Load Module Analyzer.
-
Convert your OS/VS COBOL source by using
COBOL and CICS Command Level Conversion Aid (CCCA). For instructions
on using CCCA, see COBOL and CICS Command Level Conversion Aid for OS/390 & MVS & VM User's Guide.
-
Compile the new source with either the Enterprise COBOL for z/OS and OS/390 or COBOL for OS/390 & VM.
You
can combine steps 2 and 3 by using the Convert
and Compile option of Debug Tool Utilities.
- Debug the object module by using Debug Tool.
After you convert and debug your program, you can do one of the
following options:
- Continue to use the OS/VS COBOL compiler. Every time you want
to debug your program, you need to do the steps described in this
section.
- Use the new source that was produced by the steps described in
this section. You can compile the source and debug it without repeating
the steps described in this section.
CCCA 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.
In
situations where you can specify environment variables, you can set
the environment variable EQA_USE_MDBG to YES or NO, which overrides
any setting (including the default setting) of the EQAXOPT MDBG option.
In
situations where you can specify environment variables, you can set
the environment variable EQA_USE_MDBG to YES or NO, which overrides
any setting (including the default setting) of the EQAXOPT MDBG option.
In
situations where you can specify environment variables, you can set
the environment variable EQA_USE_MDBG to YES or NO, which overrides
any setting (including the default setting) of the EQAXOPT MDBG option.
In
situations where you can specify environment variables, you can set
the environment variable EQA_USE_MDBG to YES or NO, which overrides
any setting (including the default setting) of the EQAXOPT MDBG option.
|
This information center is powered by Eclipse technology. (http://www.eclipse.org)