Choosing DEBUG compiler suboptions for C programs

This topic describes the debugging scenarios available, and how to create a particular debugging scenario by choosing the correct DEBUG compiler suboptions.

The C compiler provides the DEBUG compiler option and its suboptions to control the following actions:

The generation and placement of hooks and symbol tables.
The placement of debug information into the object file or separate debug file.

z/OS® Debugger does not support debugging optimized C programs. Do not use any OPTIMIZE compiler options other than NOOPTIMIZE or OPTIMIZE(0).

The following instructions help you choose the combination of DEBUG compiler suboptions that provide the functionality you need to debug your program:

Choose a debugging scenario, keeping in mind your site's resources, from the following list:
- Scenario A: To get the most z/OS Debugger functionality, a smaller program size, and better performance, use one of the following combinations:
```
DEBUG(FORMAT(DWARF),HOOK(LINE,NOBLOCK,PATH),SYMBOL,FILE(file_location))
```
  The compiler options are the same whether you use only .dbg files or also use .mdbg files.
- Scenario B: To get all z/OS Debugger functionality but have a larger program size and do not want the debug information in a separate file, use the following combination:
```
DEBUG(FORMAT(ISD),HOOK(LINE,NOBLOCK,PATH),SYMBOL)
```
- Scenario C: You can get some z/OS Debugger functionality by compiling with the NODEBUG compiler option. This requires that you debug your program in disassembly mode.
For all scenarios, if you are using other IBM® Application Delivery Foundation for z Systems™ tools, see topic z/OS XL C and C++ programs in IBM Problem Determination Tools for z/OS Common Component: Customization Guide and User Guide to make sure you specify all the compiler options you need to create the files needed by all the IBM Application Delivery Foundation for z Systems tools.
For the scenario you selected, verify that you have the following resources:
- For scenario A, do the following tasks:
  - If you create an .mdbg file, do the following tasks:
    1. Specify YES for the EQAOPTS MDBG command (which requires z/OS Debugger to search for a .dbg file in a .mdbg file)¹.
    2. Verify that the .dbg files are non-temporary files.
    3. Create the .mdbg file with captured source by using the -c option for the dbgld command or the CAPSRC option on the CDADBGLD utility.
    4. Verify that the .mdbg file is a non-temporary file.
  - If you use only .dbg files, verify that the .dbg files are non-temporary files and specify NO for the EQAOPTS MDBG command².
- For scenario C, 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 QUERY DYNDEBUG command.
Verify whether you need to do any of the following tasks:
- You can specify any combination of the C DEBUG suboptions in any order. The default suboptions are BLOCK, LINE, PATH, and SYMBOL.
- 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.
- z/OS Debugger does not support the LP64 compiler option. You must specify or have in effect the ILP32 compiler option.
- If you specify the OPTIMIZE compiler option with a level higher than 0, then no hooks are generated for line, block or path points, and no symbol table is generated. Only hooks for function entry and exit points are generated for optimized programs. The TEST compiler option has the same restriction.
- You cannot call user-defined functions from the command line.

Refer to the following topics for more information related to the material discussed in this topic.

Related references
Description of the DEBUG compiler option in z/OS XL C/C++ User's Guide

¹ In situations where you can specify environment variables, you can set the environment variable EQA_USE_MDBG to YES or NO, which overrides any setting (including the default setting) of the EQAOPTS MDBG command.

² In situations where you can specify environment variables, you can set the environment variable EQA_USE_MDBG to YES or NO, which overrides any setting (including the default setting) of the EQAOPTS MDBG command.