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 11.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
______________________________________________________________
|
| Enterprise PL/I, Version 4.1 or later |
TEST(ALL,NOHOOK,SYM,SEPARATE) and LISTVIEW and GONUMBER(SEPARATE) 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:
- If you are using Enterprise PL/I for z/OS, Version 4.1 or later, you can specify the GONUMBER(SEPARATE) compiler option, which can help make the program size smaller. You must install the PTF for APAR PM19445 on Language Environment, Version 1.10 to Version 1.12.
- 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 Version 3.6 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 Version 3.6 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 Version 3.6 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:
DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location))
The compiler options are the same whether you use only .dbg files or also use .mdbg 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
YES for the EQAOPTS MDBG command (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 NO for the EQAOPTS MDBG command2.
- 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 runtime 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:
DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location))
The compiler options are the same whether you use only .dbg files or also use .mdbg 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
YES for the EQAOPTS MDBG command (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 NO for the EQAOPTS MDBG command4.
- 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 EQAOPTS command, 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.
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, specifying the EQAOPTS BROWSE command, 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 an EQAOPTS command, specify either ON or OFF for the EQAOPTS BROWSE command.
The following table shows how combinations of these control methods (by RACF access or by the EQAOPTS BROWSE command) 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 the EQAOPTS BROWSE command activate or deactivate browse mode.
| Status of RACF access |
Setting of the EQAOPTS BROWSE command |
| 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 subsystems 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) |
|
|
X5 |
|
|
|
X |
X |
|
|
|
|
|
|
|
| IMS TM |
|
X |
|
X |
|
|
|
X |
X |
|
|
|
|
X3 |
|
| IMS batch |
X |
|
|
X |
|
|
|
X |
X |
X |
|
|
|
|
X4 |
| IMS BTS |
X |
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.
- This method is only for DB2 stored procedures invoked with the call_sub function.
|
For each subsystem, Table 11 shows that you can choose from several different methods of specifying the TEST runtime options. The following list can help you select the method that best applies to your situation, ordered by flexibility and convenience:
- For TSO programs
-
- For programs that start in Language Environment, specify the TEST runtime options using the CEEOPTS allocation in TSO for the most flexible method of specifying the runtime options.
- Specify the TEST runtime options using the parameters on the CALL statement if you have a small number of runtime options or need to invoke EQANMDBG for a non-Language Environment program.
- If you specify the TEST runtime options by coding 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, specify the TEST runtime options using the CEEOPTS DD statement in your JCL for the most flexible method of specifying runtime options.
- Specify the TEST runtime options using 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 specify the TEST runtime options by coding 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 specify the TEST runtime options by coding 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
-
- Specify the TEST runtime options using either the DTCN or CADP transaction to create and store a profile that contains the TEST runtime options.
- If you specify the TEST runtime options by coding 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
-
- Specify the TEST runtime options using the CEEOPTS DD statement in JCL or CEEOPTS allocation in TSO for the most flexible method of specifying runtime options.
- Specify the TEST runtime options using the parameters on the RUN statement option if you have a small number of runtime options.
- If you specify the TEST runtime options by coding 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
-
- Specify the TEST runtime options using 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 a separate 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, specify the TEST runtime options using 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 implement both methods, the Language Environment exit routine takes precedence over the DB2 catalog.
- For DB2 stored procedures that have the PROGRAM TYPE of SUB
-
- For programs invoked with the call_sub function, specify the TEST runtime options using the Language Environment EQADDCXT exit routine. You can run or debug the DB2 stored procedure with your own set of suboptions, while another user can run or debug the DB2 stored procedure with a separate set of suboptions.
If the exit routine is not available at your site, specify the TEST runtime options using 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.
If you implement methods, the Language Environment exit routine takes precedence over the DB2 catalog.
- For programs invoked by any other method, specify the TEST runtime options using 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
-
- Specify the TEST runtime options using 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, specify the TEST runtime options using the DFSBXITA user exit routine.
- If the EQADICXT or DFSBXITA user exit routines are not available at your site, specify the TEST runtime options using CEEUOPT or CEEROPT.
- If none of the previous options are available at your site, specify the TEST runtime options by coding 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
-
- For programs that start in Language Environment, specify the TEST runtime options using the CEEOPTS allocation in JCL because this method can be the most flexible method.
- Specify the TEST runtime options using 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, specify the TEST runtime options using 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, specify the TEST runtime options using CEEUOPT or CEEROPT.
- If none of the previous options are available at your site, specify the TEST runtime options by coding 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
-
- For programs that start in Language Environment, specify the TEST runtime options using the CEEOPTS allocation in JCL because this method can be the most flexible method.
- Specify the TEST runtime options using 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, specify the TEST runtime options using the EQADBCXT user exit routine.
- If the EQADBCXT user exit routine is not available at your site, specify the TEST runtime options using the DFSBXITA user exit routine.
- If the EQADICXT, EQADBCXT, or DFSBXITA user exit routines are not available at your site, specify the TEST runtime options using CEEUOPT or CEEROPT.
- If none of the previous options are available at your site, specify the TEST runtime options by coding 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 G. 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 EQAOPTS MDBG command.
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 EQAOPTS MDBG command.
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 EQAOPTS MDBG command.
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 EQAOPTS MDBG command.