Appendix A. Data sets used by Debug Tool

Debug Tool 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 file. The data set must be a single file, not a concatenation of files. Debug Tool 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. Debug Tool 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 Debug Tool.

As this data set might be read many times by Debug Tool, we recommend that you do one of the following:

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 Debug Tool Reference and Messages or the Debug Tool 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:

COBOL listing
This data set is produced by the compiler and must be kept in a permanent PDS member, sequential file, or HFS file. Debug Tool 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. Debug Tool uses this data set name to access the listing.

Debug Tool 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.

The VS COBOL II compilers do not store the name of the listing data set. Debug Tool 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 Debug Tool, we recommend that you do one of the following:

EQALANGX file
Debug Tool uses this data set to obtain debug information about assembler and non-Language Environment COBOL source files. It can be a permanent PDS member or sequential file. You must create it before you start Debug Tool. 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 or IBM VS COBOL II 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 file. Debug Tool 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. Debug Tool 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 Debug Tool.

Because this data set might be read many times by Debug Tool, we recommend that you do one of the following:

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 Debug Tool Reference and Messages or the Debug Tool Customization Guide.

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. Debug Tool 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. Debug Tool looks for the listing in a data set with the name in the form of userid.cuname.LIST.

Debug Tool 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 Debug Tool, we recommend that you do one of the following:

Separate debug file
This data set is produced by the compiler and it stores information used by Debug Tool. To produce this file, you must compile your program with the following compiler options:

Save the file in any of the following formats:

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

Because this data set might be read many times by Debug Tool, do one of the following steps to improve efficiency:

.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, Debug Tool 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 Debug Tool commands that customize your session. You can use it, for example, to change the default screen colors set by Debug Tool. 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.

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 Debug Tool Reference and Messages or the Debug Tool Customization Guide. If a global preferences file exists, Debug Tool 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.

Commands file

This data set contains Debug Tool 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, Debug Tool 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.

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 Debug Tool Reference and Messages or the Debug Tool Customization Guide.

The record format must be either F or FB and the logical record length must be 80.

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

Log file

Debug Tool uses this file to record the progress of the debugging session. Debug Tool 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 Debug Tool writes to this data set, store the log file as a sequential file to relieve any contention for this file.

Debug Tool does not use log files in remote debug mode.

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

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)
Debug Tool uses this file to save and restore, between Debug Tool 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 dedicated 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 Debug Tool 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)
Debug Tool uses this file to save and restore, between Debug Tool 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 dedicated 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 Debug Tool 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.


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