Document revision date: 19 July 1999
[Compaq] [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]
[OpenVMS documentation]

OpenVMS Debugger Manual


Previous Contents Index

14.6 Debugging Exit Handlers

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:
    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:

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.


Chapter 15
Debugging Multiprocess Programs

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:

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.

Note

If a spawned process image has been linked with the /DEBUG qualifier, or if the SPAWN command runs the image with the /DEBUG qualifier, the parent process must (in the debugging session) spawn the child process with the NOWAIT flag set in the flags argument.

15.2.1 Starting a Multiprocess Debugging Session

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 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:

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.


1See the SHOW PROCESS command description for a list of additional states.

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:

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:

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.


Previous Next Contents Index

  [Go to the documentation home page] [How to order documentation] [Help on this site] [How to contact us]  
  privacy and legal statement  
4538PRO_030.HTML