HP OpenVMS Systems Documentation

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

1. Verify that you have compiled and linked the program as explained in Section 1.2.
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
%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 is interrupted, and prompts for commands.

To know where the execution is 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 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:

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. You should 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.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 Alpha from a PC debug client interface running:

• Microsoft Windows (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 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).

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:] 

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.

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.

The following commands control and monitor program execution:

The following commands examine and manipulate data:

The following commands control type selection and radix:

The following commands control symbol searches and symbolization:

The following commands control the display of source code:

The following commands control screen mode and screen displays:

The following commands control source editing from a debugging session: