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 the EQAXOPT MDBG,NO option in the EQAOPTS
options file9
- 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 the EQAXOPT MDBG,YES option in the EQAOPTS
options file (which requires Debug Tool to search for .dbg and source
files in a .mdbg file)10
- 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 the
setting of MDBG option in the EQAOPTS options file.11 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 the EQAXOPT MDBG,NO option in the EQAOPTS options file12
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 the EQAXOPT MDBG,YES option in the EQAOPTS options file
(which requires Debug Tool to search for a .dbg file in a .mdbg file)13
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 the EQAXOPT MDBG,NO
option in the EQAOPTS options file14, 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:
- Your site specifies the EQAXOPT MDBG,YES option in the EQAOPTS
options file and, for environments that support environment variables,
you do not set the environment variable EQA_USE_MDBG to NO.
- Your site specifies or defaults to the EQAXOPT MDBG,NO
option in the EQAOPTS options file 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 made up 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 EQAXOPT MDBG option.
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 EQAXOPT MDBG option.
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 EQAXOPT MDBG option.
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 EQAXOPT MDBG option.
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 EQAXOPT MDBG option.
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 EQAXOPT MDBG option.
|
This information center is powered by Eclipse technology. (http://www.eclipse.org)