Document revision date: 30 March 2001

## OpenVMS Debugger Manual

Previous | Contents | Index

## Ctrl/Z

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

### Format

> `[Ctrl/Z]`

### Description

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

## DEACTIVATE BREAK

> 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

> 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

#1
    DBG> DEACTIVATE BREAK MAIN\LOOP+10

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

#2
    DBG> DEACTIVATE BREAK/ALL

> This command deactivates all user-defined breakpoints.

## DEACTIVATE TRACE

> Deactivates a tracepoint, which you can later activate.

### Format

> DEACTIVATE TRACE [address-expression[,...]]

### Parameters

> #### address-expression

> Specifies a tracepoint 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

> Deactivates a tracepoint established with a previous SET TRACE/ACTIVATING command.

> #### /ALL

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

> #### /BRANCH

> Deactivates a tracepoint established with a previous SET TRACE/BRANCH command.

> #### /CALL

> Deactivates a tracepoint established with a previous SET TRACE/CALL command.

> #### /EVENT=event-name

> Deactivates a tracepoint established with 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

> Deactivates a tracepoint established with a previous SET TRACE/EXCEPTION command.

> #### /INSTRUCTION

> Deactivates a tracepoint established with a previous SET TRACE/INSTRUCTION command.

> #### /LINE

> Deactivates a tracepoint established with a previous SET TRACE/LINE command.

> #### /PREDEFINED

> Deactivates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, it deactivates all predefined tracepoints.

> #### /TERMINATING

> Deactivates a tracepoint established with a previous SET TRACE/TERMINATING command.

> #### /USER

> Deactivates a specified user-defined tracepoint without affecting any predefined tracepoints. When used with /ALL, it deactivates all user-defined tracepoints. The /USER qualifier is the default unless you specify /PREDEFINED.

> #### /VECTOR_INSTRUCTION

> (VAX only) Deactivates a tracepoint established with a previous SET TRACE/VECTOR_INSTRUCTION command.

### Description

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

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

> To check if a tracepoint is deactivated, use the SHOW TRACE command.

> Related commands:

> > CANCEL ALL
> > RERUN
> > (SET,SHOW) EVENT_FACILITY
> > (SET,SHOW,CANCEL,ACTIVATE) TRACE

### Examples

#1
    DBG> DEACTIVATE TRACE MAIN\LOOP+10

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

#2
    DBG> DEACTIVATE TRACE/ALL

> This command deactivates all user-defined tracepoints.

## DEACTIVATE WATCH

> Deactivates a watchpoint, which you can later activate.

### Format

> DEACTIVATE WATCH [address-expression[,...]]

### Parameters

> #### address-expression

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

> Deactivates all watchpoints.

### Description

> Watchpoints are activated when you set them with the SET WATCH command. Use the DEACTIVATE WATCH command to deactivate one or more watchpoints.

> If you deactivate a watchpoint, the debugger ignores the watchpoint during program execution. To activate a deactivated watchpoint, use the ACTIVATE WATCH command. Activating and deactivating watchpoints enables you to run and rerun your program with or without watchpoints without having to cancel and then reset them.

> By default, the RERUN command saves the current state of all static watchpoints (activated or deactivated). The state of a particular nonstatic watchpoint might or might not be saved depending on the scope of the variable being watched relative to the main program unit (where execution restarts).

> To check if a watchpoint is deactivated, use the SHOW WATCH command.

> Related commands:

> > CANCEL ALL
> > RERUN
> > (SET,SHOW,CANCEL,ACTIVATE) WATCH

### Examples

#1
    DBG> DEACTIVATE WATCH SUB2\TOTAL

> This command deactivates the watchpoint at variable TOTAL in module SUB2.

#2
    DBG> DEACTIVATE WATCH/ALL

> This command deactivates all watchpoints you have set.

## DECLARE

> Declares a formal parameter within a command procedure. This enables you to pass an actual parameter to the procedure when entering an execute procedure (@) command.

### Format

> DECLARE p-name:p-kind [,p-name:p-kind[,...]]

### Parameters

> #### p-name

> Specifies a formal parameter (a symbol) that is declared within the command procedure.

> Do not specify a null parameter (represented either by two consecutive commas or by a comma at the end of the command).

> #### p-kind

> Specifies the parameter kind of a formal parameter. Valid keywords are as follows:

> ADDRESS | Specifies that the actual parameter is interpreted as an address expression. Same effect as DEFINE/ADDRESS symbol-name = actual-parameter.
> COMMAND | Specifies that the actual parameter is interpreted as a command. Same effect as DEFINE/COMMAND symbol-name = actual-parameter.
> VALUE | Specifies that the actual parameter is interpreted as a value expression in the current language. Same effect as DEFINE/VALUE symbol-name = actual-parameter.

### Description

> The DECLARE command is valid only within a command procedure.

> The DECLARE command binds one or more actual parameters, specified on the command line following the execute procedure (@) command, to formal parameters (symbols) declared within a command procedure.

> Each p-name:p-kind pair specified by a DECLARE command binds one formal parameter to one actual parameter. Formal parameters are bound to actual parameters in the order in which the debugger processes the parameter declarations. If you specify several formal parameters on a single DECLARE command, the leftmost formal parameter is bound to the first actual parameter, the next formal parameter is bound to the second, and so on. If you use a DECLARE command in a loop, the formal parameter is bound to the first actual parameter on the first iteration of the loop; the same formal parameter is bound to the second actual parameter on the next iteration, and so on.

> Each parameter declaration acts like a DEFINE command: it associates a formal parameter with an address expression, a command, or a value expression in the current language, according to the parameter kind specified. The formal parameters themselves are consistent with those accepted by the DEFINE command and can in fact be deleted from the symbol table with the DELETE command.

> The %PARCNT built-in symbol, which can be used only within a command procedure, enables you to pass a variable number of parameters to a command procedure. The value of %PARCNT is the number of actual parameters passed to the command procedure.

> Related commands:

> > @ (Execute Procedure)
> > DEFINE
> > DELETE

### Examples

#1
    ! ***** Command Procedure EXAM.COM *****
    SET OUTPUT VERIFY
    DECLARE K:ADDRESS
    EXAMINE K

    DBG> @EXAM ARR4
    %DEBUG-I-VERIFYIC, entering command procedure EXAM
     DECLARE K:ADDRESS
     EXAMINE K
    PROG_8\ARR4
        (1):        18
        (2):        1
        (3):        0
        (4):        1
    %DEBUG-I-VERIFYIC, exiting command procedure EXAM
    DBG>

> In this example, the DECLARE K:ADDRESS command declares the formal parameter K within command procedure EXAM.COM. When EXAM.COM is executed, the actual parameter passed to EXAM.COM is interpreted as an address expression, and the EXAMINE K command displays the value of that address expression. The SET OUTPUT VERIFY command causes the commands to echo when they are read by the debugger.

> At the debugger prompt, the @EXAM ARR4 command executes EXAM.COM, passing the actual parameter ARR4. Within EXAM.COM, ARR4 is interpreted as an address expression (an array variable, in this case).

#2
    ! ***** Debugger Command Procedure EXAM_GO.COM *****
    DECLARE L:ADDRESS, M:COMMAND
    EXAMINE L; M

    DBG> @EXAM_GO X "@DUMP"

> In this example, the command procedure EXAM_GO.COM accepts two parameters, an address expression (L) and a command string (M). The address expression is then examined and the command is executed.

> At the debugger prompt, the @EXAM_GO X "@DUMP" command executes EXAM_GO.COM, passing the address expression X and the command string @DUMP.

#3
    ! ***** Debugger Command Procedure VAR.DBG *****
    SET OUTPUT VERIFY
    FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
    DBG> @VAR.DBG 12,37,45
    %DEBUG-I-VERIFYIC, entering command procedure VAR.DBG
     FOR I = 1 TO %PARCNT DO (DECLARE X:VALUE; EVALUATE X)
    12
    37
    45
    %DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG
    DBG>

> In this example, the command procedure VAR.DBG accepts a variable number of parameters. That number is stored in the built-in symbol %PARCNT.

> At the debugger prompt, the @VAR.DBG command executes VAR.DBG, passing the actual parameters 12, 37, and 45. Therefore, %PARCNT has the value 3, and the FOR loop is repeated 3 times. The FOR loop causes the DECLARE command to bind each of the three actual parameters (starting with 12) to a new declaration of X. Each actual parameter is interpreted as a value expression in the current language, and the EVALUATE X command displays that value.

## DEFINE

> Assigns a symbolic name to an address expression, command, or value.

### Format

> DEFINE symbol-name=parameter [,symbol-name=parameter[,...]]

### Parameters

> #### symbol-name

> Specifies a symbolic name to be assigned to an address, command, or value. The symbolic name can be composed of alphanumeric characters and underscores. The debugger converts lowercase alphabetic characters to uppercase. The first character must not be a number. The symbolic name must be no more than 31 characters long.

> #### parameter

> Depends on the qualifier specified.

### Qualifiers

> #### /ADDRESS

> (Default) Specifies that the defined symbol is an abbreviation for an address expression. In this case, parameter is an address expression.

> #### /COMMAND

> Specifies that the defined symbol is treated as a new debugger command. In this case, parameter is a quoted character string. This qualifier provides, in simple cases, essentially the same capability as the following DCL command:

>     $ symbol := string

> To define complex commands, you might need to use command procedures with formal parameters. For more information about declaring parameters to command procedures, see the DECLARE command.

> #### /LOCAL

> Specifies that the definition is valid only in the command procedure in which it is defined. The defined symbol is not visible at debugger command level. By default, a symbol defined within a command procedure is visible outside that procedure.

> #### /VALUE

> Specifies that the defined symbol is an abbreviation for a value. In this case, parameter is a language expression in the current language.

### Description

> The DEFINE/ADDRESS command assigns a symbolic name to an address expression in a program. You can define a symbol for a nonsymbolic program location or for a symbolic program location having a long path-name prefix. You can then refer to that program location with the symbolic name. The /ADDRESS qualifier is the default.

> The DEFINE/COMMAND command enables you to define abbreviations for debugger commands or even define new commands, either from the debugger command level or from command procedures.

> The DEFINE/VALUE command enables you to assign a symbolic name to a value (or the result of evaluating a language expression).

> The DEFINE/LOCAL command confines symbol definitions to command procedures. By default, defined symbols are global (visible outside the command procedure).

> To enter several DEFINE commands with the same qualifier, first use the SET DEFINE command to establish a new default qualifier (for example, SET DEFINE COMMAND makes subsequent DEFINE commands behave like DEFINE/COMMAND). You can override the current default qualifier for a single DEFINE command by specifying another qualifier.

> In symbol translation, the debugger searches symbols you define during the debugging session first. So if you define a symbol that already exists in your program, the debugger translates the symbol according to its defined definition, unless you specify a path-name prefix.

> If a symbol is redefined, the previous definition is canceled, even if you used different qualifiers with the DEFINE command.

> Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands are available only when the image in whose context they were created is the current image. If you use the SET IMAGE command to establish a new current image, these definitions are temporarily unavailable. However, definitions created with the DEFINE/COMMAND and DEFINE/KEY commands are always available for all images.

> Use the SHOW SYMBOL/DEFINED command to determine the equivalence value of a symbol.

> Use the DELETE command to cancel a symbol definition.

> Related commands:

> > DECLARE
> > DELETE
> > SET IMAGE
> > SHOW DEFINE
> > SHOW SYMBOL/DEFINED

### Examples

#1
    DBG> DEFINE CHK=MAIN\LOOP+10

> This command assigns the symbol CHK to the address MAIN\LOOP+10.

#2
    DBG> DEFINE/VALUE COUNTER=0
    DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1)

> In this example, the DEFINE/VALUE command assigns a value of 0 to the symbol COUNTER. The SET TRACE command causes the debugger to increment the value of the symbol COUNTER by 1 whenever address R is encountered. In other words, this example counts the number of calls to R.

#3
    DBG> DEFINE/COMMAND BRE = "SET BREAK"

> This command assigns the symbol BRE to the debugger command SET BREAK.

## DEFINE/KEY

> Assigns a string to a function key.

> Note This command is not available in the Compaq DECwindows Motif for OpenVMS user interface to the debugger.

### Format

> DEFINE/KEY key-name "equivalence-string"

### Parameters

> #### key-name

> Specifies a function key to be assigned a string. Valid key names are as follows:

> Key Name | LK201 Keyboard | VT100-type | VT52-type
> --- | --- | --- | ---
> PF1 | PF1 | PF1 | Blue
> PF2 | PF2 | PF2 | Red
> PF3 | PF3 | PF3 | Black
> PF4 | PF4 | PF4 |
> KP0--KP9 | Keypad 0--9 | Keypad 0--9 | Keypad 0--9
> PERIOD | Keypad period (.) | Keypad period (.) |
> COMMA | Keypad comma (,) | Keypad comma (,) |
> MINUS | Keypad minus (-) | Keypad minus (-) |
> E1 | Find |  |
> E2 | Insert Here |  |
> E3 | Remove |  |
> E4 | Select |  |
> E5 | Prev Screen |  |
> E6 | Next Screen |  |
> HELP | Help |  |
> DO | Do |  |
> F6--F20 | F6--F20 |  |

> On LK201 keyboards:

> - You cannot define keys F1 to F5 or the arrow keys (E7 to E10).
> - You can define keys F6 to F14 only if you have first entered the DCL command SET TERMINAL/NOLINE_EDITING. In that case, the line-editing functions of the left and right arrow keys (E8 and E9) are disabled.

> #### equivalence-string

> Specifies the string to be processed when you press the specified key. Typically, this is one or more debugger commands. If the string includes any space or nonalphanumeric characters (for example, a semicolon separating two commands), enclose the string in quotation marks (").

### Qualifiers

> #### /ECHO (default)

> #### /NOECHO

> Controls whether the command line is displayed after the key has been pressed. Do not use /NOECHO with /NOTERMINATE.

> #### /IF_STATE=(state-name[,...])

> #### /NOIF_STATE (default)

> Specifies one or more states to which a key definition applies. The /IF_STATE qualifier assigns the key definition to the specified states. You can specify predefined states, such as DEFAULT and GOLD, or user-defined states. A state name can be any appropriate alphanumeric string. The /NOIF_STATE qualifier assigns the key definition to the current state.

> #### /LOCK_STATE

> #### /NOLOCK_STATE (default)

> Controls how long the state set by /SET_STATE remains in effect after the specified key is pressed. The /LOCK_STATE qualifier causes the state to remain in effect until it is changed explicitly (for example, with a SET KEY/STATE command). The /NOLOCK_STATE qualifier causes the state to remain in effect only until the next terminator character is typed, or until the next defined function key is pressed.

> #### /LOG (default)

> #### /NOLOG

> Controls whether a message is displayed indicating that the key definition has been successfully created. The /LOG qualifier displays the message. The /NOLOG qualifier suppresses the message.

> #### /SET_STATE=state-name

> #### /NOSET_STATE (default)

> Controls whether pressing the key changes the current key state. The /SET_STATE qualifier causes the current state to change to the specified state when you press the key. The /NOSET_STATE qualifier causes the current state to remain in effect.

> #### /TERMINATE

> #### /NOTERMINATE (default)

> Controls whether the specified string is terminated (processed) when the key is pressed. The /TERMINATE qualifier causes the string to be terminated when the key is pressed. The /NOTERMINATE qualifier enables you to press other keys before terminating the string by pressing the Return key.

### Description

> Keypad mode must be enabled (SET MODE KEYPAD) before you can use this command. Keypad mode is enabled by default.

> Previous | Next | Contents | Index

> | privacy and legal statement |
> 4538PRO_042.HTML