Updated: 11 December 1998

OpenVMS Debugger Manual

Exit handlers are procedures that are called whenever an image requests the $EXIT system service or runs to completion. A user program can declare one or more exit handlers. The debugger always declares its own exit handler.

At program termination, the debugger exit handler executes after all application-declared exit handlers have executed.

To debug an application-declared exit handler:

1. Set a breakpoint in that exit handler.
2. Cause the exit handler to execute by using one of the following techniques:
   • Include in your program an instruction that invokes the exit handler (usually a call to $EXIT).
   • Allow your program to terminate.
   • Enter the EXIT command. (Note that the QUIT command does not execute any user-declared exit handlers.)
   
   When the exit handler executes, the breakpoint is activated and control is then returned to the debugger, which prompts for commands.

The SHOW EXIT_HANDLERS command gives a display of the exit handlers that your program has declared. The exit handler routines are displayed in the order that they are called. A routine name is displayed symbolically, if possible. Otherwise, its address is displayed. The debugger's exit handlers are not displayed. For example:

DBG> SHOW EXIT_HANDLERS exit handler at STACKS\CLEANUP exit handler at BLIHANDLER\HANDLER1 DBG>

14.7 Debugging AST-Driven Programs

A program can use asynchronous system traps (ASTs) either explicitly or implicitly by calling system services or Run-Time Library (RTL) routines that call application-defined AST routines. Section 14.7.1 explains how to facilitate debugging by disabling and enabling the delivery of ASTs originating with your program.

14.7.1 Disabling and Enabling the Delivery of ASTs

Debugging AST-driven programs can be confusing because interrupts originating from the program being debugged can occur, but are not processed, while the debugger is running (processing commands, tracing execution, displaying information, and so on).

By default, the delivery of ASTs is enabled while the program is running. The DISABLE AST command disables the delivery of ASTs while the program is running and causes any such potential interrupts to be queued.

The delivery of ASTs is always disabled when the debugger is running.

If a static watchpoint is in effect, the debugger deactivates the static watchpoint, ASTs, and thread switching, just before a system service call. The debugger reactivates them just after the system service call completes. (For more information, see the SET WATCH command description.)

The ENABLE AST command reenables the delivery of ASTs, including any pending ASTs. The SHOW AST command indicates whether the delivery of ASTs is enabled or disabled.

To control the delivery of ASTs during the execution of a routine called with the CALL command, use the /[NO]AST qualifiers. The command CALL/AST enables the delivery of ASTs in the called routine. The command CALL/NOAST disables the delivery of ASTs in the called routine. If you do not specify /AST or /NOAST with the CALL command, the delivery of ASTs is enabled unless you have previously entered the DISABLE AST command.

14.8 Debugging Translated Images (Alpha Only)

On OpenVMS Alpha systems, the debugger does not support attempts to debug translated images. If you must debug a translated image, use the Delta/XDelta Debugger. For more information on this debugger, see the OpenVMS Delta/XDelta Debugger Manual.

14.9 Debugging Programs That Perform Synchronization or Communication Functions

Some programs that perform synchronization or communication can pose problems for debugging. In the following cases, a user application remains in HIB (hibernate) state:

• A program running under the two-process or multiprocess debugger issues a $WAKE call followed by a $HIBER call
• You issue a STEP command inside (or otherwise interrupt) a Run-Time Library (RTL) or system service routine that makes use of $WAKE or $HIBER (for example, LIB$WAIT or $SCHDWK)
• An application being debugged includes the LCK$M_DEQALL modifier in a $DEQ system service call (this modifier breaks communication links between the portion of the debugger in the user process (the kernel) and the debugger main process)

To work around this problem, debug these application programs using the limited one-process mode, rather than the default or the multiprocess mode. To set up one-process mode, issue the following command:

$ DEFINE DBG$PROCESS NONE

14.10 Debugging Inlined Routines

On OpenVMS systems, the debugger does not support attempts to debug inlined routines. If you attempt to debug an inlined routine, the debugger issues a message that it cannot access the routine, as shown in the following example:

%DEBUG-E-ACCESSR, no read access to address 00000000

To work around this problem, compile your program with the /NOOPTIMIZE qualifier.

This chapter describes features of the debugger that are specific to multiprocess programs (programs that run in more than one process). These features enable you to display process information and control the execution of specific processes. You can use these features in addition to those explained in other chapters.

The first section describes the two multiprocess models for multiprocess programs. Remaining sections detail the basic multiprocessing techniques, multiprocessing commands, and supplemental information.

Images discussed in this chapter are debuggable images---that is, images that can be brought under control of the debugger. A debuggable image is one that was not linked with the /NOTRACEBACK qualifier. As explained in Section 1.2, you have full symbolic information when debugging an image only if its modules were compiled and linked with the /DEBUG qualifier.

On OpenVMS Alpha systems, the debugger does not support attempts to debug translated images. If you must debug a translated image, use the Delta/XDelta Debugger. For more information on this debugger, see the OpenVMS Delta/XDelta Debugger Manual.

15.1 Multiprocessing Models

Multiprocessing programs conform to one of the following multiprocessing models:

• The hierarchical model
  The multiprocessing program spawns processes to handle programming tasks and initiates connections to each process.
• The client/server model
  The user, or client, initiates connection to the server, which processes client requests. The server spawns threads to handle programming tasks.

Debugger multiprocessing features and commands support both multiprocessing models, but process relationships may differ depending on your invocation of the debugger.

15.2 Basic Multiprocess Debugging Techniques

This section gives an overview of the multiprocess debugging environment and explains the basic techniques used to debug a multiprocess program. Refer to subsequent sections for additional details.

This section explains the usual way of starting a multiprocess debugging session. See Section 15.3.4 for additional techniques for starting the debugger by interrupting the execution of an image and bringing the image under debugger control (for example, using the Ctrl/Y--DEBUG sequence or the CONNECT command).

To start a multiprocess debugging session, follow these steps:

1. Be sure that all processes assume the same debugger configuration, and that the debugger configuration is MULTIPROCESS. You can establish a multiprocess debugging configuration by entering the following logical-name definition:

   $ DEFINE/GROUP DBG$PROCESS MULTIPROCESS

   
   This command establishes a multiprocess configuration for the user identification code (UIC) group in which the process originates. As a result, any debuggable image associated with the same UIC group can be controlled from that one session.
   Note that all processes must be using the same version of the debugger. If you control debugger image startup with logical names, you must ensure that all processes see the same logical name definitions.

2. Start the kept debugger:

   $ DEBUG/KEEP Debugger Banner and Version Number DBG> RUN prog-name Language: FORTRAN, Module: MAIN_PROG Type GO to reach main program predefined trace on activation at routine MAIN_PROG in %PROCESS_NUMBER 1 DBG_1> DBG>

As with a one-process program, the debugger displays its banner, prompts for commands, and suspends execution just prior to the start of execution of the main image. However, note two differences:

• The debugger prompt, which changes to (DBG_1>) after the program is brought under control.
• The "predefined trace on ..." message

The significance of the prompt suffix (_1) is explained Section 15.2.2.

In a multiprocess configuration, the debugger traces each new process that is brought under control. In this case, the debugger traces the first process, which runs the main image of the program. (%PROCESS_NUMBER is a built-in symbol that identifies a process number, just as %LINE identifies a line number.)

See Section 15.3.1 for more information about debugging configurations and process relationships. See Section 15.3.9 for system requirements related to multiprocess debugging.

15.2.2 Visible Process and Process-Specific Commands

The previous example shows that the debugger prompt in a multiprocess debugging configuration is different from that found in the default configuration (after the program is brought under debugger control).

In a multiprocess configuration, dynamic prompt setting is enabled by default (SET PROMPT/SUFFIX=PROCESS_NUMBER). Therefore, the prompt has a process-specific suffix that indicates the process number of the visible process. The debugger assigns a process number sequentially, starting with process 1, to each process that comes under the control of a given debugging session.

The visible process is the default context for issuing process-specific commands. Process-specific commands start execution (STEP, GO, and so on) and look up symbols, set breakpoints, look at the call stack and registers, and so on. Commands that are not process specific do not depend on the mapping of memory but, rather, affect the entire debugging environment (for example, keypad mode and screen mode commands).

Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX), the debugger prompt suffix always identifies the visible process (for example, DBG_1>). The SET PROMPT command provides several options for tailoring the prompt-string prefix and suffix to your needs.

15.2.3 Obtaining Information About Processes

Use the SHOW PROCESS command to obtain information about processes that are currently under control of your debugging session. By default, SHOW PROCESS displays one line of information about the visible process. The following example shows the kind of information displayed immediately after you start the debugger:

DBG_1> SHOW PROCESS Number Name Hold State Current PC * 1 JONES activated MAIN_PROG\%LINE 2 DBG_1>

A one-line SHOW PROCESS display provides the following information about each process specified:

• The process number assigned by the debugger. In this case, the process number is 1 because this is the first process known to the debugger. The asterisk in the leftmost column (*) marks the visible process.
• The process name. In this case, the process name is JONES.
• Whether the process has been put on hold with a SET PROCESS/HOLD command, as explained in Section 15.2.6.2. (This process has not been put on hold.)
• The current debugging state for that process. A process is in the activated state when it is first brought under debugger control (that is, before it has executed any part of the program under debugger control). Table 15-1 summarizes the possible debugging states that can appear in the state column.
• The location (symbolized, if possible) where execution of the image is paused in that process. In this case, the image has not started execution.

Table 15-1 Debugging States

State	Description
Activated	The image and its process have just been brought under debugger control.
Break 1	A breakpoint was triggered.
Interrupted	Execution was interrupted in that process, either because execution was suspended in another process, or because the user interrupted execution with the abort-key sequence (Ctrl/C, by default).
Step 1	A STEP command has completed.
Terminated	The image has terminated execution but the process is still under debugger control. Therefore, you can obtain information about the image and its process.
Trace 1	A tracepoint was triggered.
Unhandled exception	An unhandled exception was encountered.
Watch of	A watchpoint was triggered.

The SHOW PROCESS/ALL command provides information about all processes that are currently under debugger control (in the case of the previous example, a SHOW PROCESS/ALL command would show only process 1). The SHOW PROCESS/FULL command provides additional details about processes.

Returning to the previous example, if you now enter a STEP command followed by a SHOW PROCESS command, the state column in the SHOW PROCESS display indicates that execution is paused at the completion of a step:

DBG_1> SHOW PROCESS Number Name Hold State Current PC * 1 JONES step MAIN_PROG\%LINE 3 DBG_1>

Similarly, if you were to set a breakpoint and enter a GO command, a SHOW PROCESS command entered at the prompt after the breakpoint has triggered would identify the state as break.

15.2.4 Bringing a Spawned Process Under Debugger Control

Continuing with the example from the last section, assume that you have entered a few more STEP commands and, in the middle of a step, MAIN_PROG spawns a process to run a debuggable image called TEST.

Because DBG$PROCESS has the value MULTIPROCESS, the spawned process is now requesting to connect to the current debugging session, and the image TEST is paused at the start of execution.

While the spawned process is waiting to be connected, it is not yet known to the debugger and cannot be identified in a SHOW PROCESS/ALL display. You can bring the process under debugger control using either of the following methods:

• Enter a command, such as STEP, that starts execution (if, as in this example, your program is of the hierarchical model).
• Enter the CONNECT command without specifying a parameter (if your program is of the hierarchical or client/server model). The CONNECT command is preferable in cases when you do not want the program to execute further.

The following example shows use of the CONNECT command:

DBG_1> STEP stepped to MAIN_PROG\%LINE 18 in %PROCESS_NUMBER 1 18: LIB$SPAWN("RUN/DEBUG TEST",,,1) DBG_1> STEP stepped to MAIN_PROG\%LINE 21 in %PROCESS_NUMBER 1 21: X = 7 DBG_1> CONNECT predefined trace on activation at routine TEST in %PROCESS_NUMBER 2 DBG_1>

In this example, the second STEP command takes you past the LIB$SPAWN call that spawns the process. The CONNECT command brings the waiting process under debugger control. After entering the CONNECT command, you might need to wait a moment for the process to connect. The "predefined trace on..." message, as explained in Section 15.2.1, indicates that the debugger has taken control of a new process and identifies that process as process 2, the second process known to the debugger in this session.

A SHOW PROCESS/ALL command, entered at this point, identifies the debugging state for each process and the location at which execution is paused:

DBG_1> SHOW PROCESS/ALL Number Name Hold State Current PC * 1 JONES step MAIN_PROG\%LINE 21 2 JONES_1 activated TEST\%LINE 1+2 DBG_1>

Note that the CONNECT command brings any processes that are waiting to be connected to the debugger under debugger control. If no processes are waiting, you can press Ctrl/C to abort the CONNECT command and display the debugger prompt.

Depending on the version of the debugger you are running on your system, you may be restricted to connection with processes you created. For more information, see the CONNECT command.

Unexpected results can occur if you enter the CONNECT command before you have confirmed that debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG, DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL) translate to the same definitions for both debugger and target process.

15.2.5 Broadcasting Commands to Specified Processes

By default, process-specific commands are executed in the context of the visible process. The DO command enables you to execute commands in the context of one or more processes that are currently under debugger control. This is also referred to as broadcasting commands to processes.

Use the DO command without a qualifier to execute commands in the context of all of the processes. For example, the following command executes the SHOW CALLS command for all processes currently under debugger control (processes 1 and 2, in this case):

DBG_1> DO (SHOW CALLS) For %PROCESS_NUMBER 1 module name routine name line rel PC abs PC *MAIN_PROG MAIN_PROG 21 0000001E 0000041E For %PROCESS_NUMBER 2 module name routine name line rel PC abs PC TEST TEST 1+2 0000000B 0000040B

As indicated in this example, the debugger identifies the process associated with any debugger output.

Use the DO command with the /PROCESS= qualifier to execute commands in the context of specific processes. For example, the following command executes the SET MODULE START and EXAMINE X commands in the context of process 2:

DBG_1> DO/PROCESS=(%PROC 2) (SET MODULE START; EXAMINE X)

For more information about how to specify processes in debugger commands, see Section 15.3.2.

15.2.6 Controlling Execution

Program execution in a multiprocess debugging environment follows these conventions:

• When you enter a command that starts program execution, such as STEP or GO, the command is executed in the context of the visible process. However, images in any other processes that have not been put on hold (with a SET PROCESS/HOLD command) are also allowed to execute. Similarly, if you use the DO command to broadcast a command to start execution in one or more processes, the command is executed in the context of each specified process that is not on hold, but images in any other processes that are not on hold are also allowed to execute. In all cases, a hold condition is ignored in the visible process. (See Section 15.2.6.2 for additional information about the behavior of processes on hold.)
• After execution is started, the way in which it continues depends on whether the SET MODE [NO]INTERRUPT command was entered. By default (SET MODE INTERRUPT), execution continues until it is paused in any process. At that point, execution is interrupted in any other processes that were executing images, and the debugger prompts for input.

These concepts are shown next by continuing with the example in Section 15.2.4 that shows the use of the CONNECT command.

In that example, the "stepped to..." messages indicate that both commands are executed in the context of process 1, the visible process. The second STEP command spawns process 2. The SHOW PROCESS/ALL example of Section 15.2.4 indicates that execution in processes 1 and 2 is paused at MAIN_PROG\%LINE 21 and TEST\%LINE 1+2, respectively.

At this point, entering another STEP command followed by SHOW PROCESS/ALL results in the following display:

DBG_1> STEP stepped to MAIN_PROG\%LINE 23 in %PROCESS_NUMBER 1 23: Y = 15 DBG_1> SHOW PROCESS/ALL Number Name Hold State Current PC * 1 JONES step MAIN_PROG\%LINE 23 2 JONES_1 interrupted TEST\%LINE 3+1 DBG_1>

The STEP command is executed in the context of process 1, the visible process. After the STEP command, execution in process 1 is paused at MAIN_PROG\%LINE 23. However, the STEP command also causes execution to start in process 2. The completion of the STEP command in process 1 causes execution in process 2 to be interrupted at TEST\%LINE 3+1.

Section 15.2.6.1 describes another mode of execution, which is provided by the SET MODE NOINTERRUPT command.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_030.HTML