Appendix B. How does Debug Tool locate source, listing, or separate debug files?

Debug Tool obtains information (called debug information) it needs about a compilation unit (CU) by searching through the following sources:

In all of these cases, 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.

Debug Tool obtains the source or listing data, separate debug file data, or EQALANGX data from one of the following sources:

For C and C++ CUs, Debug Tool 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 MDBG command.12 For CUs created and debugged under the following conditions, Debug Tool obtains the source data from the source file and separate debug file data from the .dbg file:

Debug Tool obtains the source file from one of the following sources:

Debug Tool obtains the .dbg file from one of the following sources:

For C and C++ CUs created and debugged under the following conditions, Debug Tool obtains the source data and separate debug file data from the .mdbg file:

Debug Tool obtains the .mdbg file from one of the following sources:

For each type of file (source, listing, separate debug file, .dbg, or .mdbg), Debug Tool 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 Debug Tool finds that file.

For .dbg and .mdbg files, Debug Tool does not search for the source until it finds a valid .dbg or .mdbg file.

How does Debug Tool locate source and listing files?

Debug Tool reads the source or listing file for a CU each time it needs to display information about that CU. While you are debugging your CU, the data set from which the file is read can change. Each time Debug Tool needs to read a source or listing file, it searches for the data set in the following order:

  1. SET SOURCE command
  2. SET DEFAULT LISTINGS command. If the EQAUEDAT user exit is implemented and a EQADEBUG DD statement is not specified, the data set name might be modified by the EQAUEDAT user exit.
  3. if present, the EQADEBUG DD statement
  4. default data set name. If the EQAUEDAT user exit is implemented and a EQADEBUG DD statement is not specified, the data set name might be modified by the EQAUEDAT user exit.

How does Debug Tool locate COBOL and PL/I separate debug file files?

Debug Tool might read from a COBOL or PL/I separate debug file more than once but it always reads the separate debug file from the same data set. After Debug Tool locates a valid separate debug file, you cannot direct Debug Tool to a different separate debug file. When the CU first appears, Debug Tool looks for the separate debug file in the following order:

  1. SET SOURCE command
  2. default data set name. If the EQAUEDAT user exit is implemented and a EQADEBUG DD statement is not specified, the data set name might be modified by the EQAUEDAT user exit.
  3. SET DEFAULT LISTINGS command. If the EQAUEDAT user exit is implemented and a EQADEBUG DD statement is not specified, the data set name might be modified by the EQAUEDAT user exit.
  4. if present, the EQADEBUG DD statement

The SET SOURCE command can be entered only after the CU name appears as a CU and the separate debug file is not found in any of the other locations. The SET DEFAULT LISTINGS command can be entered at any time before the CU name appears as a CU or, if the separate debug file is not found in any of the other possible locations, it can be entered later.

How does Debug Tool locate EQALANGX files

An EQALANGX file, which contains debug information for an assembler or non-Language Environment COBOL program, might be read more than once but it is always read from the same data set. After Debug Tool locates a valid EQALANGX file, you cannot direct Debug Tool to a different EQALANGX file. After you enter the LOADDEBUGDATA (LDD) command (which is run immediately or run when the specified CU becomes known to Debug Tool), Debug Tool looks for the EQALANGX file in the following order:

  1. SET SOURCE command
  2. a previously loaded EQALANGX file that contains a CSECT that matches the name and length of the program
  3. default data set name. If the EQAUEDAT user exit is implemented and a EQADEBUG DD statement is not specified, the data set name might be modified by the EQAUEDAT user exit.
  4. SET DEFAULT LISTINGS command. If the EQAUEDAT user exit is implemented and a EQADEBUG DD statement is not specified, the data set name might be modified by the EQAUEDAT user exit.
  5. the EQADEBUG DD statement

The SET SOURCE command can be entered during any of the following situations:

The SET DEFAULT LISTINGS command can be entered any time before you enter the LDD command or, if the EQALANGX file is not found by the LDD command, after you enter the LDD command.

How does Debug Tool locate the C/C++ source file and the .dbg file?

If you compile with the FORMAT(DWARF) and FILE suboptions of the DEBUG compiler option and specify NO for the EQAOPTS MDBG command15, Debug Tool needs the source file and the .dbg file. The following list describes how Debug Tool searches for those files:

To learn more about the DEBUG compiler option, the dbgld command, and the CDADBGLD utility, see z/OS XL C/C++ User’s Guide.

How does Debug Tool locate the C/C++ .mdbg file?

For the following conditions, Debug Tool can obtain debug information and source from a module map (.mdbg) file:

You use the dbgld command with the -c option or the CDADBGLD utility with the CAPSRC option to save (capture) the source files, as well as all the .dbg files, belonging to the programs that make up a single load module or DLL into one module map file (.mdbg file).

Create an .mdbg file with captured source for any load module or DLL that you want to debug because the .mdbg file makes it easier for you to debug the load module or DLL. For example, if your load module is consists of 10 programs and you do not create a module map file, you would need to keep track of 10 .dbg files and 10 source files. If you create a module map file for that load module, you would need to keep track of just one .mdbg file.

Debug Tool might read the .mdbg file more than once, but it always reads this file from the same data set. After Debug Tool locates this file and validates its contents with the load module being debugged, you cannot redirect Debug Tool to search a different file. Debug Tool searches for the .mdbg file based on the input from the following commands, user exit, or environment variable, in the following order:

  1. The EQAUEDAT user exit, specifying function code 37.
  2. If you do not write the EQAUEDAT user exit or the user exit cannot find the file, the default data set name, which is userid.mdbg(load_module_or_DLL_name), or, in UNIX System Services, ./load_module_or_DLL_name.mdbg.
If Debug Tool cannot find the .mdbg file, then it searches for the .mdbg file based on the input from the following commands, DD statement, or environment variable, in the following order:
  1. The SET MDBG command
  2. The SET DEFAULT MDBG command
  3. The EQAMDBG DD name.
  4. The EQA_MDBG_PATH environment variable.

To learn more about the DEBUG compiler option, the dbgld command, and the CDADBGLD utility, see z/OS XL C/C++ User’s Guide.


10.
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.
11.
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.
12.
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.
13.
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.
14.
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.
15.
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.