Invokes the OpenVMS Debugger.
For a complete description of the OpenVMS Debugger, see the VSI
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
1 – 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 VSI OpenVMS Debugger Manual.
On OpenVMS Integrity servers, 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.
2 – Qualifiers
2.1 /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.
2.2 /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.
2.3 /RESUME
/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.
2.4 /SERVER
/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[R]
Windows[R] 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.
3 – Examples
1.$ 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.
2.$ 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.
3.$ 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 Integrity server systems, start the Heap Analyzer within the
kept debugger:
4.$ debug/keep
DBG> run/heap 8queens
or, alternately:
5.$ 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 analyzer
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:
6.$ debug/keep
DBG> run/heap 8queens
7.$ 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.