dbgld - Create a module map for debugging

Format

dbgld [option] ...file

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, you can add the source file contents to the .mdbg file before the source files are relocated. For example, the source files are moved into a different directory or the compilation and debugging are performed on different machines). 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.
-cf
Adds captured source file to the module map, which consists of all files regardless if they contain executable lines of code.
-v
Writes the version information to standard error.
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.

Example

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 is not generated and a warning message is 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