TEST | NOTEST

Category

Error checking and debugging

Pragma equivalent

#pragma options(test) (C only), #pragma options(notest) (C only)

Purpose

Generates debugging information that Debug Tool needs to debug your program.

Defaults

For C++, the default option is NOTEST(HOOK). For C, the default option is: NOTEST(HOOK,SYM,BLOCK,LINE,PATH).

The default for the z/OS UNIX System Services utilities is NOTEST.

Parameters

The TEST suboptions parameters that are common to C compile, C++ compile, and IPA link steps are:

Additional z/OS XL C compile suboptions parameters are:

SYM

Generates symbol tables in the object output of the program that give you access to variables and other symbol information.

• You can reference all program variables by name, allowing you to examine them or use them in expressions.
• You can use the Debug Tool command GOTO to branch to a label (paragraph or section name).
• Specify NOSYM if you want to trace the program with the Performance Analyzer.

BLOCK

Inserts only block entry and exit hooks into the object output of the program. A block is any number of data definitions, declarations, or statements that are enclosed within a single set of braces. Symbol information is generated for all variables within a block regardless of BLOCK suboption.

• Specify NOBLOCK if you want to trace the program with the Performance Analyzer.

LINE

Generates hooks at most executable statements. Hooks are not generated for the following:

• Lines that identify blocks (lines that contain braces)
• Null statements
• Labels
• Statements that begin in an #include file
• Specify NOLINE if you want to trace the program with the Performance Analyzer.

PATH

Generates hooks at all path points; for example, hooks are inserted at if-then-else points.

• This option does not influence the generation of entry and exit hooks for nested blocks. You must specify the BLOCK suboption if you need such hooks.
• 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.
• The Debug Tool command GOTO is valid only for statements and labels that coincide with path points.
• Specify PATH if you want to trace the program with the Performance Analyzer.

ALL

Inserts block and line hooks, and generates symbol table. Hooks are generated at all statements, all path points (if-then-else, calls, and so on), and all function entry and exit points.

ALL is equivalent to TEST(HOOK, BLOCK, LINE, PATH, SYM).

NONE

Generates all compiled-in hooks only at function entry and exit points. Block hooks and line hooks are not inserted, and the symbol tables are suppressed.

TEST(NONE) is equivalent to TEST(HOOK, NOBLOCK, NOLINE, NOPATH, NOSYM).

Usage

The TEST suboptions generate symbol tables and program hooks. Debug Tool uses these tables and hooks to debug your program. The Performance Analyzer uses these hooks to trace your program. The choices you make when compiling your program affect the amount of Debug Tool function available during your debugging session. These choices also impact the ability of the Performance Analyzer to trace your program.

To look at the flow of your code with Debug Tool, or to trace the flow of your code with the Performance Analyzer, use the HOOK suboption with OPT in effect. These suboptions generate function entry, function exit, function call, and function return hooks. They do not generate symbol information.

When NOOPT is in effect, and you use the HOOK suboption, the debugger runs slower, but all Debug Tool commands such as AT ENTRY * are available. You must specify the HOOK suboption in order to trace your program with the Performance Analyzer.

In order for the debugger to access the source lines, the primary source file of a compilation unit should come from one file (or sequential data set or PDS member), and not be the result of concatenated DD statements. This is because only the name of the first data set is known to the compiler reading the concatenation; the debug information generated in this case would contain only the first data set name. All the source files, including header files, should not be temporary files, and should be available to the debugger under the same name as used during compilation.

You can use the CSECT option with the TEST option to place your debug information in a named CSECT. This enables the compiler and linker to collect the debug information in your module together, which may improve the runtime performance of your program.

If you specify the INLINE and TEST compiler options when NOOPTIMIZE is in effect, INLINE is ignored.

If you specify the TEST option, the compiler turns on GONUMBER.

The TEST suboptions BLOCK, LINE, and PATH regulate the points where the compiler inserts program hooks. When you set breakpoints, they are associated with the hooks which are used to instruct Debug Tool where to gain control of your program.

The symbol table suboption SYM regulates the inclusion of symbol tables into the object output of the compiler. Debug Tool uses the symbol tables to obtain information about the variables in the program.

For z/OS XL C compile, you can specify the TEST | NOTEST option on the command line and in the #pragma options preprocessor directive. When you use both methods, the option on the command line takes precedence. For example, if you usually do not want to generate debugging information when you compile a program, you can specify the NOTEST option on a #pragma options preprocessor directive. When you do want to generate debugging information, you can then override the NOTEST option by specifying TEST on the command line rather than editing your source program. Suboptions that you specified in a #pragma options (notest) directive, or with the NOTEST compiler option, are used if TEST is subsequently specified on the command line.

IPA effects

On the IPA compile step, you can specify all of the TEST suboptions that are appropriate for the language of the code that you are compiling. However, they affect processing only if you requested code generation, and only the conventional object file is affected. If you specify the NOOBJECT suboption of IPA, the IPA compile step ignores the TEST option.

The IPA link step supports only the TEST, TEST(HOOK), TEST(NOHOOK), and NOTEST options. If you specify TEST(HOOK) or TEST, the IPA link step generates function call, entry, exit, and return hooks. It does not generate symbol table information. If you specify TEST(NOHOOK), the IPA link step generates limited debug information without any hooks. If you specify any other TEST suboptions for the IPA link step, it turns them off and issues a warning message.

Predefined macros

None.