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.

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

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

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.