Invokes the OpenVMS Debugger.

For a complete description of the OpenVMS Debugger, see the HP OpenVMS Debugger Manual.

To get help on debugger commands from DCL level, type the following command:

$ HELP/LIBRARY=SYS$HELP:DBG$HELP DEBUG

Format

DEBUG

Heap Analyzer

The Heap Analyzer provides a graphical representation of memory use in real time. This allows you to quickly identify inefficient memory usage in your application such as allocations that are made too often, memory blocks that are too large, fragmentation, or memory leaks.

For details on running the Heap Analyzer from within the debugger, see the HP OpenVMS Debugger Manual.

On OpenVMS I64, the standalone Heap Analyzer is started within the kept debugger using the START HEAP_ANALYZER command (see example).

On OpenVMS Alpha, the standalone Heap Analyzer is started within the kept debugger using the RUN/HEAP command.

On OpenVMS VAX, the standalone Heap Analyzer is started by entering the following commands:

$ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED $ RUN/NODEBUG program

Qualifiers

/CLIENT

Invokes the DEBUG client Motif interface. From the client, use the network binding string displayed by the server at startup to establish the connection. The first client to connect to the server is the primary client, and controls the number of secondary clients allowed to connect to the server.

/KEEP

Invokes the kept debugger. The kept debugger includes a Run/Rerun capability that allows you to debug an image multiple times or debug a series of distinct images without exiting the debugger.

Issuing the DEBUG/KEEP command is the only way to invoke the kept debugger.

/RESUME (default)

Reinvokes the non-kept debugger after a Ctrl/Y key sequence has interrupted the execution of a program you are debugging. (The interrupted program must not have been linked with a /NOTRACEBACK qualifier on the LINK command.)

If you issue the DEBUG/RESUME command without a previous Ctrl/Y key sequence, no action occurs.

/SERVER [=( [BINDING_INFO=filespec] [,PROTOCOLS=(protocol[,...])] )]

Invokes the DEBUG server. The DEBUG server allows up to 30 simultaneous connections from clients on the same or remote OpenVMS nodes, or from PC nodes running a supported Microsoft® Windows® platform.

(Optional) If specified, the BINDING_INFO keyword specifies that the server binding identification strings are to be written to filespec. If not specified, no file is created.

(Optional) If specified, the PROTOCOLS keyword specifies which network protocols should be enabled for connection to the DEBUG server. Only the specified protocols are enabled. If not specified, all protocols are enabled. The protocol argument can be one or more of the following keywords:

ALL
[NO]DECNET
[NO]TCP_IP
[NO]UDP

The first client to connect to the server is the primary client. A client that connects to the server after the primary client establishes the connection is a secondary client. The primary client controls the number of secondary clients allowed to connect to the server.

The server displays a series of RPC binding strings that identify the port numbers through which the client can connect to the server. The port number appears in square brackets ([]) at the end of the identification strings.

When connecting from the client, the simplest port identification string consists of the node name of the server followed by the port number in square brackets. The following are all valid binding identification strings:

NODNAM[1234]
NCACN_IP_TCP:16.32.16.25[1112]
16.32.16.25[1112]
NCACN_DNET_NSP:63.1004[RPC20A020DD0001]

Note You must hold the DBG$ENABLE_SERVER identifier in the rights database to be able to run the debug server. Exercise care when using the debug server. Once a debug server is running, anyone on the network has the ability to connect to the debug server.

Before granting the DBG$ENABLE_SERVER identifier, the system manager must create it by entering the command DEBUG/SERVER from an account with write access to the rights database. The system manager needs to do this only once. The system manager can then run the Authorize utility to grant the DBG$ENABLE_SERVER identifier to the user's account in the rights database.

Examples

$ FORTRAN/DEBUG/NOOPTIMIZE WIDGET
$ LINK/DEBUG WIDGET
$ RUN WIDGET
                [ Debugger Banner and Version ] 
 
%DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET 
DBG>
 
      

The FORTRAN and LINK commands both specify the /DEBUG qualifier to compile the program WIDGET.FOR with debugger symbol table information. Because the program has been compiled and linked with debug information, the debugger is automatically invoked by the image activator upon starting the program with the RUN command. No program code has yet been executed when the debugger is invoked.

$ FORTRAN/DEBUG/NOOPTIMIZE WIDGET
$ LINK/DEBUG WIDGET
$ RUN/NODEBUG WIDGET
  NAME: 
  NAME: 
  NAME:
^Y
$ DEBUG/RESUME
 
             [ Debugger Banner and Version ] 
 
  %DEBUG-I-INITIAL, language is FORTRAN, module set to WIDGET 
  DBG>
 
      

The FORTRAN and LINK commands both specify the /DEBUG qualifier to compile the program WIDGET.FOR with debugger symbol table information. The RUN command begins execution of the image WIDGET.EXE, which loops uncontrollably. Ctrl/Y interrupts the program, and the DEBUG/RESUME command gives control to the debugger.

$ CC/DEBUG/NOOPTIMIZE ECHOARGS
$ LINK/DEBUG ECHOARGS
$ ECHO == "$ sys$disk:[]echoargs.exe"
$ DEBUG/KEEP
                   [ Debugger Banner and Version ] 
 
DBG> RUN/COMMAND="ECHO"/ARGUMENTS="fa sol la mi"
%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 
   .
   .
   .
DBG> RERUN/ARGUMENTS="fee fii foo fum"
%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 
   .
   .
   .
DBG> RUN/ARGUMENTS="a b c" ECHOARGS
%DEBUG-I-INITIAL, language is C, module set to ECHOARGS 
%DEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 
 
      

The CC and LINK commands both specify the /DEBUG qualifier to compile the program ECHOARGS.C with debugger symbol table information.

The symbol definition command defines a foreign command for use during the debugging session.

The DEBUG/KEEP command invokes the kept debugger.

The first RUN command uses the /COMMAND qualifier to specify a foreign command to invoke the image file and the /ARGUMENTS qualifier to specify a string of arguments.

The RERUN command reinvokes the same image file and uses the /ARGUMENTS qualifier to specify a new string of arguments.

The second RUN command specifies a new image file and a new string of arguments.

On I64 systems, start the Heap Analyzer within the kept debugger:

$ debug/keep
DBG> run/heap 8queens
 
      

or, alternately:

$ debug/keep
DBG> run 8queens
 .
 .
 .
DBG> deactivate break/all
DBG> deactivate watch/all
DBG> deactivate trace/all
DBG> start heap_analyzer
DBG> activate break/all
DBG> activate watch/all
DBG> activate trace/all
 
      

Using this method, you must first deactivate all watchpoints, breakpoints, and tracepoints before starting the heap analzyer with the START HEAP_ANALYZER command. This procedure prevents a potential race condition from occurring. After starting the heap analyzer, re-activate the breakpoints, watchpoints, and trace points.

On Alpha systems, start the Heap Analyzer within the kept debugger:

$  debug/keep
DBG> run/heap 8queens
 
 
      

On VAX systems, start the heap analyzer as in the following PASCAL example:

$ PASCAL/DEBUG/NOOPTIMIZE 8QUEENS
$ LINK/DEBUG 8QUEENS
$ DEFINE/USER/NAME=CONFINE LIBRTL SYS$LIBRARY:LIBRTL_INSTRUMENTED
$ RUN/NODEBUG 8QUEENS
 
 
      

The PASCAL and LINK commands both specify the /DEBUG qualifier to compile the program 8QUEENS.PAS with debugger symbol table information.

The DEFINE command causes the Heap Analyzer to access a version of LIBRTL designed to collect memory allocation and deallocation information.

The RUN/NODEBUG command invokes the Heap Analyzer but not the Debugger.

$ DEBUG/SERVER=(PROTOCOLS=(TCP_IP,DECNET))
%DEBUG-I-SPEAK: TCP/IP: YES, DECnet: YES, UDP: NO 
%DEBUG-I-WATCH: Network Binding: ncacn_ip_tcp:16.32.16.25[1112] 
%DEBUG-I-WATCH: Network Binding: ncacn_dnet_nsp:63.1004[RPC20A020DD0001] 
%DEBUG-I-AWAIT: Ready for client connection... 
 
      

The DEBUG/SERVER command establishes a connection to the debug server, requesting network protocols TCP/IP and DECnet. Note that the binding strings are saved in file TEMP.TMP. You can use the TYPE command to display the contents of TEMP.TMP.