HP OpenVMS Debugger Manual

Contents

Index

1.3.2 When Your Program Completes Execution

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

%DEBUG-I-EXITSTATUS,is '%SYSTEM-S-NORMAL, 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).

1.3.3 Rerunning the Same Program from the Kept Debugger

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 %DEBUG-I-NOTATMAIN, Language: C, Module: FORMS %DEBUG-I-NOTATMAIN, 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 %DEBUG-I-NOTATMAIN, 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:

Verify that you have compiled and linked the program as explained in Section 1.2.1 and Section 1.2.2.
Enter the DCL command RUN filespec to start the debugger.

For example:

$ RUN FORMS Debugger Banner and Version Number %DEBUG-I-NOTATMAIN, 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 either 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:

Verify that you have compiled and linked the program as explained in Section 1.2.
Enter the DCL command RUN/NODEBUG filespec to execute the program without invoking the debugger.
Press Ctrl/Y to interrupt the executing program. Control passes to the DCL command interpreter.
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 %DEBUG-I-NOTATMAIN, 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).

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 Debugging a Program on a Workstation Running DECwindows Motif

If you are at a workstation running HP DECwindows Motif for OpenVMS, by default the debugger starts up in the HP DECwindows Motif for OpenVMS user interface, which is displayed on the workstation specified by the HP DECwindows Motif for OpenVMS 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:

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. You should use a job definition for the logical name. If you use a process definition, it must not have the CONFINE attribute.
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.8.3.

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

1.10 Debugging a Program from a PC Running the Debug Client

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

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

The client/server interface will be available for OpenVMS I64 systems in a future release.

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 Distributed Computing 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 HP DECwindows Motif for OpenVMS 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.9.4).

Note

Messages and program output appear by default in the window in which you start the server. You can redirect program output to another window as required.

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

1.11 Debugging Detached Processes That Run with No CLI

The design and implementation of the debugger's HP DECwindows Motif for OpenVMS user 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.12 Configuring Process Quotas for the Debugger

Each user needs a PRCLM quota sufficient to create an additional subprocess for the debugger, beyond the number of processes needed by the program.

BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. You may need to increase these quotas to account for the debugger subprocess as follows:

You should increase each user's ENQLM quota by at least the number of processes being debugged.
You might need to increase each user's PGFLQUOTA. If a user has an insufficient PGFLQUOTA, the debugger may fail to activate or may cause "virtual memory exceeded" errors during execution.
You might need to increase each user's BYTLM and FILLM quotas. The debugger requires sufficient BYTLM and FILLM quotas to open each image file being debugged, the corresponding source files, and the debugger input, output, and log files. To increase these quotas, you can run SYS$SYSTEM:AUTHORIZE.EXE to adjust parameters in SYSUAF.DAT.

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

1.13.3 Examining and Manipulating Data

The following commands examine and manipulate data:

EXAMINE Displays the value of a variable or the contents of a program location

SET MODE [NO]OPERANDS Controls whether the address and contents of the instruction operands are displayed when you examine an instruction

DEPOSIT Changes the value of a variable or the contents of a program location

DUMP Displays the contents of memory in a manner similar to the DCL command DUMP

EVALUATE Evaluates a language or address expression

MONITOR (Applies only to the debugger's HP DECwindows Motif for OpenVMS user interface) Displays the current value of a variable or language expression in the monitor view of the HP DECwindows Motif for OpenVMS user interface

Contents

Index

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

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

EXAMINE	Displays the value of a variable or the contents of a program location
SET MODE [NO]OPERANDS	Controls whether the address and contents of the instruction operands are displayed when you examine an instruction
DEPOSIT	Changes the value of a variable or the contents of a program location
DUMP	Displays the contents of memory in a manner similar to the DCL command DUMP
EVALUATE	Evaluates a language or address expression
MONITOR	(Applies only to the debugger's HP DECwindows Motif for OpenVMS user interface) Displays the current value of a variable or language expression in the monitor view of the HP DECwindows Motif for OpenVMS user interface