Updated: 11 December 1998

OpenVMS Debugger Manual

Permanently deletes a screen window definition.

Note This command is not available in the DECwindows Motif 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.

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.

This command applies either to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS) or the default debugging configuration in which you started the debugger with the DCL command DEBUG/KEEP.

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 Writing OpenVMS Alpha Device Drivers in C 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 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. By default, the logical definition is DBGHK$IMAGE_PATH:.

Description

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

Debugger logicals (DEBUG, DEBUGSHR, DEBUGUISHR, DBGTBKMSG, DBG$PROCESS, DBG$HELP, DBG$UIHELP, DEBUGAPPCLASS, and VMSDEBUGUIL) must translate to the same definitions for both debugger and 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 Writing OpenVMS Alpha Device Drivers in C.

Related commands:

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

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 testing_node /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 testing_node and a password of eager_beaver. The Alpha host machine (running the debugger) has the default DBGHK$IMAGE_PATH: image-path.

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.

After a Ctrl/C interruption, any processes of a multiprocess program that were executing images are in the "interrupted" state.

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). Also, you can reference all of the image's symbols while debugging only if its modules were compiled and linked with the /DEBUG qualifier (in that case, you would use the DCL command RUN/NODEBUG to execute the image without the debugger).

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 (and a SHOW PROCESS command, in the case of a multiprocess program).

Other details about the effect of a Ctrl/Y--DEBUG sequence depend on the debugging configuration (default or multiprocess), which is determined by the current definition of the logical name DBG$PROCESS in the process where the interrupted image was executing.

The Ctrl/Y--DEBUG sequence is not supported in the kept debugger configuration.

The Ctrl/Y--DEBUG sequence is not supported in the DECwindows Motif interface to the debugger. Instead, use the STOP button.

Default Debugging Configuration

The default debugging configuration is achieved when DBG$PROCESS is either undefined or has the value DEFAULT. In this case a new default debugging session is started every time you start the debugger with the Ctrl/Y--DEBUG sequence (see Example 1).

Multiprocess Debugging Configuration

The multiprocess debugging configuration is achieved when DBG$PROCESS has the job definition MULTIPROCESS. In this case, the effect of a Ctrl/Y--DEBUG sequence is as follows:

• If a multiprocess debugging session does not already exist in the same job as the process running the interrupted image, a new multiprocess debugging session is created (see Example 2).
• If a multiprocess debugging session already exists in the same job, the interrupted image and its process come under control of that session. In this case the debugger does not display its banner.

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. This is the default debugging configuration, as indicated by the DBG> prompt.

$ DEFINE/JOB DBG$PROCESS MULTIPROCESS
$ 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_1>
      

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 process-specific prompt (DBG_1>) indicates that this is a multiprocess configuration and that execution is suspended in process 1, which is running PROG2. The activation tracepoint indicates where execution was interrupted when the debugger took control of the process.

Ctrl/Z ends a debugging session (like EXIT).

Format

[Ctrl/Z]

Description

For more information about Ctrl/Z, see the EXIT command.

Deactivates a breakpoint, which you can later activate.

Format

DEACTIVATE BREAK [address-expression[,...]]

Parameters

address-expression

Specifies a breakpoint to be deactivated. 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

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the value MULTIPROCESS). Deactivates a breakpoint established by a previous SET BREAK/ACTIVATING command.

/ALL

By default, deactivates all user-defined breakpoints. When used with /PREDEFINED, deactivates all predefined breakpoints but no user-defined breakpoints. To deactivate all breakpoints, use /ALL/USER/PREDEFINED.

/BRANCH

Deactivates a breakpoint established by a previous SET BREAK/BRANCH command.

/CALL

Deactivates a breakpoint established by a previous SET BREAK/CALL command.

/EVENT=event-name

Deactivates a breakpoint established by a previous SET BREAK/EVENT=event-name command. Specify the event name (and address expression, if any) exactly as specified with the SET BREAK/EVENT command.

To identify the current event facility and the associated event names, use the SHOW EVENT_FACILITY command.

/EXCEPTION

Deactivates a breakpoint established by a previous SET BREAK/EXCEPTION command.

/HANDLER

Deactivates a breakpoint established by a previous SET BREAK/HANDLER command.

/INSTRUCTION

Deactivates a breakpoint established by a previous SET BREAK/INSTRUCTION command.

/LINE

Deactivates a breakpoint established by a previous SET BREAK/LINE command.

/PREDEFINED

Deactivates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, deactivates all predefined breakpoints.

/SYSEMULATE

(Alpha only) Deactivates a breakpoint established by a previous SET BREAK/SYSEMULATE command.

/TERMINATING

Deactivates a breakpoint established by a previous SET BREAK/TERMINATING command.

/UNALIGNED_DATA

(Alpha only) Deactivates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command.

/USER

Deactivates a specified user-defined breakpoint. To deactivate all user-defined breakpoints, use the /ALL qualifier.

/VECTOR_INSTRUCTION

(VAX only) Deactivates a breakpoint established by a previous SET BREAK/VECTOR_INSTRUCTION command.

Description

User-defined breakpoints are activated when you set them with the SET BREAK command. Predefined breakpoints are activated by default. Use the DEACTIVATE BREAK command to deactivate one or more breakpoints.

If you deactivate a breakpoint, the debugger ignores the breakpoint during program execution. To activate a deactivated breakpoint, use the ACTIVATE BREAK command. You can activate and deactivate user-defined and predefined breakpoints separately. Activating and deactivating breakpoints enables you to run and rerun your program with or without breakpoints without having to cancel and then reset them. By default, the RERUN command saves the current state of all breakpoints (activated or deactivated).

To check if a breakpoint is deactivated, use the SHOW BREAK command.

Related commands:

• CANCEL ALL
• RERUN
• (SET,SHOW,CANCEL,ACTIVATE) BREAK
• (SET,SHOW) EVENT_FACILITY

Examples

DBG> DEACTIVATE BREAK MAIN\LOOP+10
      

This command deactivates the user-defined breakpoint set at the address expression MAIN\LOOP+10.

DBG> DEACTIVATE BREAK/ALL
      

This command deactivates all user-defined breakpoints.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4538PRO_042.HTML