 |
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.
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 HP 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.
On Integrity servers, the debugger command CONNECT can also be used to
bring a target system running the Integrity server operating system
under the control of the OpenVMS Integrity server System-Code Debugger.
The OpenVMS Integrity server 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 or Integrity servers only) When you are debugging an Alpha or
Integrity server operating system, specifies the node name of the
machine to which you are connecting (the target machine running the
Alpha or Integrity server operating system).
Qualifiers
/PASSWORD="password"
(Alpha or Integrity servers only) When you are debugging an Alpha or
Integrity server operating system, specifies the password for the
machine to which you are connecting (the target machine running the
Alpha or Integrity server operating system). If a password has not been
established for that machine, this qualifier can be omitted.
/IMAGE_PATH="image-path"
(Alpha or Integrity servers only) When you are debugging an 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 can connect
to a process created through a $CREPRC system service call only if you
specify LOGINOUT.EXE as the executable image.
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.)
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 code in the image must be compiled with the /DEBUG qualifier and
the image must be linked with either /DEBUG or /DSF. The image must not
be 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.
Related commands:
DISCONNECT
Ctrl/Y
(SET,SHOW,CANCEL) TRACE
Using the CONNECT Command to Debug the OpenVMS Operating System (Integrity servers and Alpha only)
You can use the CONNECT command to debug Alpha or Integrity server
operating system code with the OpenVMS System Code Debugger (SCD). This
capability requires two systems, one called the host and the other
called the target. The host and target must be running the same
operating system (Alpha or Integrity servers). The host is configured
as a standard OpenVMS system, from which you run the debugger using
DEBUG/KEEP, then enter the CONNECT command. The target is a standalone
system that is booted in a special way that enables SCD. Communication
between the host and the target occurs over the Ethernet network.
For complete information on using the OpenVMS System Code Debugger, see
the OpenVMS Alpha System Analysis Tools Manual.
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>
|
This CONNECT command brings the target system running the OpenVMS
operating system under debugger control. This example specifies that
the target system has a node name of SCDTST and a password of
eager_beaver.
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.
Note
Pressing Ctrl/C to interrupt a program running under debugger control
works only once. Thereafter, the Ctrl/C interrupt is ignored. The same
is true when using the DECwindows STOP button; the action is
acknowledged only the first time the button is pressed.
|
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 HP 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.
|
