Data sets used by z/OS Debugger

z/OS® Debugger uses the following data sets:

C and C++ source

This data set is used as input to the compiler, and must be kept in a permanent PDS member, sequential file, or HFS or zFS file. The data set must be a single file, not a concatenation of files. z/OS Debugger uses the data set to show you the program as it is executing.

The C and C++ compilers store the name of the source data set inside the load module. z/OS Debugger uses this data set name to access the source.

This data set might not be the original source; for example, the program might have been preprocessed by the CICS® translator. If you use a preprocessor, you must keep the data set input to the compiler in a permanent data set for later use with z/OS Debugger.

As this data set might be read many times by z/OS Debugger, we recommend that you do one of the following:

Define it with the largest block size that your DASD can hold.
Instruct the system to compute the optimum block size, if your system has that capability.

If you manage your source code with a library system that requires you to specify the SUBSYS=ssss parameter when you allocate a data set, you or your site need to specify the EQAOPTS SUBSYS command, which provides the value for ssss. This support is not available when debugging a program under CICS. To learn how to specify EQAOPTS commands, see the topic EQAOPTS commands in the IBM z/OS Debugger Reference and Messages or the IBM z/OS Debugger Customization Guide.

If the following conditions apply to your situation, you do not need access to the source because the .mdbg file has a copy of the source:

You are compiling with z/OS XL C/C++, Version 1.10 or later.
You compile your program with the FORMAT(DWARF) and FILE suboptions of the DEBUG compiler option.
You create an .mdbg file and save (capture) the source with either of the following commands:
- the dbgld command with the -c option
- the CDADBGLD command with the CAPSRC option
You or your site specified YES for the EQAOPTS MDBG command¹, which requires z/OS Debugger to search for the .dbg and source file in a .mdbg file.

COBOL listing

This data set is produced by the compiler and must be kept in a permanent PDS member, sequential file, or an HFS or zFS file. z/OS Debugger uses it to show you the program as it is executing.

The COBOL compiler stores the name of the listing data set inside the load module. z/OS Debugger uses this data set name to access the listing.

z/OS Debugger does not use the output that is created by the COBOL LIST compiler option.

COBOL programs that have been compiled with the SEPARATE suboption do not need to save the listing file. Instead, you must save the separate debug file SYSDEBUG.

For Enterprise COBOL for z/OS Version 5 and Version 6 Release 1, program listings do not need to be saved. The debug data and the source code is saved in a NOLOAD segment in the program object.

For Enterprise COBOL for z/OS Version 6 Release 2 and later, program listings do not need to be saved. The debug data and the source code are saved in a NOLOAD segment of the program object if you specified TEST or TEST(NOSEPARATE,SOURCE), and in a separate debug file if you specified TEST(SEPARATE,SOURCE).

The VS COBOL II compilers do not store the name of the listing data set. z/OS Debugger creates a name in the form userid.cuname.LIST and uses that name to find the listing.

Because this data set might be read many times by z/OS Debugger, we recommend that you do one of the following:

Define it with the largest block size that your DASD can hold.
Instruct the system to compute the optimum blocksize, if your system has that capability.

EQALANGX file

z/OS Debugger uses this data set to obtain debug information about assembler and LangX COBOL source files. It can be a permanent PDS member or sequential file. You must create it before you start z/OS Debugger. You can create it by using the EQALANGX program. Use the SYSADATA output from the High Level assembler or the listing from the IBM® OS/VS COBOL, IBM VS COBOL II, or Enterprise COBOL compiler as input to the EQALANGX program.

PL/I source (Enterprise PL/I only)

This data set is used as input to the compiler, and must be kept in a permanent PDS member, sequential file, or HFS or zFS file. z/OS Debugger uses it to show you the program as it is executing.

The Enterprise PL/I compiler stores the name of the source data set inside the load module. z/OS Debugger uses this data set name to access the source.

This data set might not be the original source; for example, the program might have been preprocessed by the CICS translator. If you use a preprocessor, you must keep the data set input to the compiler in a permanent data set, for later use with z/OS Debugger.

Because this data set might be read many times by z/OS Debugger, we recommend that you do one of the following:

Define it with the largest block size that your DASD can hold.
Instruct the system to compute the optimum block size, if your system has that capability.

PL/I listing (all other versions of PL/I compiler)

This data set is produced by the compiler and must be kept in a permanent file. z/OS Debugger uses it to show you the program as it is executing.

The PL/I compiler does not store the name of the listing data set. z/OS Debugger looks for the listing in a data set with the name in the form of userid.cuname.LIST.

z/OS Debugger does not use the output that is created by the PL/I compiler LIST option; performance improves if you specify NOLIST.

Because this data set might be read many times by z/OS Debugger, we recommend that you do one of the following:

Define it with the largest block size that your DASD can hold.
Instruct the system to compute the optimum block size, if your system has that capability.

Separate debug file

This data set is produced by the compiler and it stores information used by z/OS Debugger. To produce this file, you must compile your program with the following compiler options:

The SEPARATE compiler suboption of the TEST compiler option, which is available on the following compilers:
- Enterprise COBOL for z/OS, Version 6 Release 2 or later. For Enterprise COBOL for z/OS Version 6 Release 2 with APAR PH04485 installed or later, you can specify SEPARATE(DSNAME) to provide the side file location.
- Enterprise COBOL for z/OS, Version 4
- Enterprise COBOL for z/OS and OS/390®, Version 3
- COBOL for OS/390 & VM, Version 2 Release 2
- COBOL for OS/390 & VM, Version 2 Release 1 with APAR PQ40298
- Enterprise PL/I for z/OS, Version 3.5 or later
The compiler uses the SYSDEBUG DD statement to specify the separate debug file.
The FORMAT(DWARF) suboption of the DEBUG compiler option with z/OS C/C++, Version 1.6 or later. The compiler uses one of the following methods to specify the separate debug file (also known as a .dbg file):
- You specify a name with the FILE suboption
- You specify a name with the SYSCDBG DD statement
- If you do not specify a name, the compiler generates a name as described in z/OS XL C/C++ User's Guide.
The file does not contain source. You must also save the source file.

Save the file in any of the following formats:

a permanent PDS member
a sequential file
for COBOL or PL/I, an HFS or zFS file
for C or C++, a z/OS UNIX System Services file

The compiler stores the data set name of the separate debug file inside the load module. z/OS Debugger uses this data set name to access the debug information, unless you provide another data set name as described in How does z/OS Debugger locate source, listing, or separate debug files?.

Because this data set might be read many times by z/OS Debugger, do one of the following steps to improve efficiency:

Define it with the largest block size that your DASD can hold.
Instruct the system to compute the optimum block size, if your system has that capability.

.mdbg file

The .mdbg file is created by the dbgld command or CDADBGLD utility. It contains all the .dbg files for all the programs in a load module or DLL. Beginning with z/OS XL C/C++, Version 1.10, z/OS Debugger can obtain information from this file if it also stores (captures) the source files. Create an .mdbg file with captured source by using the dbgld command with the -c option or the CDADBGLD utility with the CAPSRC option.

To learn how to use these commands, see z/OS XL C/C++ User's Guide.

Preferences file

This data set contains z/OS Debugger commands that customize your session. You can use it, for example, to change the default screen colors set by z/OS Debugger. Store this file in a permanent PDS member or a sequential file.

You can specify a preferences file directly (for example, through the TEST runtime option) or through the EQAOPTS PREFERENCESDSN command. For instructions, see Creating a preferences file.

A CICS region must have read authorization to the preferences file.

The preferences file specifications need to be one of the following options:

RECFM(F) or RECFM(FB) and 32<=LRECL<=256
RECFM(V) or RECFM(VB) and 40<=LRECL<=264

For more information, see Creating a preferences file.

Global preferences file

This is a preferences file generally available to all users. It is specified through the EQAOPTS GPFDSN command. To learn how to specify EQAOPTS commands, see the topic EQAOPTS commands in the IBM z/OS Debugger Reference and Messages or the IBM z/OS Debugger Customization Guide. If a global preferences file exists, z/OS Debugger runs the commands in the global preferences file before commands found in the preferences file.

A CICS region must have read authorization to the global preferences file.

The global preferences file specifications need to be one of the following options:

RECFM(F) or RECFM(FB) and 32<=LRECL<=256
RECFM(V) or RECFM(VB) and 40<=LRECL<=264

For more information, see command GPFDSN in IBM z/OS Debugger Customization Guide.

Commands file

This data set contains z/OS Debugger commands that control the debug session. You can use it, for example, to set breakpoints or set up monitors for common variables. Store it in a permanent PDS member or a sequential file.

If you specify a preferences file, z/OS Debugger runs the commands in the commands file after the commands specified in the preferences file.

You can specify a commands file directly (for example, through the TEST runtime option) or through the EQAOPTS COMMANDSDSN command. If it is specified through the EQAOPTS COMANDSDSN command, it must be in a PDS or PDSE and the member name must match the name of the initial load module in the first enclave. For instructions on creating a commands files, see Creating a commands file.

A CICS region must have read authorization to the commands file.

The commands file specifications need to be one of the following options:

RECFM(F) or RECFM(FB) and 32<=LRECL<=256
RECFM(V) or RECFM(VB) and 40<=LRECL<=264

For more information, see Creating a commands file and Entering multiline commands in a commands file.

EQAOPTS file

This data set contains EQAOPTS commands that control initial settings and options for the debug session. Store it in a permanent PDS member or a sequential file. To learn how to specify EQAOPTS commands, see the topic EQAOPTS commands in the IBM z/OS Debugger Reference and Messages or the IBM z/OS Debugger Customization Guide.

The RECFM must be either F or FB and the LRECL must be 80.

A CICS region must have read authorization to the EQAOPTS file.

EQAUOPTS file

This data set is used to hold parameters for the z/OS Debugger Language Environment® user exit or for the delay debug processing.

The EQAUOPTS data set must be a sequential data set with a RECFM of FB or VB, and an LRECL of 80 to 256.

For more information about this data set, see Specifying the TEST runtime options through the Language Environment user exit and Using delay debug mode to delay starting of a debug session.

Log file

z/OS Debugger uses this file to record the progress of the debugging session. z/OS Debugger stores a copy of the commands you entered along with the results of the execution of commands. The results are stored as comments. This allows you to use the log file as a commands file in subsequent debugging sessions. Store the log file in a permanent PDS member or a sequential file. Because z/OS Debugger writes to this data set, store the log file as a sequential file to relieve any contention for this file.

z/OS Debugger does not use log files in remote debug mode.

The log file specifications need to be one of the following options:

RECFM(F) or RECFM(FB) and 32<=LRECL<=256
RECFM(V) or RECFM(VB) and 40<=LRECL<=264

You can specify a log file directly (for example, the INSPLOG DD or the SET LOG command) or through the EQAOPTS LOGDSN command. For instructions, see Creating the log file.

For Db2® stored procedures, to prevent multiple users from trying to use the same log, do not use the EQAOPTS LOGDSN command.

For CICS, review the special circumstances described in Restrictions when debugging under CICS.

Save settings file (SAVESETS)

z/OS Debugger uses this file to save and restore, between z/OS Debugger sessions, the settings from the SET command. A sequential file with RECFM of VB and LRECL>=3204 must be used.

The default name for this data set is userid.DBGTOOL.SAVESETS. However, you can change this default by using the EQAOPTS SAVESETDSN command. In non-interactive mode (MVS batch mode without using a full-screen terminal), the DD name used to locate this file is INSPSAFE.

You can not save the settings information in the same file that you save breakpoint and monitor specifications information.

Save settings files are not used for remote debug sessions.

Automatic save and restore of the settings is not supported under CICS if the current user is not logged-in or is logged in under the default user ID. If you are running in CICS, the CICS region must have update authorization to the save settings file.

Save settings files are not supported automatically when debugging Db2 stored procedures.

You or your site can direct z/OS Debugger to create this file and enable saving and restoring settings through the EQAOPTS SAVESETDSNALLOC command. For instructions, see Saving and restoring settings, breakpoints, and monitor specifications.

Save breakpoints and monitor specifications file (SAVEBPS)

z/OS Debugger uses this file to save and restore, between z/OS Debugger sessions, the breakpoints, monitor specifications, and LDD specifications. A PDSE or PDS data set with RECFM of VB and LRECL >= 3204 must be used. (We recommend you use a PDSE.)

The default name for this data set is userid.DBGTOOL.SAVEBPS. However, you can change this default by using EQAOPTS SAVEBPDSN command. In non-interactive mode (MVS batch mode without using a full-screen terminal), the DD name used to locate this file is INSPBPM.

You can not save the breakpoint and monitor specifications information in the same file that you save settings information.

Save breakpoints and monitor specifications files are not used for remote debug sessions.

Automatic save and restore of the breakpoints and monitor specifications is not supported under CICS if the current user is not logged-in or is logged in under the default user ID. If you are running in CICS, the CICS region must have update authorization to the save breakpoints and monitor specifications file.

Save breakpoints and monitor specifications files are not supported automatically when debugging Db2 stored procedures.

You or your site can direct z/OS Debugger to create this file and enable saving and restoring breakpoints and monitor specifications through the EQAOPTS SAVEBPDSNALLOC command. For instructions, see Saving and restoring settings, breakpoints, and monitor specifications.

¹ 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.