Updated: 11 December 1998

OpenVMS Debugger Manual

The SET MODE NOINTERRUPT command allows execution to continue without interruption in other processes when it is suspended in some process. This is especially useful if, for example, you want to broadcast a STEP command to several processes with the DO command, then complete execution of the STEP command in all these processes. For example:

DBG_1> SET MODE NOINTERRUPT DBG_1> DO (STEP)

In this example, the DO command executes the STEP command in the context of all processes. The visible process and any other processes that are not on hold start execution. Because the SET MODE NOINTERRUPT command was entered, the prompt is displayed only after the STEP command has completed execution (or execution has been otherwise suspended at a breakpoint or watchpoint) in all processes that were executing.

When SET MODE NOINTERRUPT is in effect, as long as execution continues in any process, the debugger does not prompt for input. In such cases, use Ctrl/C to interrupt all processes and display the prompt.

15.2.6.2 Putting Specified Processes on Hold

As indicated in the previous sections, a command that starts execution is executed in the context of the visible process, but it also causes execution to start in other processes. If you want to inhibit execution in a process, put it on hold. For example, the following SET PROCESS/HOLD command puts process 2 on hold. The subsequent STEP command is executed in the context of process 1, the visible process. Execution also starts in any other processes that are not on hold, but not in process 2:

DBG_1> SET PROCESS/HOLD %PROC 2 DBG_1> STEP

A SHOW PROCESS display indicates whether a process is on hold. For example:

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

To release a process from the hold condition, enter the SET PROCESS/NOHOLD command, and specify the process.

Note that a hold condition is ignored in the visible process. Therefore, the SET PROCESS/HOLD/ALL command is a convenient way to confine execution to the visible process. In the following example, execution starts only in the visible process:

DBG_1> SET PROCESS/HOLD/ALL DBG_1> STEP

This feature is useful if, for example, you want to use the CALL command to execute a dump routine that is not part of the execution stream of your program.

The previous discussions also apply if you use the DO command to broadcast a GO, STEP, or CALL command to several processes. The GO, STEP or CALL command is executed in the context of each specified process that is not on hold, and execution also starts in any other process that is not on hold. The following example shows the execution behavior when all processes are put on hold and commands are broadcast to all processes. Execution starts only in the visible process (process 1, in this example):

DBG_1> SET PROCESS/HOLD/ALL DBG_1> DO (EXAMINE X; STEP) For %PROCESS_NUMBER 1 MAIN_PROG\X: 78 For %PROCESS_NUMBER 2 TEST\X: 29 stepped to MAIN_PROG\%LINE 26 in %PROCESS_NUMBER 1 26: K = K + 1 DBG_1>

15.2.7 Changing the Visible Process

Use the SET PROCESS command (with the default /VISIBLE qualifier) to establish another process as the visible process. For example, the following command makes process 2 the visible process:

DBG_1> SET PROCESS %PROC 2 DBG_2>

In this example, because dynamic prompt setting is enabled by default, the SET PROCESS command also has caused the prompt string suffix to change. It now indicates that process 2 is the visible process. All process-specific commands are now executed in the context of process 2. For example, a SHOW CALLS command would display the call stack for the image running in process 2.

15.2.8 Dynamic Process Setting

By default, dynamic process setting is enabled (SET PROCESS/DYNAMIC). As a result, whenever the debugger suspends program execution and displays its prompt, the process in which execution is suspended becomes the visible process automatically. Dynamic process setting occurs in the following situations: when a breakpoint or watchpoint is triggered, at an exception condition, on the completion of a STEP command, or when the last process performs an image exit.

When dynamic process setting is disabled (/NODYNAMIC), the visible process remains unchanged until you specify another process with the SET PROCESS/VISIBLE command.

Dynamic process setting is shown in the following example, which also shows dynamic prompt setting:

DBG_1> SHOW PROCESS/ALL Number Name Hold State Current PC * 1 JONES step MAIN_PROG\%LINE 22 2 JONES_1 interrupted TEST\%LINE 4 DBG_1> DO/PROCESS=(%PROC 2) (SET BREAK %LINE 11) DBG_1> GO . . . break at TEST\%LINE 11 in %PROCESS_NUMBER 2 DBG_2> SHOW PROCESS/ALL Number Name Hold State Current PC 1 JONES interrupted MAIN_PROG\%LINE 28 * 2 JONES_1 break TEST\%LINE 11 DBG_2>

In this example, process 1 is initially the visible process, as indicated by the prompt and the SHOW PROCESS display. The DO command sets a breakpoint in the context of process 2. Execution is resumed with the GO command and is suspended at the breakpoint in process 2. Process 2 is now the visible process, as indicated by the prompt and the SHOW PROCESS display.

If you have entered the SET MODE NOINTERRUPT command and then started execution in several processes with the DO command, the prompt is displayed only after execution has been suspended in all processes. In this case, the visible process remains unchanged, unless the last process performs an image exit (and thereby becomes the visible process).

15.2.9 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/ALL display. You can enter commands to examine variables, and so on.

When the last image of the program exits, the debugger gains control and displays its prompt.

15.2.10 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, the following command disconnects the JONES image:

DBG> DISCONNECT JONES DBG>

See Section 15.3.5 for information on DISCONNECT command restrictions and cautions.

15.2.11 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, the following command terminates the image running in process 2 and terminates the process:

DBG_3> EXIT %PROC 2 DBG_3>

Subsequently, process 2 does not appear in a SHOW PROCESS display. See the the EXIT and QUIT command descriptions.

15.2.12 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.

As in the default configuration, you can also use Ctrl/C to abort a debugger command.

15.2.13 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.

Thus, when you do not specify any parameters, the behavior of EXIT and QUIT is analogous to their behavior for the default debugging configuration.

15.3 Supplemental Information

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

15.3.1 Debugging Configurations and Process Relationships

You can start the debugger in either the default configuration or the multiprocess configuration to debug programs that run in either one or several processes, respectively.

The debugging configuration depends on the current definition of the logical name DBG$PROCESS, as indicated in the following table:

Definition of Logical Name DBG$PROCESS	Resulting Debugging Configuration
Undefined or DEFAULT	Default (use this configuration with a program that runs in one process)
MULTIPROCESS	Multiprocess (use this configuration with a program that runs in several processes)

Note that the debugging configuration does not depend on whether the program runs in one or several processes. Rather, the current definition of DBG$PROCESS determines whether debuggable images running in different processes can be controlled from the same debugging session.

Before starting the debugger, enter the DCL command SHOW LOGICAL DBG$PROCESS to determine the current definition of DBG$PROCESS and the resulting debugging configuration.

15.3.1.1 Establishing a Default Debugging Configuration

Use the default configuration to debug a program that normally runs (without the debugger) in only one process. This configuration is achieved when DBG$PROCESS is either undefined or has the definition DEFAULT.

In the following example, the output of the SHOW LOGICAL command indicates that a default debugging configuration is in effect:

$ SHOW LOGICAL DBG$PROCESS %SHOW-S-NOTRAN, no translation for logical name DBG$PROCESS

If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a program that runs in only one process, enter the following command:

$ DEFINE DBG$PROCESS DEFAULT

15.3.1.2 Establishing a Multiprocess Debugging Configuration

Use the multiprocess configuration to debug a program that normally runs in more than one process. This configuration is achieved when DBG$PROCESS has the definition MULTIPROCESS, and it enables you to interact with several processes. Use the following command to establish a multiprocess debugging configuration:

$ DEFINE/GROUP DBG$PROCESS MULTIPROCESS

15.3.1.3 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 start the debugger, a process is created to run the main debugger. Regardless of the configuration (default or multiprocess), the presence of a main debugger running in some process establishes a unique debugging session.

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

In the multiprocess configuration, the program being debugged runs in several processes. Each process that is running one or more images under debugger control is also running a local copy of the kernel debugger. The main debugger, running in its own process, communicates with the other processes through their kernel debuggers.

Although all processes of a multiprocess configuration 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.3.9 for system requirements related to multiprocess debugging.

15.3.2 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.3.4.2).

The CONNECT command is used to bring a process that is not yet known to the debugger under debugger control. Therefore, when specifying a process with CONNECT, you can use only its process name or process identifier (PID). You cannot use its debugger-assigned process number or any of the process built-in symbols (for example, %NEXT_PROCESS) for the process.

Table 15-2 Process Specifications

Format	Usage
[%PROCESS_NAME] process-name	The process name, if that name does not contain spaces or lowercase characters 1.
[%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 is not reused 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-group-name	A symbol defined with the DEFINE/PROCESS_GROUP 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 built-in symbol when entering commands. For example:

DBG_2> SHOW PROCESS %PROC 2, JONES_3

You can define a symbol to represent a group of processes (DEFINE/PROCESS_GROUP). This enables you to enter commands in abbreviated form. For example:

DBG_1> DEFINE/PROCESS_GROUP SERVERS=FILE_SERVER, NETWORK_SERVER DBG_1> SHOW PROCESS SERVERS Number Name Hold State Current PC * 1 FILE_SERVER step FS_PROG\%LINE 37 2 NETWORK_SERVER break NET_PROG\%LINE 24 DBG_1>

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.3.3 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 by means of 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 assumed by 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.

Also, 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.3.4 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.
• To interrupt an image and connect it to an existing debugging session, use the CONNECT command.

You use the Ctrl/Y--DEBUG sequence with the multiprocess debugging configuration as with the default configuration (see Section 1.7):

1. Run the image from DCL level with the RUN/NODEBUG command.
2. Press Ctrl/Y to interrupt the image.
3. Enter the DEBUG command to start the debugger.

The following example shows how you might start a new debugging session:

$ DEFINE/GROUP DBG$PROCESS MULTIPROCESS $ RUN/NODEBUG PROG2 . . . [Ctrl/Y] Interrupt $ DEBUG Debugger Banner and Version Number Language: FORTRAN, Module: SUB4 predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 1 DBG_1>

In this example, the DEFINE/JOB command establishes a multiprocess debugging configuration. The RUN/NODEBUG command starts the execution of image PROG2 without debugger control. The Ctrl/Y--DEBUG sequence interrupts execution and starts the debugger.

The debugger banner indicates that a new debugging session has been started. The process-specific prompt (DBG_1>) indicates that this is a multiprocess configuration and that execution is paused in process 1, which is running image PROG2.

The activation tracepoint identifies the location at which execution was interrupted (and at which the debugger took control of the process). You can also use the SHOW CALLS command to display the call stack at that location.

After the debugger has been started, you can use the CONNECT command to bring other processes under debugger control. In the previous example, you could use the CONNECT command to bring processes under debugger control that were created by PROG2 before you interrupted its execution (see Section 15.3.4.2).

When using the Ctrl/Y--DEBUG sequence, if a multiprocess debugging session already exists in the same group as the image that is interrupted, the image connects to that session. In this case, because a new session is not started, the debugger banner is not displayed when the debugger takes control. This situation could occur if, for example, you entered a SPAWN/NOWAIT command from the session, started execution with a RUN/NODEBUG command, and then entered a Ctrl/Y--DEBUG sequence.

15.3.4.2 Using the CONNECT Command to Interrupt an Image

The CONNECT command, used without a parameter, was introduced in Section 15.2.4. When used with a parameter, the CONNECT command enables you to interrupt a debuggable image that is running without debugger control and bring it under control of your current debugging session.

The image might have been activated as follows:

• Your program issued a LIB$SPAWN run-time library call to spawn a process and run an image without debugger control
• You started execution with a RUN/NODEBUG command entered at DCL level

In the following example, the CONNECT command causes the image running in process JONES_3 to be interrupted and to come under control of the current debugging session. Process JONES_3 must be in the same job as the session.

DBG_1> CONNECT JONES_3

Note that a process is not identified by a debugger process number until it is connected to a debugging session. Therefore, when specifying a process with the CONNECT command, you can use only its process name or process identifier (PID).

The effect of the CONNECT command is equivalent to attaching to a process from a debugging session and then entering the sequence Ctrl/Y--DEBUG to interrupt the running image and start the debugger. However, the CONNECT command is easier to enter and also enables you to interrupt a process to which you cannot attach.

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

4538PRO_031.HTML