Using delay debug mode to delay starting of a debug session

By default, z/OS® Debugger starts a debug session at the first entry compile unit of the initial load module of an application. However, there are cases where the problem is in some compile unit (for example, prog1) inside the application that needs debugging.

Currently, you enter AT ENTRY prog1 and GO commands when the debug session starts.

However, in some complex applications, it can take some significant time before prog1 appears. In this case, you can use delay debug mode to delay the starting of the debug session until z/OS Debugger recognizes prog1.

z/OS Debugger is in the dormant state during the delay debug mode and monitors only a few events. When z/OS Debugger recognizes prog1, z/OS Debugger comes out of delay debug mode, completes the initialization, and starts the debug session.

Delay debug mode uses a delay debug profile data set that contains the program list and TEST runtime option. This profile is used by z/OS Debugger to match the program name or C function name (compile unit) (and optionally a load module name) with the names in the program list. If there is a match, z/OS Debugger comes out of the delay debug mode and uses the TEST runtime to complete the initialization. This data set is a physical sequential data set that is created and edited by using one of the following ways:
  • Option B of the IBM® z/OS Debugger Utilities: Delay Debug Profile
  • The z/OS Debugger Profiles view in a remote IDE.
  • Any application that uses the Debug Profile Service API for profile management.
You can enable delay debug mode by using one of the following ways:
  • Using the EQAOPTS DLAYDBG command
  • Specifying a simple TEST runtime option for Language Environment programs1.

By default, delay debug mode is NO. When delay debug mode is enabled, you can specify these additional commands:
DLAYDBGCND

You can use this command to indicate whether you want z/OS Debugger to monitor condition events in the delay debug mode.

The default is DLAYDBGCND,ALL.

DLAYDBGDSN
Delay debug profile data set naming pattern.

The default is userid.DLAYDBG.EQAUOPTS.

This command is ignored if delay debug mode is turned on using a simple TEST runtime option. In that case, the delay debug profile data set naming pattern is set with a parameter to the Debug Profile Service API.

DLAYDBGTRC
Delay debug pattern match trace message level.

This message level is used to generate error and informational messages for debugging purposes.

The default is 0, which indicates no trace messages.

DLAYDBGXRF

You can use this command to indicate that you want z/OS Debugger to use the cross-reference file or the Terminal Interface Manager repository to find the user ID when it constructs the delay debug profile data set name.

This command can be used in the IMS environment when an IMS transaction is started with a generic ID. With the RESPOSITORY option, the command can also be used in the Db2 stored procedures environment when a stored procedure runs under a generic ID.

See Debugging tasks running under a generic user ID by using Terminal Interface Manager for a description of the steps required to use the REPOSITORY option of DLAYDBGXRF.

Once z/OS Debugger completes the initialization, the delay debug mode cannot be reactivated.

Usage notes

  • The delay debug mode applies to non-CICS environments only.
  • The delay debug mode applies to programs compiled with the Enterprise COBOL for z/OS and Enterprise PL/I for z/OS compilers, C functions compiled with the z/OS V2.1 XL C/C++ compiler and non-Language Environment programs. Non-Language Environment compile units must be the initial program in a task or the target of a LINK or LINKX macro to be eligible for delay debug pattern matching.

    For compile time and runtime requirements of C functions, see Delay debug mode for C requires the FUNCEVENT(ENTRYCALL) compiler suboption.

  • The main program of the application must be a Language Environment® program, or a non-Language Environment program that is started by using EQANMDBG.
  • The TEST runtime option used to start z/OS Debugger at the beginning of the application must have PROMPT in the third suboption, for example, TEST(ALL,*,PROMPT,*).
  • If the user exit method is used to start z/OS Debugger at the beginning of the application, the user exit data set should have a '*' as one of the names in the program name list so that the pattern matching always succeeds and the TEST runtime option is returned to Language Environment.

    In addition, the name of the user exit data set must be different from the name of the delay debug profile data set.

  • Use Delay Debug Profile to set up the delay debug profile data set. You can find this tool under option B in IBM z/OS Debugger Utilities.
  • To interoperate between 31-bit and 64-bit COBOL programs or between 31-bit and 64-bit PL/I programs, specify load module and compile unit pairs for both 31-bit and 64-bit programs in the debug profile.
  • To interoperate between 31-bit COBOL and 64-bit Java programs, specify load module and compile unit pairs for 31-bit COBOL programs in the debug profile. For more information, see Compiling, linking, and running non-OO COBOL applications that interoperate with Java.
  • To interoperate between 31-bit PL/I and 64-bit Java programs, use 64-bit PL/I programs in between.
1 The simple TEST option turns on delay debug if the application environment is not a foreground TSO application, and TEST suboptions are not supplied using #pragma runopts or PLIXOPT.