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 statements and symbol tables.
• The placement of debug information into the program object 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:

1. 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.
   • Scenario D: If you are compiling with z/OS C/C++ Version 2.3 or later, use the following combination to get the most z/OS Debugger functionality with no separate file for the debug information:

     DEBUG(FORMAT(DWARF),NOFILE,HOOK(LINE,NOBLOCK,PATH),SYMBOL) GOFF

     The debug data does not increase the size of the loaded program. The size of the program object increases but not the footprint in memory, unless it is required to load the debug data when you are debugging a program. The debug data always matches the executable and is always available, so there is no need to search the lists of data sets.

   For all scenarios, if you are using other Application Delivery Foundation for z/OS tools, see 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 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 use the Dynamic Debug facility to place hooks into programs that reside in read-only storage, verify with your system administrator that you are authorized to do so
     2. After you start z/OS Debugger, verify that you have not deactivated the Dynamic Debug facility by entering the QUERY DYNDEBUG command.
3. 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 SYM.

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

After you have chosen the compiler options and suboptions, see Planning your debug session to determine the next task you must complete.

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