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.

z/OS® Debugger 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:

  1. Choose a debugging scenario, keeping in mind your site's resources, from the following list:
    • Scenario A: To get all z/OS Debugger functionality but have a larger program size (compared to using DEBUG(FORMAT(DWARF))), use TEST.
    • Scenario B: You can get some z/OS Debugger 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 Application Delivery Foundation for z/OS tools, see IBM® Application Delivery Foundation for z/OS Common Components Customization Guide and User Guide to make sure you specify all the compiler options you need to create the files needed by all the Application Delivery Foundation for z/OS tools.

  2. 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 z/OS Debugger requires access to a permanent data set for the source of the program you are debugging.

    • The C++ TEST compiler option implicitly specifies the GONUMBER compiler option, which causes the compiler to generate line number tables that correspond to the input source file. You can explicitly remove this option by specifying NOGONUMBER. When the TEST and NOGONUMBER options are specified together, z/OS Debugger does not display the current execution line as you step through your code.
    • Programs that are compiled with both the TEST compiler option and either the OPT(1) or OPT(2) compiler option do not have hooks at line, block, and path points, or generate a symbol table. Only hooks for function entry and exit points are generated for optimized programs.

After you have chosen the compiler options and suboptions, see Planning your debug session to determine the next task you must complete.

Table 1. Description of the effects that the C++ NOTEST and TEST compiler option have on z/OS Debugger.
Name of compiler option or suboption Description of the effect
NOTEST

The following list explains the effect of the NOTEST compiler has on z/OS Debugger 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 z/OS Debugger 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 z/OS Debugger 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