How does z/OS Debugger locate source, listing, or separate debug files?

z/OS® Debugger obtains information (called debug information) it needs about a compilation unit (CU) by searching through the following sources:

  • In some cases, the debug information is stored in the load module. z/OS Debugger uses this information, along with the source or listing file, to display source code on the screen.
  • For IBM® Enterprise COBOL for z/OS Version 5, Version 6 Release 1, and Version 6 Release 2 or later with the TEST(NOSEPARATE) compiler option programs, z/OS Debugger uses the debug information and the source files that are in a NOLOAD segment in the program object.
  • For COBOL and PL/I CUs compiled with the SEPARATE suboption of the TEST compiler option, z/OS Debugger uses the information stored in a separate file (called a separate debug file) that contains both the debug information and the information needed to display source code on the screen.
  • For C and C++ CUs created and debugged under the following conditions, z/OS Debugger uses the debug information stored in the .dbg file along with the source file to display code on the screen:
    • Compiled with the FORMAT(DWARF) suboption of the DEBUG compiler option
    • Specified or defaulted to NO for the EQAOPTS MDBG1 command
  • For C and C++ CUs created and debugged under the following conditions, z/OS Debugger uses debug information and source code stored in the .mdbg file to display source code on the screen:
    • Compiled with the FORMAT(DWARF) suboption of the DEBUG compiler option
    • Compiled with z/OS XL C/C++, Version 1.10 or later
    • Created an .mdbg file with saved (captured) source for the load module or DLL by using the -c option of the dbgld command or CAPSRC option of the CDADBGLD utility.
    • Specified YES for the EQAOPTS MDBG1 command (which requires z/OS Debugger to search for .dbg and source files in a .mdbg file)
  • For assembler and LangX COBOL CUs, z/OS Debugger uses the information stored in a separate file (called an EQALANGX file) that contains both the debug information and the information needed to display source code on the screen.

In all of these cases, with the exception of Enterprise COBOL for z/OS Version 6 Release 2 or later compiled with TEST(SEPARATE) or TEST(SEPARATE(NODSNAME)), there is a default data set name associated with each CU, load module, or DLL. The way this default name is generated differs depending on the source language and compiler used. To learn how each compiler generates the default name, see the compiler's programming guide or user's guide.

z/OS Debugger obtains the source or listing data, separate debug file data, or EQALANGX data from one of the following sources:

  • the default data set name
  • the SET SOURCE command
  • the SET DEFAULT LISTINGS command
  • the EQADEBUG DD statement
For C and C++ CUs, z/OS Debugger obtains the source data and separate debug file data from different sources, depending on how you created the CU and what value you specified for the EQAOPTS MDBG1 command. For CUs created and debugged under the following conditions, z/OS Debugger obtains the source data from the source file and separate debug file data from the .dbg file:
  • Compiled with the FORMAT(DWARF) suboption of the DEBUG compiler option
  • Specified NO for the EQAOPTS MDBG1 command
z/OS Debugger obtains the source file from one of the following sources:
  • the default data set name
  • the SET SOURCE command
  • the SET DEFAULT LISTINGS command
  • the EQAUEDAT user exit (specifying function code 3)
  • The EQADEBUG DD name
  • the EQA_SRC_PATH environment variable
z/OS Debugger obtains the .dbg file from one of the following sources:
  • the default data set name
  • the SET DEFAULT DBG command
  • the EQAUEDAT user exit (specifying function code 35)
  • the EQADBG DD name
  • the EQA_DBG_PATH environment variable

Note that these lists do show only what can be processed, not the processing order.

For C and C++ CUs created and debugged under the following conditions, z/OS Debugger obtains the source data and separate debug file data from the .mdbg file:
  • Compiled with the FORMAT(DWARF) suboption of the DEBUG compiler option
  • Compiled with z/OS XL C/C++, Version 1.10 or later
  • Created an .mdbg file with saved (captured) source for the load module or DLL by using the -c option of the dbgld command or CAPSRC option of the CDADBGLD utility.
  • Specified YES for the EQAOPTS MDBG1 command (which requires z/OS Debugger to search for a .dbg file in a .mdbg file)
z/OS Debugger obtains the .mdbg file from one of the following sources:
  • the default data set name
  • the SET MDBG command
  • the SET DEFAULT MDBG command
  • the EQAUEDAT user exit (specifying function code 37)
  • the EQAMDBG DD statement
  • the EQA_MDBG_PATH environment variable

For each type of file (source, listing, separate debug file, .dbg, or .mdbg), z/OS Debugger searches through the sources in different order. The rest of the topics in this chapter describe the order.

If you are using the EQAUEDAT user exit in your environment, the name provided in the user exit takes precedence if z/OS Debugger finds that file.

For .dbg and .mdbg files, z/OS Debugger does not search for the source until it finds a valid .dbg or .mdbg file.

Notes:
  1. 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.