DEBUG | NODEBUG

Category

Error checking and debugging

Pragma equivalent

None.

Purpose

Instructs the compiler to generate debugging information.

Defaults

• NODEBUG
• For FORMAT, the default is DWARF.
• For FILE, the default is FILE.
• For LEVEL, the default is LEVEL(0).
• For HOOK, the defaults are HOOK(ALL) for NOOPTIMIZE and HOOK(NONE,PROFILE) for OPTIMIZE.
• For SYMBOL, the default is SYMBOL.

Parameters

FORMAT

Has the following suboptions: ISD and DWARF. ISD produces the same debugging information as the TEST option. This suboption is available only with ILP32. If this format is used, both the FILE and the NOFILE suboptions are ignored.

The DWARF suboption produces debugging information in the DWARF Version 4 debugging information format, stored in the file specified by the FILE suboption, or in GOFF NOLOAD classes when the NOFILE suboption is specified. This is the only format supported when LP64 or METAL is specified.

FILE | NOFILE

Controls whether the DWARF debugging information is stored in a separate debug file.

The FILE suboption specifies the name of the output file for FORMAT(DWARF). The output file can be a sequential data set, a partitioned data set, a partitioned data set (member), a z/OS UNIX file, or a z/OS UNIX System Services directory.

When specified with the GOFF and DEBUG(FORMAT(DWARF)) options, the NOFILE suboption instructs the compiler to place the debugging information in the GOFF NOLOAD classes in the object file instead of a separate debug side file. The binder then merges the debugging information from different object files into the NOLOAD classes in the executable or library at binding time. The debugging information in the NOLOAD classes will be loaded only when it is explicitly required by the debugger.

If you do not specify a file name with the FILE suboption, the compiler uses the SYSCDBG DD statement, or its alternative, if you allocated it. Otherwise, the compiler constructs a file name as follows:

• If you are compiling a data set, the compiler uses the source file name to form the name of the output data set. The high-level qualifier is replaced with the userid under which the compiler is running, and .DBG is appended as the low-level qualifier.
• If you are compiling a z/OS® UNIX file, the compiler stores the debugging information in a file that has the name of the source file with a .dbg extension.

For example, if TSYOU19 is compiling TSPERF.EON.SOURCE(EON) with the DEBUG option and does not specify a file name, the default output file name will be TSYOU19.EON.SOURCE.DBG(EON).

For a PDS or z/OS UNIX file system directory compile, the FILE option specifies the PDS or z/OS UNIX file system directory where the output files are generated.

The default for c89 is FILE(./filename.dbg).

The compiler resolves the full path name for this file name, and places it in the generated object file. This information can be used by program analysis tools to locate the output file for FORMAT(DWARF). You can examine this generated file name in the compiler listing file (see LIST | NOLIST for instructions on how to create a compiler listing file), as shown in the following example:

                 PPA4: Compile Unit Debug Block
 000140  0000001A                =F'26'        DWARF File Name
 000144  ****                    C'/hfs/fullpath/filename.dbg'

If the compiler cannot resolve the full path name for the file name (for example, because the search permission was denied for a component of the file name), the compiler will issue a warning message, and the relative file name will be used instead.

Notes:

• DEBUG(FILE(filename)) and DEBUG(NOFILE) are not supported when the METAL compiler option is specified.

LEVEL

Controls the amount of debugging information produced. Different levels can balance between debug capability and compiler optimization. Higher levels provide more complete debug support, at the cost of runtime or possible compile-time performance. Lower levels provide higher runtime performance, at the cost of some capability in the debugging session. The LEVEL suboption has the following values:

0

• If the OPTIMIZE compiler option is specified, DEBUG(LEVEL(0)) is equivalent to DEBUG(LEVEL(2)).
• If the NOOPTIMIZE compiler option is specified, DEBUG(LEVEL(0)) is equivalent to NODEBUG.

Note: In the z/OS UNIX System Services environment, -g forces NOOPTIMIZE and translates to DEBUG(LEVEL(0)).-g0 implies NODEBUG. To debug at an optimization level, you must specify -g with an explicit level. Unlike -g, -g# does not force NOOPTIMIZE and is equivalent to DEBUG(LEVEL(#)), where the number sign # represents a positive integer whose value is 1 to 9 inclusive.

1

Generates minimal read-only debugging information about line numbers and source file names. No program state is preserved.

Note: Specifying DEBUG(LEVEL(1)) is equivalent to specifying NODEBUG with GONUMBER. If DEBUG(LEVEL(1)) and NOGONUMBER are specified, a warning message is issued, and the options are set to NODEBUG and NOGONUMBER.

2

Generates read-only debugging information about line numbers, source file names, and symbols. When OPTIMIZE(2) or higher level is specified, no program state is preserved.

3, 4

Generates read-only debugging information about line numbers, source file names, and symbols.

When OPTIMIZE(2) or higher level is specified:

• No program state is preserved.
• Function parameter values are available to the debugger at the beginning of each function.

Note: DEBUG(LEVEL(3)) implies STOREARGS if the linkage mode is XPLINK.

5, 6, 7

Generates read-only debugging information about line numbers, source file names, and symbols.

When OPTIMIZE(2) or higher level is specified:

• Program state is available to the debugger at if constructs, loop constructs, procedure calls, and function calls.
• Function parameter values are available to the debugger at the beginning of each function.

8

Generates read-only debugging information about line numbers, source file names, and symbols.

When OPTIMIZE(2) or higher level is specified:

• Program state is available to the debugger at the beginning of every executable statement.
• Function parameter values are available to the debugger at the beginning of each function.

9

Generates debugging information about line numbers, source file names, and symbols. Modifying the value of a variable in the debugger is allowed and respected.

When OPTIMIZE(2) or higher level is specified:

• Program state is available to the debugger at the beginning of every executable statement.
• Function parameter values are available to the debugger at the beginning of each function.

Notes: In the z/OS UNIX System Services environment:

1. When no optimization is enabled, the debugging information is always available if you specify -g2 or a higher level.
2. When the -O2 optimization level is in effect, the debugging information is available at selected source locations if you specify -g5 or a higher level.
3. When you specify -g5, -g6, or -g7 with -O2, the debugging information is available for the following language constructs:

   if constructs

   The debugging information is available at the beginning of every if statement. It is also available at the beginning of the next executable statement right after the if statement.

   Loop constructs

   The debugging information is available at the beginning of every do, for, or while statement. It is also available at the beginning of the next executable statement right after the do, for, or while statement.

   Function definitions

   The debugging information is available at the first executable statement in the body of the function.

   Function calls

   The debugging information is available at the beginning of every statement where a user-defined function is called. It is also available at the beginning of the next executable statement right after the statement that contains the function call.

4. When you specify -g8 or -g9 with -O2, the debugging information is available at every executable statement.

HOOK

Notes:

1. A METAL compilation does not generate hook instructions, therefore DEBUG(HOOK) is not supported when the METAL compiler option is specified.
2. If the OPTIMIZE compiler option is specified, the only valid suboptions for HOOK are CALL and FUNC. If other suboptions are specified, they will be ignored.

Controls the generation of LINE, BLOCK, PATH, CALL, and FUNC hook instructions. Hook instructions appear in the compiler Pseudo Assembly listing in the following form:

EX r0,HOOK..[type of hook] 

The type of hook that each hook suboption controls is summarized in the list below:

• LINE
  • STMT - General statement
• BLOCK
  • BLOCK-ENTRY - Beginning of block
  • BLOCK-EXIT - End of block
  • MULTIEXIT - End of block and procedure
• PATH
  • LABEL - A label
  • DOBGN - Start of a loop
  • TRUEIF - True block for an if statement
  • FALSEIF - False block for an if statement
  • WHENBGN - Case block
  • OTHERW - Default case block
  • GOTO - Goto statement
  • POSTCOMPOUND - End of a PATH block
• CALL
  • CALLBGN - Start of a call sequence
  • CALLRET - End of a call sequence
• FUNC
  • PGM-ENTRY - Start of a function
  • PGM-EXIT - End of a function

There is also a set of shortcuts for specifying a group of hooks:

NONE

It is the same as specifying NOLINE, NOBLOCK, NOPATH, NOCALL, and NOFUNC. It instructs the compiler to suppress all hook instructions.

ALL

It is the same as specifying LINE, BLOCK, PATH, CALL, and FUNC. It instructs the compiler to generate all hook instructions. This is the ideal setting for debugging purposes.

PROFILE

It is the same as specifying CALL and FUNC. It is the ideal setting for tracing the program with the Performance Analyzer.

SYMBOL

This option provides you with access to variable and other symbol information. For optimized code, the results are not always well-defined for every variable because the compiler might have optimized away their use.

Note: The default of this suboption is DEBUG(SYMBOL), but when the HOT or IPA option is used with DEBUG, DEBUG(NOSYMBOL) is forced.

Usage

As of z/OS V1R11 XL C/C++ compiler, the DEBUG option has superseded the TEST option. If you specify both TEST and DEBUG options in the same compilation unit, the compiler uses the last specified option. IBM recommends the DEBUG option.

When the DEBUG option is in effect, the compiler generates debugging information based on the DWARF Version 4 debugging information format, which has been developed by the UNIX International Programming Languages Special Interest Group (SIG), and is an industry standard format.

Starting with z/OS V1R5, the compiler supports two debug formats, ISD and DWARF. ISD is the only debug format that works with the Performance Analyzer.

If you specify the INLINE and DEBUG(FORMAT(DWARF)) compiler options when OPTIMIZE is in effect, the inline debugging information is generated for inline procedures as well as parameters and local variables of inline procedures.

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

When OPT(2) or OPT(3) is used with DEBUG, the DEBUG(SYMBOL) suboption is enabled by default.

You can specify the DEBUG option and TARGET to a release prior to z/OS V1R5. However, if the debug format is DWARF, you must debug using dbx on a z/OS V1R5 (and above) system.

In the z/OS UNIX System Services environment, -g forces DEBUG(FORMAT(DWARF)), NOHOT, NOOPTIMIZE, and GONUMBER.

If you specify DEBUG(FORMAT(DWARF)), automonitor debugging information is generated to list the variables that occur on each statement of the program source file.

The usage status of this option is inserted in the object file to aid you in diagnosing a problem with your program.

IPA effects

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

The IPA link step only supports generation of profiling hooks and no other debugging information. To generate profiling hooks, the IPA link step only requires the TEST(HOOK) or the DEBUG(FORMAT(ISD),HOOK) option.

If only IPA object is produced at the IPA compile step, the TEST and DEBUG options are accepted and ignored. If a regular object is also produced, the compiler behavior is the same as when the TEST or DEBUG option is specified with the OPITMIZE option and applies to the regular object only.

Predefined macros

None.

Examples

cc -Wc,"NODEBUG(FORMAT(DWARF),HOOK(ALL))" -Wc,"DEBUG(NOSYMBOL)" hello.c
cc -WC,"DEBUG(FORMAT(DWARF),HOOK(ALL),NOSYMBOL)" hello.c