HP OpenVMS systems documentation

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

DBG> CANCEL TRACE MAIN\LOOP+10
      

This command cancels the user-defined tracepoint at the location MAIN\LOOP+10.

DBG> CANCEL TRACE/ALL
      

This command cancels all user-defined tracepoints.

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.

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.

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.

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

DBG> CANCEL WATCH SUB2\TOTAL
      

This command cancels the watchpoint at variable TOTAL in module SUB2.

DBG> CANCEL WATCH/ALL
      

This command cancels all watchpoints you have set.

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.

(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 I64 systems, the debugger command CONNECT can also be used to bring a target system running the I64 operating system under the control of the OpenVMS I64 System-Code Debugger. The OpenVMS I64 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 HP OpenVMS 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 I64 only) When you are debugging an Alpha or I64 operating system, specifies the node name of the machine to which you are connecting (the target machine running the Alpha or I64 operating system).

Qualifiers

/PASSWORD="password"

(Alpha or I64 only) When you are debugging an Alpha or I64 operating system, specifies the password for the machine to which you are connecting (the target machine running the Alpha or I64 operating system). If a password has not been established for that machine, this qualifier can be omitted.

/IMAGE_PATH="image-path"

(Alpha or I64 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 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.

Table DEBUG-1 Restrictions on Process Creation, by Debugger Version Number

If you are running...	Then you can connect to a process started by...	With the SYSGEN Parameter?
VAX Version 5.5-2, earlier Alpha Version 6.0, earlier	You	No
VAX Version 6.0	You, Member of UIC Group	Yes
VAX Version 6.1, later Alpha Version 6.1, later	You, Member of UIC Group	No

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.

Related commands:

DISCONNECT
Ctrl/Y
(SET,SHOW,CANCEL) TRACE

Using the CONNECT Command to Debug the OpenVMS Operating System (Alpha and I64 only)

You can use the CONNECT command to debug Alpha or I64 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 I64). 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 HP OpenVMS System Analysis Tools Manual.

Examples

DBG_1> CONNECT
 
      

This command brings under debugger control any processes that are waiting to be connected to the debugger.

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.

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.

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

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

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

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