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.

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(ALL,HOOK,SYMBOL).
    • 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 topic z/OS XL C and C++ programs in 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. 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. After you start z/OS Debugger, 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:

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

    • If you are using #pragma statements to specify your TEST or NOTEST compiler options, see Compiling your C program with the #pragma statement.
    • 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, regardless of the TEST suboptions specified. Only hooks for function entry and exit points are generated for optimized programs.
    • You can specify any number of TEST suboptions, including conflicting suboptions (for example, both PATH and NOPATH). The last suboptions that are specified take effect. For example, if you specify TEST(BLOCK, NOBLOCK, BLOCK, NOLINE, LINE), what takes effect is TEST(BLOCK, LINE) because BLOCK and LINE are specified last.
    • No duplicate hooks are generated even if two similar TEST suboptions are specified. For example, if you specify TEST(BLOCK, PATH), the BLOCK suboption causes the generation of hooks at entry and exit points. The PATH suboption also causes the generation of hooks at entry and exit points. However, only one hook is generated at each entry and exit point.
Table 1. Description of the effects that the C NOTEST compiler option and the TEST compiler suboptions have on z/OS Debugger.
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 z/OS Debugger 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 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 some of the suboptions of the TEST compiler option will have on how z/OS Debugger 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 z/OS Debugger 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