![[Digital logo]](../../IMAGES/DIGITAL-LOGO.GIF){kind=logo}
![[HR]](../../IMAGES/REDBAR.GIF)
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.
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:
| State | Description |
|---|---|
| Activated | The image and its process have just been brought under debugger control. |
| Break¹ | 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¹ | 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¹ | 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.
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 14.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.
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 14.3.2.
Program execution in a multiprocess debugging environment follows these conventions:
These concepts are shown next by continuing with the example in Section 14.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 14.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 14.2.6.1 describes another mode of execution, which is provided by the SET MODE NOINTERRUPT command.
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.
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>
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.
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).
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.
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 14.3.5 for information on DISCONNECT command restrictions and cautions.
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.
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.
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.
This section provides additional details or more advanced concepts and usages than those covered in Section 14.2.
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.
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
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
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 14.3.9 for system requirements related to multiprocess debugging.
When specifying processes in debugger commands, you can use any of the forms listed in Table 14-2, except when specifying processes with the CONNECT command (see Section 14.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.
| Format | Usage |
|---|---|
| [%PROCESS_NAME] process-name | The process name, if that name contains no spaces or lowercase characters¹. |
| [%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>
4538P023.HTM OSSG Documentation 22-NOV-1996 13:02:06.02
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.