Document revision date: 19 July 1999

When your program completes execution normally during a debugging session, the debugger issues the following message:

'Normal successful completion'

You then have the following options:

• You can rerun your program from the same debugging session (see Section 1.3.3).
• You can run another program from the same debugging session (see Section 1.3.4).
• You can end the debugging session (see Section 1.8).

You can rerun the program currently under debugger control at any time during a debugging session, provided you invoked the kept debugger as explained in Section 1.3.1. Use the RERUN command. For example:

DBG> RERUN Language: C, Module: FORMS Type GO to reach main program DBG>

The RERUN command terminates the image you were debugging and brings a fresh copy of that image under debugger control, pausing at the start of the main source module as if you had used the RUN command (see Section 1.3.1).

When you use the RERUN command you can save the current state (activated or deactivated) of any breakpoints, tracepoints, and static watchpoints. Note that the state of a particular nonstatic watchpoint might not be saved, depending on the scope of the variable being watched relative to the main program unit (where execution restarts). RERUN/SAVE is the default. To clear all breakpoints tracepoints, and watchpoints, enter RERUN/NOSAVE.

The RERUN command invokes the same version of the image that is currently under debugger control. To debug a different version of that program (or a different program) from the same debugging session, use the RUN command. To rerun a program with new arguments, use the /ARGUMENTS qualifier (see RUN and RERUN Command Options for Programs That Require Arguments).

1.3.4 Running Another Program from the Kept Debugger

You can bring another program under debugger control at any time during a debugging session, provided you invoked the kept debugger as explained in Section 1.3.1. Use the debugger RUN command. For example:

DBG> RUN TOTALS Language: FORTRAN, Module: TOTALS DBG>

The debugger loads the program and pauses execution at the start of the main source module.

For more information about startup conditions and restrictions, see Section 1.3.1.

For information about all RUN command options, see the debugger RUN command description.

1.4 Interrupting Program Execution and Aborting Debugger Commands

If your program goes into an infinite loop during a debugging session so that the debugger prompt does not reappear, press Ctrl/C. This interrupts program execution and returns you to the debugger prompt (pressing Ctrl/C does not end the debugging session). For example:

DBG> GO . . . [Ctrl/C] DBG>

You can also press Ctrl/C to abort the execution of a debugger command. This is useful if, for example, the debugger is displaying a long stream of data.

Pressing Ctrl/C when the program is not running or when the debugger is not performing an operation has no effect.

If your program has a Ctrl/C AST (asynchronous system trap) service routine enabled, use the SET ABORT_KEY command to assign the debugger's abort function to another Ctrl/key sequence. To identify the abort key that is currently defined, enter the SHOW ABORT_KEY command.

Pressing Ctrl/Y from within a debugging session has the same effect as pressing Ctrl/Y during the execution of a program. Control is returned to the DCL command interpreter ($ prompt).

1.5 Pausing and Resuming a Debugging Session

The debugger SPAWN and ATTACH commands enable you to interrupt a debugging session from the debugger prompt, enter DCL commands, and return to the debugger prompt. These commands function essentially like the DCL commands SPAWN and ATTACH:

• Use the debugger SPAWN command to create a subprocess.
• Use the debugger ATTACH command to attach to an existing process or subprocess.

You can enter the SPAWN command with or without specifying a DCL command as a parameter. If you specify a DCL command, it is executed in a subprocess (if the DCL command invokes a utility, that utility is invoked in a subprocess). Control returns to the debugging session when the DCL command terminates (or when you exit the utility). The following example shows spawning the DCL command DIRECTORY:

DBG> SPAWN DIR [JONES.PROJECT2]*.FOR . . . Control returned to process JONES_1 DBG>

The next example shows spawning the DCL command MAIL, which invokes the Mail utility:

DBG> SPAWN MAIL MAIL> READ/NEW . . . MAIL> EXIT Control returned to process JONES_1 DBG>

If you enter the SPAWN command without specifying a parameter, a subprocess is created, and you can then enter DCL commands. Either logging out of the subprocess or attaching to the parent process (with the DCL command ATTACH) returns you to the debugging session. For example:

DBG> SPAWN $ RUN PROG2 . . . $ ATTACH JONES_1 Control returned to process JONES_1 DBG>

If you plan to go back and forth several times between your debugging session and a spawned subprocess (which might be another debugging session), use the debugger ATTACH command to attach to that subprocess. Use the DCL command ATTACH to return to the parent process. Because you do not create a new subprocess every time you leave the debugger, you use system resources more efficiently.

If you are running two debugging sessions simultaneously, you can define a new debugger prompt for one of the sessions with the SET PROMPT command. This helps you differentiate the sessions.

1.6 Starting the Debugger by Running a Program

You can bring your program under control of the non-kept debugger in one step by entering the DCL command RUN filespec.

Note that when running the non-kept debugger, you cannot use the debugger RERUN or RUN features explained in Section 1.3.3 and Section 1.3.4, respectively. To rerun the same program or run another program under debugger control, you must first exit the debugger and start it again.

To start the non-kept debugger by running a program:

1. Verify that you have compiled and linked the program as explained in Section 1.2.1 and Section 1.2.2 and that you have established the proper debugging configuration as explained in Section 1.9.
2. Enter the DCL command RUN filespec to start the debugger.

For example:

$ RUN FORMS Debugger Banner and Version Number Language: C, Module: FORMS DBG>

Upon startup, the debugger displays its banner, executes any user-defined initialization file, sets the language-dependent parameters to the source language of the main program, suspends execution at the start of the main program, and prompts for commands.

For more information about startup conditions, see Section 1.2.3 and Section 1.3.1.

1.7 Starting the Debugger After Interrupting a Running Program

You can bring a program that is executing freely under debugger control. This is useful if you suspect that the program might be in an infinite loop or if you see erroneous output.

To bring your program under debugger control:

1. Verify that you have compiled and linked the program as explained in Section 1.2 and that you have established the proper debugging configuration as explained in Section 1.9.
2. Enter the DCL command RUN/NODEBUG filespec to execute the program without invoking the debugger.
3. Press Ctrl/Y to interrupt the executing program. Control passes to the DCL command interpreter.
4. Enter the DCL command DEBUG. This invokes the non-kept debugger.

For example:

$ RUN/NODEBUG FORMS . . . [Ctrl/Y] Interrupt $ DEBUG Debugger Banner and Version Number Language: C, Module: FORMS DBG>

Upon startup, the debugger displays its banner, executes any user-defined initialization file, sets the language-dependent parameters to the source language of the module where execution was interrupted, and prompts for commands.

Usually you will not know where execution was interrupted. Enter the SHOW CALLS command to determine where execution is paused and to display the sequence of routine calls on the call stack (the SHOW CALLS command is described in Section 2.3.3).

Note that when running the non-kept debugger, you cannot use the debugger RERUN or RUN features explained in Section 1.3.3 and Section 1.3.4, respectively. To rerun the same program or run another program under debugger control, you must first exit the debugger and start it again.

For more information about startup conditions, see Section 1.2.3 and Section 1.3.1.

1.8 Ending a Debugging Session

To end a debugging session in an orderly manner and return to DCL level, enter EXIT or QUIT or press Ctrl/Z. For example:

DBG> EXIT $

The QUIT command starts the debugger exit handlers to close log files, restores the screen and keypad states, and so on.

The EXIT command and Ctrl/Z function identically. They perform the same functions as the QUIT command, and additionally execute any exit handlers that are declared in your program.

1.9 Establishing a Multiprocess Debugging Configuration

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 configuration depends on the current definition of the logical name DBG$PROCESS. Before starting the debugger, enter the DCL command SHOW LOGICAL DBG$PROCESS to determine the definition of DBG$PROCESS:

• If you are debugging a program that runs in only one process, DBG$PROCESS should be either undefined, as in the following example, or should have the value DEFAULT:

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

  
  By default, DBG$PROCESS is undefined. This is appropriate for debugging a program that runs in only one process (the typical case).

• If you are debugging a program that runs in more than one process, DBG$PROCESS should have the value MULTIPROCESS.
• 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

For more information about multiprocess debugging, see Chapter 15.

1.10 Debugging a Program on a Workstation Running DECwindows Motif

If you are at a workstation running DECwindows Motif, by default the debugger starts up in the DECwindows Motif interface, which is displayed on the workstation specified by the DECwindows Motif applicationwide logical name DECW$DISPLAY.

The logical name DBG$DECW$DISPLAY enables you to override the default to display the debugger's command interface in a DECterm window, along with any program input/output (I/O).

To display the debugger's command interface in a DECterm window:

1. Enter the following definition in the DECterm window from which you plan to start the debugger:

   $ DEFINE/JOB DBG$DECW$DISPLAY " "

   
   You can specify one or more space characters between the quotation marks. It is recommended that you use a job definition for the logical name. If you use a process definition, it must not have the CONFINE attribute.

2. Start the debugger in the usual way from that DECterm window (see Section 1.3.1). The debugger's command interface is displayed in the same window.

For example:

$ DEFINE/JOB DBG$DECW$DISPLAY " " $ DEBUG/KEEP Debugger Banner and Version Number DBG>

You can now bring your program under debugger control as explained in Section 1.3.1. For more information about the logical names DBG$DECW$DISPLAY and DECW$DISPLAY, see Section 9.7.3.

On a workstation running DECwindows Motif, you can also run the client/server configuration of the OpenVMS debugger. See Section 9.8 for details.

1.11 Debugging a Program from a PC Running the Debug Client

The OpenVMS Debugger Version 7.2 features a client/server interface that allows you to debug programs running on OpenVMS on a VAX or Alpha CPU from a PC debug client interface running:

• Microsoft Windows 95 (Intel)
• Microsoft Windows NT Version 3.51 or greater (Intel or Alpha)

The OpenVMS client/server configuration allows the following:

• Remote access to OpenVMS Debug servers from other OpenVMS systems or from PCs running Windows 95 or Windows NT Version 3.51 or later
• Client access to multiple servers, each running on the same or different OpenVMS nodes
• Multiple clients on different nodes to simultaneously connect to the same server for teaching or team debugging
• Debugging of multitier client/server applications that are distributed among several mixed-platform systems

The client and server communicate using Desktop Common Environment/Remote Procedure Calls (DCE/RPC) over one of the following transports:

• TCP/IP
• UDP
• DECnet

To invoke the server on an OpenVMS node, enter the following command:

$ DEBUG/SERVER

The server displays its network binding strings. You must specify one of these strings when you connect a DECwindows Motif or Microsoft Windows client to this server. For example:

$ DEBUG/SERVER %DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: YES %DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.138[1034] %DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:19.10[RPC224002690001] %DEBUG-I-WATCH: Network Binding: ncadg_ip_udp:16.32.16.138[1045] %DEBUG-I-AWAIT: Ready for client connection...

In the client's Server Connection dialog box, enter the type of network protocol (TCP/IP, DECnet, or UDP) and the corresponding network binding string (see Section 9.8.4).

For more information about using the debug client interface, see Chapter 11.

1.12 Debugging Detached Processes That Run with No CLI

The design and implementation of the debugger's DECwindows Motif interface requires that the process being debugged have a command line interpreter (CLI). To debug a detached process (such as a print symbiont) that does not have a CLI, you must use the character-cell (screen mode) interface to the debugger.

To do so, direct DBG$INPUT, DBG$OUTPUT and DBG$ERROR to a terminal port that is not logged in. This allows the image to be debugged with the standard character-cell interface on that terminal.

For example:

$ DEFINE/TABLE=GROUP DBG$INPUT TTA3: $ DEFINE/TABLE=GROUP DBG$OUTPUT TTA3: $ DEFINE/TABLE=GROUP DBG$ERROR TTA3: $ START/QUEUE SYS$PRINT /PROCESSOR=dev:[dir]test_program [Debugger starts up on logged-out terminal TTA3:]

1.13 Debugger Command Summary

The following sections list all the debugger commands and any related DCL commands in functional groupings, along with brief descriptions. During a debugging session, you can get online help on all debugger commands and their qualifiers by typing HELP at the debugger prompt (see Section 2.1).

1.13.1 Starting and Ending a Debugging Session

The following commands start the debugger, bring a program under debugger control, and interrupt and end a debugging session. Except where the DCL commands RUN and DEBUG are indicated specifically, all commands are debugger commands.

$DEBUG/KEEP	(DCL) Starts the kept debugger.
$RUN SYS$SHARE:DEBUGSHR.EXE	(DCL) Starts the kept debugger.
$DEBUG/SERVER	(DCL) Starts the debug server.
$DEBUG/CLIENT	(DCL) Starts the debug client.
$RUN SYS$SHARE:DEBUGUISHR.EXE	(DCL) Starts the debug client.
RUN filespec	Brings a program under debugger control.
RERUN	Reruns the program currently under debugger control.
$RUN program-image	(DCL) If the specified image was linked using LINK/DEBUG, starts the debugger and also brings the image under debugger control. When you start the debugger in this manner, you cannot then use the debugger RUN or RERUN commands. You can use the /[NO]DEBUG qualifiers with the RUN command to control whether the debugger is started when the program is executed.
EXIT, Ctrl/Z	Ends a debugging session, executing all exit handlers.
QUIT	Ends a debugging session without executing any exit handlers declared in the program.
Ctrl/C	Aborts program execution or a debugger command without interrupting the debugging session.
(SET,SHOW) ABORT_KEY	(Assigns, identifies) the default Ctrl/C abort function to another Ctrl/key sequence, identifies the Ctrl/key sequence currently defined for the abort function.
Ctrl/Y $DEBUG	(DCL) Interrupts a program that is running without debugger control and starts the debugger.
ATTACH	Passes control of your terminal from the current process to another process.
SPAWN	Creates a subprocess, which enables you to execute DCL commands without ending a debugging session or losing your debugging context.

1.13.2 Controlling and Monitoring Program Execution

The following commands control and monitor program execution:

GO	Starts or resumes program execution.
STEP	Executes the program up to the next line, instruction, or specified instruction.
(SET,SHOW) STEP	(Establishes, displays) the default qualifiers for the STEP command.
(SET,SHOW,CANCEL) BREAK	(Sets, displays, cancels) breakpoints.
(ACTIVATE,DEACTIVATE) BREAK	(Activates, deactivates) previously set breakpoints.
(SET,SHOW,CANCEL) TRACE	(Sets, displays, cancels) tracepoints.
(ACTIVATE,DEACTIVATE) TRACE	(Activates, deactivates) previously set tracepoints.
(SET,SHOW,CANCEL) WATCH	(Sets, displays, cancels) watchpoints.
(ACTIVATE,DEACTIVATE) WATCH	(Activates, deactivates) previously set watchpoints.
SHOW CALLS	Identifies the currently active routine calls.
SHOW STACK	Gives additional information about the currently active routine calls.
CALL	Calls a routine.

	privacy and legal statement
4538PRO_002.HTML