[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP OpenVMS Debugger Manual

15.8.1 WAIT Mode

With regard to executing processes, the debugger has two modes: wait and nowait. You can control whether or not the debugger waits for all running processes to stop before the debugger accepts and executes another command by toggling wait mode with the SET MODE [NO]WAIT command. Wait mode is the default.

When the debugger is in wait mode and you enter the GO, STEP, or CALL command, the debugger executes the command in all processes in the command process set, and waits until all those processes stop (for example, at breakpoints) before displaying a prompt and accepting another command.

When the debugger is in nowait mode and you enter the GO, STEP, or CALL command, the debugger executes the command in all processes in the command process set, and immediately displays a prompt. You can enter a new command immediately, regardless of whether any or all processes have stopped. This provides great flexibility, especially when debugging multiprocess programs.

Control over WAIT mode allows you to to do the following:

While the program is running, you can use the debugger as a source browser. Because the source view is process-independent, you can change its focus while processes are executing.
You can control separate processes one at a time.
You can control more than one process at a time.

A SET MODE [NO]WAIT command remains in effect until the next SET MODE [NO]WAIT command. For example:

all> SET MODE NOWAIT
all> clients> STEP
all> SHOW PROCESS
 Number  Name          State            Current PC
     1 DBGK$$2727282C  step     SERVER\main\%LINE 18819
     2 USER1_2         running          not available
*    3 USER1_3         running          not available
all>

You can use the WAIT command to override nowait mode for the duration of one command, to direct the debugger to wait until all processes in the command process set stop before prompting for another command. Nowait mode remains in effect when the command completes. For example:

all> GO;WAIT
processes 2,3
  break at CLIENT\main\%LINE 18814
        18814:       status = sys$qiow (EFN$C_ENF,  mbxchan,
IO$_READVBLK|IO$M_WRITERCHECK, &myiosb,
process 1
  break at SERVER\main\%LINE 18834
        18834:       if ((myiosb.iosb$w_status ==
                          SS$_NOREADER) && (pos_status != -1))
all>

When commands are processed in a non-interactive manner (within debugger command sequences within FOR, REPEAT, WHILE, IF, and @ commands, and within WHEN clauses), WAIT mode is enabled by default during the execution of the command sequence.

During NOWAIT mode, an EXAMINE command (similar to all process-independent commands) displays results for those processes in its command process set that are stopped. If all processes in its command process set are running, the EXAMINE command reports that condition and the debugger displays a prompt and accepts a new command. Similarly, a GO command during NOWAIT mode starts all stopped processes in the command process set.

15.8.2 Interrupt Mode

Use the SET MODE [NO]INTERRUPT command to toggle the state of interrupt mode. When interrupt mode is toggled on, the debugger stops all processes when one process stops. This can be a disadvantage if an interrupted process is deep into a RTL or system service call because it can leave many irrelevant non-symbolic frames on top of the process stack.

When interrupt mode is toggled off, the debugger does not stop any other process unless you enter a STOP command. This is the default mode.

15.8.3 STOP Command

Use the STOP command to interrupt running processes. The STOP command interrupts all of the running processes in its command process set.

The STOP command completes as soon as it sends a stop request to every running process in the command set. For example:

all> SHOW PROCESS
 Number  Name          State            Current PC
     1 DBGK$$2727282C  break    SERVER\main\%LINE 18834
     2 USER1_2         running          not available
*    3 USER1_3         running          not available
all> clients> STOP
all> SHOW PROCESS
 Number  Name          State            Current PC
     1 DBGK$$2727282C  break    SERVER\main\%LINE 18834
     2 USER1_2         interrupted   0FFFFFFFF800F7A20
*    3 USER1_3         interrupted   0FFFFFFFF800F7A20
all>

15.9 Connecting to Another Program

You can bring a debuggable program under control of the debugger from a kept debugger session. This could be a client program that runs independently in another process. Because the debugger is not yet aware of that process, you cannot obtain information about it from a SHOW PROCESS command. Enter the CONNECT command and specify the process name of the client program with the debugger %PROCESS_NAME lexical function. For example:

all> CONNECT %PROCESS_NAME CLIENT2
process 3
  predefined trace on activation at 0FFFFFFFF800F7A20
all> SHOW PROCESS
 Number  Name          State            Current PC
*    1 DBGK$$2727282C  activated        SERVER\__main
     2 USER1_2         activated        CLIENT\__main
     3 CLIENT2         interrupted   0FFFFFFFF800F7A20
                        activated
all>

Unexpected results can occur if you enter the CONNECT command if any of the debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG, DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL) differ between the debugger main process and the process in which the client runs.

15.10 Connecting to a Spawned Process

When a program you are debugging (with the kept debugger) spawns a debuggable process, the spawned process waits to be connected to the debugger. At this time the debugger has no information about the newly spawned process, and you cannot get information about that process from a SHOW PROCESS command. You can bring the newly spawned process under debugger control using either of the following methods:

Enter a command, such as STEP, that starts execution (if, as in the following example, your program is of the hierarchical model).
Enter the CONNECT command without specifying a parameter. The CONNECT command is useful in cases when you do not want the process to execute further.

The following example shows this use of the CONNECT command:

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

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 indicates that the debugger has taken control of a new process which is identified as process 2.

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

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

Note that the CONNECT command brings all 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.

15.11 Monitoring the Termination of Images

When the main image of a process runs to completion, the process goes into the terminated debugging state (not to be confused with process termination in the operating system sense). This condition is traced by default, as if you had entered the SET TRACE/TERMINATING command.

When a process is in the terminated debugging state, it is still known to the debugger and appears in a SHOW PROCESS display. You can enter commands to examine variables, and so on.

15.12 Releasing a Process From Debugger Control

To release a process from debugger control without terminating the process, enter the DISCONNECT command. (In contrast, when you specify a process with the EXIT or QUIT command, the process is terminated.)

This command is required for programs of the client/server model. For example:

all> SHOW PROCESS
 Number  Name          State            Current PC
*    1 DBGK$$2727282C  step     SERVER\main\%LINE 18823
     2 USER1_2         step     CLIENT\main\%LINE 18805
     3 USER1_3         step     CLIENT\main\%LINE 18805
all> DISCONNECT 3
all> SHOW PROCESS
 Number  Name          State            Current PC
*    1 DBGK$$2727282C  step     SERVER\main\%LINE 18823
     2 USER1_2         step     CLIENT\main\%LINE 18805
all> QUIT 1,2
DBG> SHOW PROCESS
  %DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$

Bear in mind that the debugger kernel runs in the same process as the image being debugged. If you issue the DISCONNECT command for this process, you release your process, but the kernel remains activated. This activation continues until the program image finishes running. If you install a new version of the debugger while one or more disconnected but activated kernels inhabit user program space, you can experience problems with debugger behavior if you try to reconnect to that program image.

15.13 Terminating Specified Processes

To terminate specified processes without ending the debugging session, use the EXIT or QUIT command, specifying one or more process specifications as parameters. For example,

all> SHOW PROCESS
 Number  Name          State            Current PC
*    1 DBGK$$2727282C  step     SERVER\main\%LINE 18823
     2 USER1_2         step     CLIENT\main\%LINE 18805
all> QUIT 1,2
DBG> SHOW PROCESS
  %DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$

15.14 Interrupting Program Execution

Pressing Ctrl/C (or the abort-key sequence established with the SET ABORT_KEY command) interrupts execution in every process that is currently running an image. This is indicated as an interrupted state in a SHOW PROCESS display.

Note that you can also use Ctrl/C to abort a debugger command.

You can also stop a process with the debugger STOP command.

15.15 Ending the Debugging Session

To end the entire debugging session, use the EXIT or QUIT command without specifying any parameters.

EXIT executes any exit handlers that are declared in the program. QUIT does not.

QUIT Command

Use the QUIT command to terminate running processes. The QUIT command terminates all of the running processes in its command process set without allowing any exit handlers to run. A process set prefix is ignored before a QUIT command. For example:

all> SHOW PROCESS
 Number  Name          State            Current PC
*    1 DBGK$$2727282C  step     SERVER\main\%LINE 18823
     2 USER1_2         step     CLIENT\main\%LINE 18805
all> QUIT 1,2
DBG> SHOW PROCESS
  %DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$

The QUIT command ignores the current process set. If you do not specify a process, the QUIT command terminates all processes and then terminates the debugging session.

EXIT Command

Use the EXIT command to terminate running processes. The EXIT command terminates all of the running processes in its command process set without allowing any exit handlers to run. A process set prefix is ignored before an EXIT command. For example:

all> SHOW PROCESS
 Number  Name          State            Current PC
*    1 DBGK$$2727282C  step     SERVER\main\%LINE 18823
     2 USER1_2         step     CLIENT\main\%LINE 18805
all> EXIT 1,2
DBG> SHOW PROCESS
  %DEBUG-W-NOPROCDEBUG, there are currently no processes being debugged
DBG> EXIT
$

The EXIT command ignores the current process set. If you do not specify a process, the EXIT command terminates all processes and then terminates the debugging session.

15.16 Supplemental Information

This section provides additional details or more advanced concepts and usages than those covered in Section 15.1.

15.16.0.1 Process Relationships When Debugging

The debugger consists of two parts: a main debugger image (DEBUGSHR.EXE) that contains most of the debugger code and a smaller kernel debugger image (DEBUG.EXE). This separation reduces potential interference between the debugger and the program being debugged and also makes it possible to have a multiprocess debugging configuration.

When you bring a program under control of the kept debugger, the main debugger spawns a subprocess to run the program along with the kernel debugger.

An application being debugged might run in several processes. Each process under debugger control is running a local copy of the kernel debugger. The main debugger, which is running in its own process, communicates with the other processes through their kernel debuggers.

Although all processes must be in the same UIC group, they do not have to be related in a particular process/subprocess hierarchy. Moreover, the program images running in separate processes do not have to communicate with each other.

See Section 15.16.6 for system requirements related to multiprocess debugging.

15.16.1 Specifying Processes in Debugger Commands

When specifying processes in debugger commands, you can use any of the forms listed in Table 15-2, except when specifying processes with the CONNECT command (see Section 15.9).

Use the CONNECT command to bring a process that is not yet known to the debugger under debugger control. Until you bring a new process under control of the debugger, the process does not have a debugger-assigned process number, nor can you reference it with any of the built-in process symbols (for example, %NEXT_PROCESS). Therefore, when specifying a process with CONNECT, you can use only its process name or process identifier (PID).

**Table 15-2 Process Specifications**
Format	Usage
[%PROCESS_NAME] process-name	The process name, if that name does not contain spaces or lowercase characters. The process name can include the asterisk (*) wildcard character.
[%PROCESS_NAME] " process-name "	The process name, if that name contains spaces or lowercase characters. You can also use apostrophes (') instead of quotation marks (").
%PROCESS_PID process_id	The process identifier (PID, a hexadecimal number).
[%PROCESS_NUMBER] process-number (or %PROC process-number)	The number assigned to a process when it comes under debugger control. A new number is assigned sequentially, starting with 1, to each process. If a process is terminated with the EXIT or QUIT command, the number can be assigned again during the debugging session. Process numbers appear in a SHOW PROCESS display. Processes are ordered in a circular list so they can be indexed with the built-in symbols %PREVIOUS_PROCESS and %NEXT_PROCESS.
process-set-name	A symbol defined with the DEFINE/PROCESS_SET command to represent a group of processes.
%NEXT_PROCESS	The next process after the visible process in the debugger's circular process list.
%PREVIOUS_PROCESS	The process previous to the visible process in the debugger's circular process list.
%VISIBLE_PROCESS	The process whose stack, register set, and images are the current context for looking up symbols, register values, routine calls, breakpoints, and so on.

You can omit the %PROCESS_NAME and %PROCESS_NUMBER built-in symbols when entering commands. For example:

2> SHOW PROCESS 2, JONES_3

The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and %PREVIOUS_PROCESS are useful in control structures based on the IF, WHILE, or REPEAT commands and in command procedures.

15.16.2 Monitoring Process Activation and Termination

By default, a tracepoint is triggered when a process comes under debugger control and when it performs an image exit. These predefined tracepoints are equivalent to those resulting from entering the SET TRACE/ACTIVATING and SET TRACE/TERMINATING commands, respectively. You can set breakpoints on these events with the SET BREAK/ACTIVATING and SET BREAK/TERMINATING commands.

To cancel the predefined tracepoints, use the CANCEL TRACE/PREDEFINED command with the /ACTIVATING and /TERMINATING qualifiers. To cancel any user-defined activation and termination breakpoints, use the CANCEL BREAK command with the /ACTIVATING and /TERMINATING qualifiers (the /USER qualifier is the default when canceling breakpoints or tracepoints).

The debugger prompt is displayed when the first process comes under debugger control. This enables you to enter commands before the main image has started execution, as with a one-process program.

Similarly, the debugger prompt is displayed when the last process performs an image exit. This enables you to enter commands after the program has completed execution, as with a one-process program.

15.16.3 Interrupting the Execution of an Image to Connect It to the Debugger

You can interrupt a debuggable image that is running without debugger control in a process and connect that process to the debugger.

To start a new debugging session, use the Ctrl/Y--DEBUG sequence from DCL level. Note that this starts the unkept debugger, which you cannot use for debugging multiprocess programs.
To interrupt an image and connect it to an existing multiprocess debugging session, use the debugger CONNECT command.

15.16.4 Screen Mode Features for Multiprocess Debugging

By default, the source, instruction, and register displays show information about the visible process.

By using the /PROCESS qualifier with the DISPLAY command, you can create process-specific displays or make existing displays process specific, respectively. The contents of a process-specific display are generated and modified in the context of that process. You can make any display process specific except for the PROMPT display. For example, the following command creates the automatically updated source display SRC_3, which shows the source code where execution is suspended in process 3:

2> DISPLAY/PROCESS=(3) SRC_3 AT RS23 -
2> SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC)

Assign attributes to process-specific displays in the same way as for displays that are not process specific. For example, the following command makes display SRC_3 the current scrolling and source display; that is, the output of SCROLL, TYPE, and EXAMINE/SOURCE commands are then directed at SRC_3:

2> SELECT/SCROLL/SOURCE SRC_3

If you enter a DISPLAY/PROCESS command without specifying a process, the specified display is then specific to the process that was the visible process when you entered the command. For example, the following command makes display OUT_X specific to process 2:

2> DISPLAY/PROCESS OUT_X

In a multiprocess configuration, the predefined tracepoint on process activation automatically creates a new source display and a new instruction display for each new process that comes under debugger control. The displays have the names SRC_n and INST_n, respectively, where n is the process number. These displays are initially marked as removed. They are automatically deleted on process termination.

Several predefined keypad key sequences enable you to configure your screen with the process-specific source and instruction displays that are created automatically when a process is activated. Key sequences that are specific to multiprocess programs are as follows: PF1 KP9, PF4 KP9, PF4 KP7, PF4 KP3, PF4 KP1. See Section A.5 for the general effect of these sequences. Use the SHOW KEY command to determine the exact commands.

Contents

Index