Rational Developer for System z, Version 7.6

Planning your debug session

Before you begin debugging, create a plan that can help you make the following choices:

To help you create your plan, do the following tasks:

  1. 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:
  2. 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.
  3. Use Table 10 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.
  4. 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: 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.

Choosing compiler options for debugging

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 9.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 following instructions help you choose the combination of TEST compiler suboptions that provide the functionality you need to debug your program:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
  2. For COBOL programs using IMS™, include the IMS interface module DFSLI000 from the IMS RESLIB library.
  3. For scenarios A, B and E, do the following steps:
    1. 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.
    2. Verify that the Dynamic Debug facility is installed on your system.
    3. After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility by entering the QUERY DYNDEBUG command.
    4. 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.
  4. 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.

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 following instructions help you choose the combination of TEST compiler suboptions that provide the functionality you need to debug your program:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
  2. For scenarios A, B, C, E, and F, do the following steps:
    1. 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.
    2. Verify that the Dynamic Debug facility is installed on your system.
    3. After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility by entering the QUERY DYNDEBUG command.
    4. Verify that the separate debug file is a non-temporary file and is available during the debug session.
  3. 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 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.

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

The C/C++ compiler option DEBUG(FORMAT(DWARF)) 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.

Compile your program with the DEBUG(FORMAT(DWARF)) compiler option to place the debug information in a separate debug file (.dbg file), which reduces the size of your load module. During a debug session, Debug Tool obtains information from .dbg file and the source file.

You can debug programs that are a combination of compile units compiled with the TEST and DEBUG compiler options.

Refer to the z/OS XL C/C++ User’s Guide for more information about the TEST and DEBUG compiler options.

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 following instructions help you choose the combination of DEBUG compiler suboptions that provide the functionality you need to debug your program:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
  2. For the following scenarios, verify that you have the following resources:
  3. 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.

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.

The following instructions help you choose the combination of TEST compiler suboptions that provide the functionality you need to debug your program:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
  2. For scenario B, do the following steps:
    1. If you are running on z/OS Version 1.6 or Version 1.7, verify that Language Environment PTF for APAR PK12833 is installed.
    2. 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.
    3. Verify that the Dynamic Debug facility is installed on your system.
    4. After you start Debug Tool, verify that you have not deactivated the Dynamic Debug facility by entering the SET DYNDEBUG OFF command.
  3. 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.

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:

Refer to the following topics for more information related to the material discussed in this topic.

Rules for placement of hooks in statements and path points

The following rules apply to the placement of hooks for statements and path points:

Refer to the following topics for more information related to the material discussed in this topic.

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

The C/C++ compiler option DEBUG(FORMAT(DWARF)) 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.

Compile your program with the DEBUG(FORMAT(DWARF)) compiler option to place the debug information in a separate debug file (.dbg file), which reduces the size of your load module. During a debug session, Debug Tool obtains information from .dbg file and the source file.

You can debug programs that are a combination of compile units compiled with the TEST and DEBUG compiler options.

Refer to the z/OS XL C/C++ User’s Guide for more information about the TEST and DEBUG compiler options.

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 following instructions help you choose the combination of DEBUG compiler suboptions that provide the functionality you need to debug your program:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
  2. For the following scenarios, verify that you have the following resources:
  3. 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.

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.

The following instructions help you choose the combination of TEST compiler suboptions that provide the functionality you need to debug your program:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
  2. 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.

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:

Refer to the following topics for more information related to the material discussed in this topic.

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:

Refer to the following topics for more information related to the material discussed in this topic.

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:

The Dynamic Debug facility can also help improve the performance of Debug Tool while debugging programs compiled with any of the following compilers:

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:

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:

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 through a VTAM 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 through a VTAM 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:

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.

For DB2® programs
Choose full-screen mode through a VTAM terminal. If you want to use a supported remote debugger, choose remote debug mode.
For DB2 Stored Procedures
Choose full-screen mode through a VTAM terminal. If you want to use a supported remote debugger, choose remote debug mode.
For IMS TM programs
Choose full-screen mode through a VTAM 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 through a VTAM 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 through a VTAM 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.

Refer to the following topics for more information related to the material discussed in this topic.

Choosing a method or methods for starting Debug Tool

Table 10 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 10. 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:
  1. You cannot use CEEROPT to specify TEST runtime options.
  2. The DB2 catalog method always takes precedence over CEEUOPT.
  3. This method is only for non-Language Environment assembler programs.
  4. 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 10.

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:

To convert an OS/VS COBOL program to 1985 COBOL Standard, do the following steps:

  1. 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 G. Debug Tool Load Module Analyzer.
  2. 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.
  3. 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.

  4. Debug the object module by using Debug Tool.

After you convert and debug your program, you can do one of the following options:

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.


Terms of use | Feedback

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