 |
OpenVMS Debugger Manual
CANCEL TRACE
Cancels a tracepoint.
Format
CANCEL TRACE [address-expression[,...]]
Parameters
address-expression
Specifies a tracepoint to be canceled. Do not use the asterisk (*)
wildcard character. Instead, use the /ALL qualifier. Do not specify an
address expression when using any qualifiers except /EVENT,
/PREDEFINED, or /USER.
Qualifiers
/ACTIVATING
Cancels the effect of a previous SET TRACE/ACTIVATING command.
/ALL
By default, cancels all user-defined tracepoints. When used with
/PREDEFINED, it cancels all predefined tracepoints but no user-defined
tracepoints. To cancel all tracepoints, use /ALL/USER/PREDEFINED.
/BRANCH
Cancels the effect of a previous SET TRACE/BRANCH command.
/CALL
Cancels the effect of a previous SET TRACE/CALL command.
/EVENT=event-name
Cancels the effect of a previous SET TRACE/EVENT=event-name
command. Specify the event name (and address expression, if any)
exactly as specified with the SET TRACE/EVENT command. To identify the
current event facility and the associated event names, use the SHOW
EVENT_FACILITY command.
/EXCEPTION
Cancels the effect of a previous SET TRACE/EXCEPTION command.
/INSTRUCTION
Cancels the effect of a previous SET TRACE/INSTRUCTION command.
/LINE
Cancels the effect of a previous SET TRACE/LINE command.
/PREDEFINED
Cancels a specified predefined tracepoint without affecting any
user-defined tracepoints. When used with /ALL, it cancels all
predefined tracepoints.
/TERMINATING
Cancels the effect of a previous SET TRACE/TERMINATING command.
/USER
Cancels a specified user-defined tracepoint without affecting any
predefined tracepoints. This is the default unless you specify
/PREDEFINED. To cancel all user-defined tracepoints, use /ALL.
/VECTOR_INSTRUCTION
(VAX only) Cancels the effect of a previous SET
TRACE/VECTOR_INSTRUCTION command.
Description
Tracepoints can be user defined or predefined. User-defined tracepoints
are explicitly set with the SET TRACE command. Predefined tracepoints,
which depend on the type of program you are debugging (for example, Ada
or multiprocess), are established automatically when you start the
debugger. Use the SHOW TRACE command to identify all tracepoints that
are currently set. Any predefined tracepoints are identified as such.
User-defined and predefined tracepoints are set and canceled
independently. For example, a location or event can have both a
user-defined and a predefined tracepoint. Canceling the user-defined
tracepoint does not affect the predefined tracepoint, and conversely.
To cancel only user-defined tracepoints, do not specify /PREDEFINED
with the CANCEL TRACE command (the default is /USER). To cancel only
predefined tracepoints, specify /PREDEFINED but not /USER. To cancel
both user-defined and predefined tracepoints, use CANCEL
TRACE/ALL/USER/PREDEFINED.
In general, the effect of CANCEL TRACE is symmetrical with that of SET
TRACE (even though SET TRACE is used only with user-defined
tracepoints). Thus, to cancel a tracepoint that was established at a
specific location, specify that same location (address expression) with
CANCEL TRACE. To cancel tracepoints that were established on a class of
instructions or events, specify the class of instructions or events
with the corresponding qualifier (/LINE, /BRANCH, /ACTIVATING, /EVENT=,
and so on). For more information, see the qualifier descriptions.
To cause the debugger to temporarily ignore a tracepoint, but retain
definition of the tracepoint, use the command DEACTIVATE TRACE. You can
later activate the tracepoint (with ACTIVATE TRACE).
Related commands:
(ACTIVATE,DEACTIVATE,SET,SHOW) TRACE
CANCEL ALL
(SET,SHOW,CANCEL) BREAK
(SET,SHOW) EVENT_FACILITY
Examples
| #1 |
DBG> CANCEL TRACE MAIN\LOOP+10
|
This command cancels the user-defined tracepoint at the location
MAIN\LOOP+10.
This command cancels all user-defined tracepoints.
| #3 |
all> CANCEL TRACE/TERMINATING
|
This command cancels a previous SET TRACE/TERMINATING command. As a
result, a user-defined tracepoint is not triggered when a process does
an image exit.
| #4 |
DBG> CANCEL TRACE/EVENT=RUN %TASK 3
|
This command cancels the tracepoint that was set to trigger when task 3
(task ID = 3) entered the RUN state.
CANCEL TYPE/OVERRIDE
Cancels the override type established by a previous SET TYPE/OVERRIDE
command.
Format
CANCEL TYPE/OVERRIDE
Description
The CANCEL TYPE/OVERRIDE command sets the current override type to
"none." As a result, a program location associated with a
compiler-generated type is interpreted according to that type.
Related commands:
DEPOSIT
EXAMINE
(SET,SHOW) EVENT_FACILITY
(SET,SHOW) TYPE/OVERRIDE
Example
|
DBG> CANCEL TYPE/OVERRIDE
|
This command cancels the effect of a previous SET TYPE/OVERRIDE command.
CANCEL WATCH
Cancels a watchpoint.
Format
CANCEL WATCH [address-expression[,...]]
Parameters
address-expression
Specifies a watchpoint to be canceled. With high-level languages, this
is typically the name of a variable. Do not use the asterisk (*)
wildcard character. Instead, use the /ALL qualifier. Do not specify an
address expression with /ALL.
Qualifiers
/ALL
Cancels all watchpoints.
Description
The effect of the CANCEL WATCH command is symmetrical with the effect
of the SET WATCH command. To cancel a watchpoint that was established
at a specific location with the SET WATCH command, specify that same
location with CANCEL WATCH. Thus, to cancel a watchpoint that was set
on an entire aggregate, specify the aggregate in the CANCEL WATCH
command; to cancel a watchpoint that was set on one element of an
aggregate, specify that element in the CANCEL WATCH command.
The CANCEL ALL command also cancels all watchpoints.
To cause the debugger to temporarily ignore a watchpoint, but not
delete the definition of the watchpoint, use the command DEACTIVATE
WATCH. You can later activate the watchpoint (with ACTIVATE WATCH).
Related commands:
(ACTIVATE,DEACTIVATE,SET,SHOW) WATCH
CANCEL ALL
(SET,SHOW,CANCEL) BREAK
(SET,SHOW,CANCEL) TRACE
Examples
| #1 |
DBG> CANCEL WATCH SUB2\TOTAL
|
This command cancels the watchpoint at variable TOTAL in module SUB2.
This command cancels all watchpoints you have set.
CANCEL WINDOW
Permanently deletes a screen window definition.
Note
This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to
the debugger.
|
Format
CANCEL WINDOW [window-name[,...]]
Parameters
window-name
Specifies the name of a screen window definition to be canceled. Do not
use the asterisk (*) wildcard character. Instead, use the /ALL
qualifier. Do not specify a window definition name with /ALL.
Qualifiers
/ALL
Cancels all predefined and user-defined window definitions.
Description
When a window definition is canceled, you can no longer use its name in
a DISPLAY command. The CANCEL WINDOW command does not affect any
displays.
Related commands:
(SHOW,CANCEL) DISPLAY
(SET,SHOW) WATCH
Example
|
DBG> CANCEL WINDOW MIDDLE
|
This command permanently deletes the screen window definition MIDDLE.
CONNECT
(Kept debugger only.) Interrupts an image that is running without
debugger control in another process and brings that process under
debugger control. When used without a parameter, CONNECT brings any
spawned process that is waiting to connect to the debugger under
debugger control.
On Alpha systems, the debugger command CONNECT can also be used to
bring a target system running the Alpha operating system under the
control of the OpenVMS Alpha System-Code Debugger. The OpenVMS Alpha
System-Code Debugger is a kernel debugger that you activate through the
OpenVMS Debugger.
If you are using the CONNECT command to debug the Alpha operating
system, you must complete the instructions described in the System Code
Debugger chapter of the OpenVMS Alpha System Analysis Tools Manual before you issue the command.
(These instructions include the creation of an Alpha device driver and
the setup commands activating the OpenVMS Alpha System-Code Debugger.)
You must also have started the OpenVMS Debugger with the DCL command
DEBUG/KEEP.
Format
CONNECT [process-spec]
CONNECT %NODE_NAME node-name
Parameters
process-spec
Specifies a process in which an image to be interrupted is running. The
process must be in the same OpenVMS job as the process in which the
debugger was started. Use any of the following forms:
|
[%PROCESS_NAME]
proc-name
|
The OpenVMS process name, if that name contains no space or lowercase
characters. The process name can include the asterisk (*) wildcard
character.
|
|
[%PROCESS_NAME] "
proc-name"
|
The OpenVMS process name, if that name contains space or lowercase
characters. You can also use apostrophes (') instead of quotation marks
(").
|
|
%PROCESS_PID
proc-id
|
The OpenVMS process identifier (PID, a hexadecimal number).
|
node-name
(Alpha only) When you are debugging the Alpha operating system,
specifies the node name of the machine to which you are connecting (the
target machine running the Alpha operating system).
Qualifiers
/PASSWORD="password"
(Alpha only) When you are debugging the Alpha operating system,
specifies the password for the machine to which you are connecting (the
target machine running the Alpha operating system). If a password has
not been established for that machine, this qualifier can be omitted.
/IMAGE_PATH="image-path"
(Alpha only) When you are debugging the Alpha operating system,
specifies the image-path for the machine from which you are connecting
(the host machine running the debugger). The image-path is a logical
name that points to the location of system images. The default logical
name is DBGHK$IMAGE_PATH:.
Description
(Kept debugger only.) When you specify a process, the CONNECT command
enables you to interrupt an image that is running without debugger
control in that process and bring the process under debugger control.
The command is useful if, for example, you run a debuggable image with
the DCL command RUN/NODEBUG, or if your program issues a LIB$SPAWN
Run-Time Library call that does not start the debugger. You cannot
connect to a process created through a $CREPRC system service call.
Depending on the version of the debugger you are running on your
system, you may be restricted to connection with processes you created,
or you may be able to connect to processes created by any member of
your user identification code (UIC) group. (In some cases, you may have
to set the SYSGEN SECURITY_POLICY parameter to 8 before you create the
process.) Table DEBUG-1 lists the restrictions that apply to specific
versions of the debugger.
If debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG,
DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL)
exist, they must translate to the same definitions in both the debugger
and the target process.
The image modules must have been compiled and linked with the /DEBUG
qualifier. The image cannot have been linked with the /NOTRACEBACK
qualifier.
When the process is brought under debugger control, execution of the
image is suspended at the point at which it was interrupted.
When you do not specify a process, the CONNECT command brings any
processes that are waiting to connect to your debugging session under
debugger control. If no process is waiting, you can press Ctrl/C to
abort the CONNECT command.
By default, a tracepoint is triggered when a process is brought under
debugger control. This predefined tracepoint is equivalent to that
resulting from entering the SET TRACE/ACTIVATING command. The process
is then known to the debugger and can be identified in a SHOW PROCESS
display.
You cannot use the CONNECT command to connect to a subprocess of a
process running under debugger control. Use the SET PROCESS command to
connect to such a subprocess.
Using the CONNECT Command to Debug the Alpha Operating System (Alpha only)
You can use the CONNECT command to debug Alpha operating system code
with the OpenVMS Alpha System-Code Debugger (SCD). Typically, you issue
this command from a timesharing (host) Alpha machine (running SCD), and
you connect to a standalone (target) Alpha machine (running the Alpha
operating system). Communication between the two machines occurs over
the Ethernet network.
Note
The port used for SCD on the target machine is not configured at all,
and cannot be used for any other purpose, such as DECnet, LAT, user
applications, and so on. Therefore, to be able to use DECnet or to be
in a cluster while using SCD, you must have another Ethernet port for
that traffic.
|
In some cases, you may find that you need to use the alternative
Delta/XDelta Debugger to debug operating system code. These cases
include:
- When you have access to only one Alpha machine for debugging
- When you are debugging portions of code that generate Ethernet
traffic on the target system and have only one ethernet port.
Generally, however, the OpenVMS Alpha System-Code Debugger is preferred
for debugging Alpha operating system code. For complete information on
using this debugger, see the OpenVMS Alpha System Analysis Tools Manual.
Related commands:
DISCONNECT
Ctrl/Y
(SET,SHOW,CANCEL) TRACE
Examples
This command brings under debugger control any processes that are
waiting to be connected to the debugger.
| #2 |
DBG_1> CONNECT JONES_3
|
This command interrupts the image running in process JONES_3 and brings
the process under debugger control. Process JONES_3 must be in the same
UIC group as the process in which the debugger was started. Also, the
image must not have been linked with the /NOTRACEBACK qualifier.
| #3 |
DBG> CONNECT %NODE_NAME SCDTST /PASSWORD="eager_beaver"
%DEBUG-I-NOLOCALS, image does not contain local symbols
DBG>
|
On Alpha systems, this CONNECT command brings the target system running
Alpha operating-system code under debugger control. This example
specifies that the Alpha target machine (running the operating system)
has a node name of SCDTST and a password of eager_beaver. The Alpha
host machine (running the debugger) has the default DBGHK$IMAGE_PATH:
image-path.
Ctrl/C
When entered from within a debugging session, Ctrl/C aborts the
execution of a debugger command or interrupts program execution without
interrupting the debugging session.
Note
Do not use Ctrl/Y from within a debugging session.
|
Format
[Ctrl/C]
Description
Pressing Ctrl/C enables you to abort the execution of a debugger
command or to interrupt program execution without interrupting the
debugging session. This is useful when, for example, the program is
executing an infinite loop that does not have a breakpoint, or you want
to abort a debugger command that takes a long time to complete. The
debugger prompt is then displayed, so that you can enter debugger
commands.
If your program already has a Ctrl/C AST service routine enabled, use
the SET ABORT_KEY command to assign the debugger's abort function to
another Ctrl-key sequence. Note, however, that many Ctrl-key sequences
have predefined functions, and the SET ABORT_KEY command enables you to
override such definitions (see the OpenVMS User's Manual).
Some of the Ctrl-key characters not used by the operating system are G,
K, N, and P.
If your program does not have a Ctrl/C AST service routine
enabled and you assign the debugger's abort function to another
Ctrl-key sequence, then Ctrl/C behaves like Ctrl/Y---that is, it
interrupts the debugging session and returns you to DCL level.
Do not use Ctrl/Y from within a debugging session. Instead, use either
Ctrl/C or an equivalent Ctrl-key sequence established with the SET
ABORT_KEY command.
You can use the SPAWN and ATTACH commands to leave and return to a
debugging session without losing the debugging context.
Related commands:
ATTACH
Ctrl/Y
(SET,SHOW) ABORT_KEY
SPAWN
Example
|
DBG> GO
...
[Ctrl/C]
DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010
1000: 0
1004: 0
1008: 0
1012: 0
1016: 0
[Ctrl/C]
%DEBUG-W-ABORTED, command aborted by user request
DBG>
|
This example shows how to use Ctrl/C to interrupt program execution and
then to abort the execution of a debugger command.
Ctrl/W
Ctrl/W refreshes the screen in screen mode (like DISPLAY/REFRESH).
Format
[Ctrl/W]
Description
For more information about Ctrl/W, see the /REFRESH qualifier to the
DISPLAY command.
Ctrl/Y
When entered from DCL level, Ctrl/Y interrupts an image that is running
without debugger control, enabling you then to start the debugger with
the DCL command DEBUG.
Notes
Do not use Ctrl/Y from within a debugging session. Instead, use Ctrl/C
or an equivalent abort-key sequence established with the SET ABORT_KEY
command.
When you start the debugger with the Ctrl/Y--DEBUG sequence, you cannot
then use the debugger RUN or RERUN commands.
|
Format
[Ctrl/Y]
Description
Pressing Ctrl/Y at DCL level enables you to interrupt an image that is
running without debugger control, so that you can then start the
debugger with the DCL command DEBUG.
You can bring an image under debugger control only if, as a minimum,
that image was linked with the /TRACEBACK qualifier (/TRACEBACK is the
default for the LINK command).
When you press Ctrl/Y to interrupt the image's execution, control is
passed to DCL. If you then enter the DCL command DEBUG, the interrupted
image is brought under control of the debugger. The debugger sets its
language-dependent parameters to the source language of the module in
which execution was interrupted and displays its prompt. You can then
determine where execution was suspended by entering a SHOW CALLS
command.
The Ctrl/Y--DEBUG sequence is not supported in the kept debugger
configuration.
The Ctrl/Y--DEBUG sequence is not supported in the Compaq DECwindows Motif for OpenVMS user
interface to the debugger. Instead, use the STOP button.
Within a debugging session, you can use the CONNECT command to connect
an image that is running without debugger control in another process
(of the same job) to that debugging session.
Related commands:
CONNECT
Ctrl/C
DEBUG (DCL command)
RUN (DCL command)
Examples
| #1 |
$ RUN/NODEBUG TEST_B
...
[Ctrl/Y]
Interrupt
$ DEBUG
Debugger Banner and Version Number
Language: ADA, Module: SWAP
DBG>
|
In this example, the RUN/NODEBUG command executes the image TEST_B
without debugger control. Execution is interrupted with Ctrl/Y. The
DEBUG command then causes the debugger to be started. The debugger
displays its banner, sets the language-dependent parameters to the
language (Ada, in this case) of the module (SWAP) in which execution
was interrupted, and displays the prompt.
| #2 |
$ RUN/NODEBUG PROG2
...
[Ctrl/Y]
Interrupt
$ DEBUG
Debugger Banner and Version Number
Language: FORTRAN, Module: SUB4
predefined trace on activation at SUB4\%LINE 12 in %PROCESS_NUMBER 1
DBG>
|
In this example, the DEFINE/JOB command establishes a multiprocess
debugging configuration. The RUN/NODEBUG command executes the image
PROG2 without debugger control. The Ctrl/Y--DEBUG sequence interrupts
execution and starts the debugger. The banner indicates that a new
debugging session has been started. The activation tracepoint indicates
where execution was interrupted when the debugger took control of the
process.
|
