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 some cases, the debug information is stored in the load module. Debug Tool uses
this information, along with the source or listing file, to display
source code on the screen.
- For COBOL and PL/I CUs compiled with the SEPARATE suboption
of the TEST compiler option, Debug Tool 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, Debug Tool 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 MDBG command10
- For C and C++ CUs created and debugged under the following conditions, Debug Tool 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 MDBG command
(which requires Debug Tool to search for .dbg and source files in a .mdbg
file)11
- For assembler and non-Language Environment COBOL CUs, Debug Tool 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, 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:
- the default data set name
- the SET SOURCE command
- the SET DEFAULT LISTINGS command
- the EQADEBUG DD statement
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:
- Compiled with the FORMAT(DWARF) suboption of the DEBUG compiler
option
- Specified NO for the EQAOPTS MDBG command13
Debug Tool 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
Debug Tool obtains the .dbg file from one of the following sources:
- the default data set name
- the EQADBG DD statement
- the EQAUEDAT user exit (specifying function code 35)
- the EQADBG DD name
- the EQA_DBG_PATH environment variable
- the SET DEFAULT DBG command
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:
- 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 MDBG command
(which requires Debug Tool to search for a .dbg file in a .mdbg file)14
Debug Tool 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 name
- the EQA_MDBG_PATH environment variable
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:
- SET SOURCE command
- 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.
- if present, the EQADEBUG DD statement
- 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:
- SET SOURCE command
- 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.
- 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.
- 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:
- SET SOURCE command
- a previously loaded EQALANGX file that contains a CSECT that matches
the name and length of the program
- 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.
- 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.
- the EQADEBUG DD statement
The SET SOURCE command can be entered during any of
the following situations:
- Any time after the CU name appears as a disassembly CU.
- If the CU is known when the LDD command is entered
but then Debug Tool does not find the EQALANGX file.
- If the CU is not known to Debug Tool when the LDD command
is entered and then Debug Tool runs the LDD after the CU becomes
known to Debug Tool.
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:
- Debug Tool reads the source files for a CU each time it needs to display
the source code. Debug Tool searches for the source file by using the
name the compiler saved in the load module or DLL. If you move the
source files to a different location, Debug Tool searches for the source
file based on the input from the following commands, user exit, or
environment variable, in the following order:
- In full screen mode, the SET SOURCE command.
- In remote debug mode, the EQA_SRC_PATH environment variable or what
you enter in the Change Text File action from
the editor view.
- The EQADEBUG DD name.
- The EQAUEDAT user exit, specifying function code 3. If you specify
the EQADEBUG DD name, the EQAUEDAT user exit is not run.
- The SET DEFAULT LISTINGS command.
- Debug Tool might read the .dbg 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 .dbg file by using the name the compiler saved in the load
module or DLL. If you move the .dbg file to a different location, Debug Tool searches
for the .dbg file based on the input from the following commands,
user exit, or environment variable, in the following order:
- In remote debug mode, the EQA_DBG_PATH environment variable.
- The EQADBG DD name.
- The EQAUEDAT user exit, specifying function code 35. If you specify
the EQADBG DD name, the EQAUEDAT user exit is not run.
- The SET DEFAULT DBG command.
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 do one of the following tasks:
- You or your site specifies YES for the EQAOPTS MDBG command
and, for environments that support environment variables, you do not
set the environment variable EQA_USE_MDBG to NO.
- You or your site specifies or defaults to NO for the
EQAOPTS MDBG command but, for environments that support
environment variables, you override that option by setting the environment
variable EQA_USE_MDBG to YES.
- You compile your programs with z/OS XL
C/C++, Version 1.10 or later
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:
- The EQAUEDAT user exit, specifying function code 37.
- 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:
- The SET MDBG command
- The SET DEFAULT MDBG command
- The EQAMDBG DD name.
- 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.
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.
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.
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.