HP OpenVMS systems documentation

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 and I64 Only)

On OpenVMS Alpha and I64 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 HP 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. For example, 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 this application 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.

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

15.1 Basic Multiprocess Debugging Techniques

This section introduces basic concepts of multiprocess debugging. Refer to subsequent sections for complete details.

15.1.1 Starting a Multiprocess Debugging Session

This section explains the easiest way to start a multiprocess debugging session. Section 15.16.3 describes additional ways to start the debugger.

To start a multiprocess debugging session, start the kept debugger. For example,

$ debug/keep OpenVMS I64 Debug64 Version T8.2-008 DBG>

In a multiprocess debugging session, the debugger traces each new process that is brought under control. The debugger identifies each process with a decimal process number, as shown in Example 15-1.

Example 15-1 RUN/NEW Command

DBG> SHOW PROCESS Number Name State Current PC * 1 DBGK$$2727282C activated SERVER\__main DBG> RUN/NEW CLIENT process 2 %DEBUG-I-INITIAL, Language: C, Module: CLIENT %DEBUG-I-NOTATMAIN, Type GO to reach MAIN program predefined trace on activation at CLIENT\__main all> SHOW PROCESS Number Name State Current PC * 1 DBGK$$2727282C activated SERVER\__main 2 USER_2 activated CLIENT\__main all>

The RUN/NEW CLIENT command in Example 15-1 starts the program CLIENT in a new process. The first time (in a debugging session) that the debugger has more than one process under its control, it changes its prompt to all> to identify the set of all processes under its control.

Processes and Process Sets

Once the debugger is aware of more than one process, the debugger prompt changes to the identifier of the current process set, followed by a right angle bracket (>).

Conceptually, each process belongs to a set of one, identified by default by the unique decimal number assigned to it when the debugger takes control of the process. A process can belong to more than one set. All processes under debugger control are grouped by default into a set named all.

You can group processes into user-named sets with the DEFINE /PROCESS_SET command.

Current Process Set

Debugger commands apply by default to the current process set. By default, the current process set is the set named all. You can change the current process set with the SET PROCESS command.

Command Process Set

The set of processes at which a command is directed is called the command process set. The default command process set is the current process set.

Process Set Prefix

You can give a debugger command that applies to a command process set other than the current process set without changing the current process set. To do so, prefix the command with the name of the process set followed by a right angle bracket (>). For example:

all> 1,2,5> GO

1,2,5> is a process set prefix. This syntax allows you to cut and paste commands from a previous command line.

Visible Process

The visible process is the process that is shown in current displays, and is identified by an asterisk (*) in column 1 in a SHOW PROCESS display. You can change the visible process with the SET PROCESS/VISIBLE command. For example:

all> SHOW PROCESS Number Name State Current PC * 1 DBGK$$2727282C activated SERVER\__main 2 USER_2 activated CLIENT\__main all>

In the above example, process number 1 is the visible process.

15.2 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 information about all processes under control of the debugger. (These are the processes in process set all.) Example 15-2 shows the type of information displayed immediately after you start the debugger.

Example 15-2 SHOW PROCESS Command

DBG> SHOW PROCESS/BRIEF/ALL Number Name State Current PC * 1 JONES activated MAIN_PROG\%LINE 2 DBG>

Note that the qualifiers /BRIEF and /ALL are the default. Note also that the debugger displays its default prompt, because the debugger still has only one process under its control. The SHOW PROCESS command provides the following information about each process specified:

• The process number assigned by the debugger. In Example 15-2, 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.
• 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 of a process under debugger control.
• The location (symbolized, if possible) where execution of the image is paused in that process. In Example 15-2, the image has not yet started execution.

Table 15-1 Debugging States

State		Description
Running		Executing under control of the debugger.
Stopped
	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, in one of the following ways: Execution was suspended in another process. It was interrupted with the abort-key sequence (Ctrl/C, by default). It was interrupted by the STOP command.
	Step 1	A STEP command has completed.
	Trace 1	A tracepoint was triggered.
	Unhandled exception	An unhandled exception was encountered.
	Watch of	A watchpoint was triggered.
	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.

Returning to Example 15-2, 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. For example:

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

Similarly, if you were to set a breakpoint and then enter a GO command, a SHOW PROCESS command entered once the breakpoint has triggered identifies the state as break.

15.3 Process Specification

Each new process to which the debugger connects is identified by a process-number. The first process is process-number 1, the second process is process-number 2, and so on. When a process stops, its process number is recycled and is available to the debugger for assignment to a subsequent process.

Processes are referred to using the process-spec. The most simple process-spec is either a process-name created by OpenVMS when the process is created, or a process-number created by the debugger when the debugger gains control of the process. A process-spec that consists of only numbers is interpreted as a process number. Within debugger commands, you can use process-numbers to specify individual processes (for example, "2,3,4,5").

A process-spec-item can be a name, in which case it can refer to a process-name or a process-set-name. The debugger tries first to find a process-set with that name. If unsuccessful, the debugger then tries to match a process to the name. You can explicitly specify the process-name by using the %PROCESS_NAME lexical function.

Example 15-3 contains the complete process specification syntax.

Example 15-3 Process Specification Syntax

process-spec ::= process-spec-item [, process-spec-item] process-spec-item ::= named-item | numbered-item | pid-item | process-set-name | special-item named-item ::= [%PROCESS_NAME] wildcard-name numbered-item ::= numbered-process numbered-process ::= [%PROCESS_NUMBER] decimal-number pid-item ::= %PROCESS_ID VMS-process-identifier process-set-name ::= name special-item ::= %NEXT_PROCESS | %PREVIOUS_PROCESS | %VISIBLE_PROCESS

15.4 Process Sets

You can place processes into groups called process sets with the DEFINE PROCESS_SET command followed by a list of processes separated by commas (,). For example:

all> DEFINE/PROCESS CLIENTS = 2,3 all> SET PROCESS CLIENTS clients> STEP process 2,3 stepped to CLIENT\main\%LINE 18796 18796: status = sys$crembx (0, &mbxchan, 0, 0, 0, 0, &mbxname_dsc, CMB$M_READONLY, 0); clients> SHOW PROCESS CLIENTS Number Name State Current PC 2 USER1_2 step CLIENT\main\%LINE 18796 3 USER1_3 step CLIENT\main\%LINE 18796 clients>

There is a predefined process set named all, which is the default process set when the debugger is first invoked. You cannot redefine this process set.

Current Process Set

At any time during a debugging session, there is a current process set in effect. The current process set is the group of processes to which debugger process-sensitive commands apply by default. See Section 15.6 for a list of debugger commands that are process-sensitive.

By default, the current process set is the set of all processes, with the process set name all. You can change the current process set with the SET PROCESS command.

The SET PROCESS command does three things:

• It specifies the current process set.
• It controls the visible process with the /VISIBLE qualifier.
• It turns dynamic process setting on or off with the /[NO]DYNAMIC qualifier.

When used without a qualifier, the SET PROCESS command takes a single parameter, a process-spec, which specifies the current process set. For example:

all> SET PROCESS 1 1> STEP process 1 stepped to SERVER\main\%LINE 18800 18800: if (!(status & 1)) 1> SET PROCESS ALL all>

The SET PROCESS/DYNAMIC command directs the debugger to change the visible process when a debugger event occurs, such as the completion of a STEP command, or the triggering of a breakpoint. The visible process becomes the process that triggered the event. For example:

all> SET PROCESS/DYNAMIC all> 1> STEP process 1 stepped to SERVER\main\%LINE 18808 18808: df_p = fopen (datafile, "r+"); all> SHOW PROCESS/VISIBLE Number Name State Current PC * 1 DBGK$$2727282C step SERVER\main\%LINE 18808 all>

Command Process Set

The command process set is the group of processes to which a debugger command is directed. By default, the command process set is the current process set. You can use a process set prefix to specify a command process set for the current command, which overrides the current process set for that single command. For example:

all> 2,3> STEP processes 2,3 stepped to CLIENT\main\%LINE 18797 18797: if (!(status & 1)) all> clients> STEP processes 2,3 stepped to CLIENT\main\%LINE 18805 18805: memset (&myiosb, 0, sizeof(myiosb)); all>

Process-independent commands ignore any process set prefix, just as they ignore the current process set.

15.5 Debugger Prompts

By default, the debugger command prompt indicates the current process set, using the same syntax as the process-spec. The command prompt is the current process set process-spec followed by a right angle bracket (>). When you define the current process set, the debugger changes its prompt to the name of the current process set, followed by a right angle bracket. For example:

all> ! by default, current process set is all processes all> all> SET PROCESS 2,3,4,5 2,3,4,5> DEFINE /PROCESS_SET interesting 1,2,3,7 2,3,4,5> SET PROCESS interesting interesting> SET PROCESS * all> SET PROCESS 3 3>

There are two types of commands, process-sensitive and process-independent.

Process-sensitive commands are those that depend on the state of a process, such as GO, STEP, CALL, and SET BREAK.

Process-independent commands are those that depend on and affect the state of the debugger and ignore the state of processes, such as SET DISPLAY, WAIT, ATTACH, and SPAWN.

15.7 Visible Process and Process-Sensitive Commands

The visible process is the process shown by default in the source display (and other such process-oriented displays). When the current process set is changed with the SET PROCESS command, the visible process is set to be the first process specified in that command. You can use the SET PROCESS/VISIBLE command to specify a particular process as the visible one without changing the current process set.

15.8 Controlling Process Execution

When debugging an application with multiple processes, it is common to have some process stopped while other processes are still running. It can be useful to be able to give commands only to those processes that are stopped without waiting for all processes to stop. Wait mode provides that capability.