Description
The compiler
creates a .dbg file for each compilation unit if
the DEBUG compiler option is specified. The path names of all of the .dbg files
are then stored in the module, which is an executable file or a DLL.
The dbgld command opens all of the .dbg files
associated with the module and stores all of the functions, global
variables, external types, and source files in a single module map
file with a .mdbg extension. In addition, the contents
of all of the .dbg files are packaged together into
this same .mdbg file. The dbgld command
only needs to be executed once after binding.
Debuggers that
support demand load can use the .mdbg file for faster
access to debug information. For more information on using the module
map to improve debugger performance, see z/OS Common Debug Architecture User's Guide.
If
the original source files are not available at debugging time (for
example, the source files are moved into a different directory or
the compilation and debugging are performed on different machines),
you can add the source file contents to the .mdbg file
before the source files are relocated. When invoking the dbgld command,
you can specify the -c option because the source
file contents cannot be captured into the .mdbg file
by the dbgld command by default. A debugger that
supports captured source can then retrieve the source file contents
from the .mdbg file.
Options
option - -c
- Adds captured source file to the module map, which consists of
all files that contain executable lines of code.
- -v
- Writes the version information to stderr.
- file
- Is the module name, which can be:
- The absolute path name of a z/OS® UNIX file
- The relative path name of a z/OS UNIX file
- A fully qualified MVS™ data
set (PDS member)
The output of the
dbgld command
is a file with the name of the module followed by a
.mdbg extension.
The file will always be written in the current directory. For example,
if the module name is
/mypath/mymodule, a file called
mymodule.mdbg will
be created in the current directory. If the file already exists, it
will be overwritten.
Restrictions
The following
restrictions apply to the use of
dbgld:
- The source files must be compiled with the DEBUG compiler option.
- The name of a valid module must be passed into the dbgld utility.
The module must be bound with the EDIT=YES binder option, which is
the default. An error message will be generated if EDIT=NO.
- The .dbg files associated with the module must
exist in the directories where they were during compilation. Otherwise,
they will not be added to the module map and no debug information
will be available to the compilation units via the module map during
debugging. An error message will be generated for each .dbg file
that is not found.
- Because the dbgld command always creates the .mdbg file
in the current directory, the command must be run from a directory
that has write permission.
- Source files compiled with NOGOFF and NOLONGNAME are not processed
by the utility. If the entire module is made up of these compilation
units, an error message will be generated to indicate that no debug
information was found. Compile your application with LONGNAME or GOFF
to mitigate this restriction.
Eample
The following example
shows how to compile
hello1.c and
hello2.c and
create a module map in a file called
hello.mdbg.
xlc -g hello1.c hello2.c -o hello
dbgld hello
The following example shows how to compile
hello1.c and
hello2.c and
create a module map in a file called
hello.mdbg which
contains captured source.
xlc -g hello1.c hello2.c -o hello
dbgld -c hello
The following example shows how to
display the version information for the dbgld utility and the Common
Debug Architecture run times when creating the module map.
dbgld -v hello
The
output is:
CDA0000I Utility(dbgld ) Level(level name)
CDA0000I Library(elf ) Level(level name)
CDA0000I Library(dwarf ) Level(level name)
CDA0000I Library(ddpi ) Level(level name)
If the
-g option
is missing during compilation,
hello.mdbg will not
be generated and a warning message will be printed, as shown in the
following example:
xlc hello1.c hello2.c -o hello
dbgld hello
The output is a warning message stating that
no debug information was found in
hello.
Exit values
The exit
values for
dblgd are:
- 0
- Successful completion
- 4
- Warning
- 8
- Error
- 12
- Severe error