DEBUG | NODEBUG

Category

Error checking and debugging

Pragma equivalent

None.

Purpose

Defaults

• NODEBUG
• For FORMAT, the default is DWARF.
• 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 debug information as the TEST option. This suboption is available only with ILP32. If this format is used, the FILE suboption is ignored.

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

FILE

Specifies the name of the output file for FORMAT(DWARF). It 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.

If you do not specify a file name, 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 debug 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.

Note: DEBUG(FILE(filename)) is not supported when the METAL compiler option is specified.

LEVEL

Controls the amount of debug 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 DEBUG(LEVEL(9)).

Note: In the z/OS UNIX System Services environment, -g translates to DEBUG(LEVEL(0)), and -g implies NOOPTIMIZE. To debug at an optimization level, you must specify -g with an explicit level.

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

When the DEBUG option is in effect, the compiler generates debug 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.

If you specify OPTIMIZE and DEBUG(FORMAT(ISD)), the behavior is the same as OPTIMIZE and TEST.

If you specify the INLINE and DEBUG(FORMAT(DWARF)) compiler options when OPTIMIZE is in effect, the inline debug 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 debug information is generated to list the variables that occur on each statement of the program source file.

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 debug 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