OpenVMS Debugger Manual

In this example, the SET ATSIGN command establishes that debugger command procedures are, by default, in USER:[JONES.DEBUG] and have a file type of .DBG. The @CHECKOUT command executes the command procedure USER:[JONES.DEBUG]CHECKOUT.DBG. The debugger echoes commands in the command because of the SET OUTPUT VERIFY command.

ACTIVATE BREAK

Activates a breakpoint that you have previously set and then deactivated.

Format

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

PARAMETERS

address-expression
Specifies a breakpoint to be activated. 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). Activates a breakpoint established by a previous SET BREAK/ACTIVATING command.
/ALL
By default, activates all user-defined breakpoints. When used with /PREDEFINED, activates all predefined breakpoints but no user-defined breakpoints. To activate all breakpoints, use /ALL/USER/PREDEFINED.
/BRANCH
Activates a breakpoint established by a previous SET BREAK/BRANCH command.
/CALL
Activates a breakpoint established by a previous SET BREAK/CALL command.
/EVENT=event-name
Activates 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
Activates a breakpoint established by a previous SET BREAK/EXCEPTION command.
/HANDLER
Activates a breakpoint established by a previous SET BREAK/HANDLER command.
/INSTRUCTION
Activates a breakpoint established by a previous SET BREAK/INSTRUCTION command.
/LINE
Activates a breakpoint established by a previous SET BREAK/LINE command. Do not specify an address expression with this qualifier.
/PREDEFINED
Activates a specified predefined breakpoint without affecting any user-defined breakpoints. When used with /ALL, activates all predefined breakpoints.
/SYSEMULATE
(Alpha only) Activates a breakpoint established by a previous SET BREAK/SYSEMULATE command.
/TERMINATING
Activates a breakpoint established by a previous SET BREAK/TERMINATING command.
/UNALIGNED_DATA
(Alpha only) Activates a breakpoint established by a previous SET BREAK/UNALIGNED_DATA command, or reactivates a breakpoint previously disabled by a DEACTIVATE BREAK/UNALIGNED_DATA command.
/USER
Activates a specified user-defined breakpoint without affecting any predefined breakpoints. To activate all user-defined breakpoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Activates 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 ACTIVATE BREAK command to activate one or more breakpoints that you deactivated with DEACTIVATE BREAK.
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).
You can activate and deactivate user-defined breakpoints or predefined breakpoints or both. To check if a breakpoint is activated, use the SHOW BREAK command.
Related commands:

CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) BREAK
(SET,SHOW) EVENT_FACILITY

Examples

DBG> ACTIVATE BREAK MAIN\LOOP+10

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

DBG> ACTIVATE BREAK/ALL

This command activates all user-defined breakpoints.

DBG> ACTIVATE BREAK/ALL/USER/PREDEFINED

This command activates all breakpoints, both user-defined and predefined.

ACTIVATE TRACE

Activates a tracepoint that you have previously set and then deactivated.

Format

ACTIVATE TRACE [address-expression[,...]]

PARAMETERS

address-expression
Specifies a tracepoint to be activated. 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). Activates a tracepoint established with a previous SET TRACE/ACTIVATING command.
/ALL
By default, activates all user-defined tracepoints. When used with /PREDEFINED, activates all predefined tracepoints but no user-defined tracepoints. To activate all tracepoints, use /ALL/USER/PREDEFINED.
/BRANCH
Activates a tracepoint established with a previous SET TRACE/BRANCH command.
/CALL
Activates a tracepoint established with a previous SET TRACE/CALL command.
/EVENT=event-name
Activates 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
Activates a tracepoint established with a previous SET TRACE/EXCEPTION command.
/INSTRUCTION
Activates a tracepoint established with a previous SET TRACE/INSTRUCTION command.
/LINE
Activates a tracepoint established with a previous SET TRACE/LINE command.
/PREDEFINED
Activates a specified predefined tracepoint without affecting any user-defined tracepoints. When used with /ALL, activates all predefined tracepoints.
/TERMINATING
Activates a tracepoint established with a previous SET TRACE/TERMINATING command.
/USER
Activates a specified user-defined tracepoint without affecting any predefined tracepoints. To activate all user-defined tracepoints, use the /ALL qualifier.
/VECTOR_INSTRUCTION
(VAX only) Activates 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 ACTIVATE TRACE command to activate one or more tracepoints that you deactivated with DEACTIVATE TRACE.
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).
You can activate and deactivate user-defined tracepoints or predefined tracepoints or both. To check if a tracepoint is activated, use the SHOW TRACE command.
Related commands:

CANCEL ALL
RERUN
(SET,SHOW) EVENT_FACILITY
(SET,SHOW,CANCEL,DEACTIVATE) TRACE

Examples

DBG> ACTIVATE TRACE MAIN\LOOP+10

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

DBG> ACTIVATE TRACE/ALL

This command activates all user-defined tracepoints.

ACTIVATE WATCH

Activates a watchpoint that you have previously set and then deactivated.

Format

ACTIVATE WATCH [address-expression[,...]]

PARAMETERS

address-expression
Specifies a watchpoint to be activated. 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
Activates all watchpoints.

DESCRIPTION

Watchpoints are activated when you set them with the SET WATCH command. Use the ACTIVATE WATCH command to activate one or more watchpoints that you deactivated with DEACTIVATE WATCH.
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 activated, use the SHOW WATCH command.
Related commands:

CANCEL ALL
RERUN
(SET,SHOW,CANCEL,DEACTIVATE) WATCH

Examples

DBG> ACTIVATE WATCH SUB2\TOTAL

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

DBG> ACTIVATE WATCH/ALL

This command activates all watchpoints you have set and deactivated.

ATTACH

Passes control of your terminal from the current process to another process.

Note
This command is not available in the DECwindows Motif interface to the debugger.

Format

ATTACH process-name

PARAMETERS

process-name
Specifies the process to which your terminal is to be attached. The process must already exist before you try to attach to it. If the process name contains nonalphanumeric or space characters, you must enclose it in quotation marks (").

DESCRIPTION

The ATTACH command enables you to go back and forth between a debugging session and your command interpreter, or between two debugging sessions. To do so, you must first use the SPAWN command to create a subprocess. You can then attach to it whenever you want. To return to your original process with minimal system overhead, use another ATTACH command.
Related command:

SPAWN

Examples

DBG> SPAWN
$ ATTACH JONES
%DEBUG-I-RETURNED, control returned to process JONES
DBG> ATTACH JONES_1
$

In this example, the series of commands creates a subprocess named JONES_1 from the debugger (currently running in the process JONES) and then attaches to that subprocess.

DBG> ATTACH "Alpha One"
$

This example illustrates using quotation marks to enclose a process name that contains a space character.

CALL

Calls a routine that was linked with your program.

Format

CALL routine-name [(argument[,...])]

PARAMETERS

routine-name
Specifies the name or the memory address of the routine to be called.
argument
Specifies an argument required by the routine. Arguments can be passed by address, by descriptor, by reference, and by value, as follows:
%ADDR
(Default, except for C and C++.) Passes the argument by address. The format is as follows:
CALL
      routine-name (%ADDR
      address-expression)
      

      
The debugger evaluates the address expression and passes that address to the routine specified. For simple variables (such as X), the address of X is passed into the routine. This passing mechanism is how Fortran implements ROUTINE(X). In other words, for named variables, using %ADDR corresponds to a call by reference in Fortran. For other expressions, however, you must use the %REF function to call by reference. For complex or composite variables (such as arrays, records, and access types), the address is passed when you specify %ADDR, but the called routine might not handle the passed data properly. Do not specify a literal value (a number or an expression composed of numbers) with %ADDR.
%DESCR
Passes the argument by descriptor. The format is as follows:
CALL
      routine-name (%DESCR
      language-expression)
      

      
The debugger evaluates the language expression and builds a standard descriptor to describe the value. The descriptor is then passed to the routine you named. You would use this technique to pass strings to a Fortran routine.
%REF
Passes the argument by reference. The format is as follows:
CALL
      routine-name (%REF
      language-expression)
      

      
The debugger evaluates the language expression and passes a pointer to the value, into the called routine. This passing mechanism corresponds to the way Fortran passes the result of an expression.
%VAL
(Default for C and C++.) Passes the argument by value. The format is as follows:
CALL
      routine-name (%VAL
      language-expression)
      

      
The debugger evaluates the language expression and passes the value directly to the called routine.

QUALIFIERS

/AST (default)

/NOAST
Controls whether the delivery of asynchronous system traps (ASTs) is enabled or disabled during the execution of the called routine. The /AST qualifier enables the delivery of ASTs in the called routine. The /NOAST qualifier disables the delivery of ASTs in the called routine. If you do not specify /AST or /NOAST with the CALL command, the delivery of ASTs is enabled unless you have previously entered the DISABLE AST command.
/SAVE_VECTOR_STATE

/NOSAVE_VECTOR_STATE (default)
Applies to VAX vectorized programs. Controls whether the current state of the vector processor is saved and then restored when a routine is called with the CALL command.
The state of the vector processor comprises the following:

The values of the vector registers (V0 to V15) and the vector control registers (VCR, VLR, and VMR)
Any vector exception (an exception caused by the execution of a vector instruction) that might be pending delivery

When you use the CALL command to execute a routine, execution of the routine might change the state of the vector processor as follows:

By changing the values of vector registers or vector control registers
By causing a vector exception
By causing the delivery of a vector exception that was pending when the CALL command was issued

The /SAVE_VECTOR_STATE qualifier specifies that after the called routine has completed execution, the debugger restores the state of the vector processor that exists before the CALL command is issued. This ensures that, after the called routine has completed execution:

Any vector exception that was pending delivery before the CALL command was issued is still pending delivery
No vector exception that was triggered during the routine call is still pending delivery
The values of the vector registers are identical to their values before the CALL command was issued

The /NOSAVE_VECTOR_STATE qualifier (which is the default) specifies that the state of the vector processor that exists before the CALL command is issued is not restored by the debugger after the called routine has completed execution. In this case, the state of the vector processor after the routine call depends on the effect (if any) of the called routine.
The /[NO]SAVE_VECTOR_STATE qualifiers have no effect on the general registers. The values of these registers are always saved and restored when you execute a routine with the CALL command.

DESCRIPTION

The CALL command is one of the four debugger commands that can be used to execute your program (the others are GO, STEP, and EXIT). The CALL command enables you to execute a routine independently of the normal execution of your program. The CALL command executes a routine whether or not your program actually includes a call to that routine, as long as the routine was linked with your program.
When you enter a CALL command, the debugger takes the following actions. For more information, see the qualifier descriptions.

Saves the current values of the general registers.
Constructs an argument list.
Executes a call to the routine specified in the command and passes any arguments.
Executes the routine.
Displays the value returned by the routine in register R0. By convention, after a called routine has executed, register R0 contains the function return value (if the routine is a function) or the procedure completion status (if the routine is a procedure that returns a status value). If a called procedure does not return a status value or function value, the value in R0 might be meaningless, and the "value returned" message can be ignored.
Restores the values of the general registers to the values they had just before the CALL command was executed.
Issues the prompt.

The debugger assumes that the called routine conforms to the procedure calling standard (see the OpenVMS Calling Standard). However, the debugger does not know about all the argument-passing mechanisms for all supported languages. Therefore, you might need to specify how to pass parameters, for example, use CALL SUB1(%VAL X) rather than CALL SUB1(X). For complete information about how arguments are passed to routines, see your language documentation.
When the current language is C or C++, the CALL command by default now passes arguments by value rather than by reference. In addition, you can now pass the following arguments without using a passing mechanism lexical (such as %REF or %VAL):

Routine references
Quoted strings (treated as %REF strings)
Structures, records, and objects
Floating-point parameters by value in F_, D_, G_, S_, and T_floating format by dereferencing a variable of that type

If the routine contains parameters that are not read-only, the values assigned to parameters may not be visible, and access to values is unreliable. This is because the debugger adjusts parameter values in an internal argument list, not the program argument list. To examine changing values, consider using static variables instead of parameters.
The CALL command converts all floating-point literals to F_floating format. Passing a floating-point literal in a format other than F_floating is not supported. (See the example below.)
A common debugging technique at an exception breakpoint (resulting from a SET BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine with the CALL command. When you enter the CALL command at an exception breakpoint, any breakpoints, tracepoints, or watchpoints that were previously set within the called routine are temporarily disabled so that the debugger does not lose the exception context. However, such eventpoints are active if you enter the CALL command at a location other than an exception breakpoint.
When an exception breakpoint is triggered, execution is suspended before any application-declared condition handler is invoked. At an exception breakpoint, entering a GO or STEP command after executing a routine with the CALL command causes the debugger to resignal the exception (see the GO and STEP commands).
On Alpha processors, you cannot debug routines that are activated before the routine activated by a CALL command. For example, your program is stopped in routine MAIN, and you set a breakpoint in routine SORT. You issue the debugger command CALL SORT. While debugging routine SORT, you cannot debug routine MAIN. You must first return from the call to routine SORT.
If you are using the multiprocess debugging configuration to debug a multiprocess program (if the logical name DBG$PROCESS has the value MULTIPROCESS), the CALL command is executed in the context of the visible process, but images in any other processes that are not on hold (through a SET PROCESS/HOLD command) are also allowed to execute. If you use the DO command to broadcast a CALL command to one or more processes, the CALL command is executed in the context of each specified process that is not on hold, but images in any other processes that are not on hold are also allowed to execute. In all cases, a hold condition in the visible process is ignored.
If you are using the multiprocess debugging configuration to debug a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command. By default (SET MODE INTERRUPT), execution continues until it is suspended in any process. At that point, execution is interrupted in any other processes that were executing images, and the debugger prompts for input.
Related commands:

GO
EXIT
DO
SET PROCESS
SET MODE [NO]INTERRUPT
SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
STEP
SYNCHRONIZE VECTOR_MODE (VAX only)

Examples

DBG> CALL SUB1(X)
value returned is 19
DBG>

This command calls routine SUB1, with parameter X (by default, the address of X is passed). In this case, the routine returns the value 19.

DBG> CALL SUB(%REF 1)
value returned is 1
DBG>

This command passes a pointer to a memory location containing the numeric literal 1, into the routine SUB.

DBG> SET MODULE SHARE$LIBRTL
DBG> CALL LIB$SHOW_VM
 1785 calls to LIB$GET_VM, 284 calls to LIB$FREE_VM, 122216 bytes 
 still allocated, value returned is 00000001
DBG>

This example calls Run-Time Library routine LIB$SHOW_VM (in shareable image LIBRTL) to display memory statistics. The SET MODULE command makes the universal symbols (routine names) in LIBRTL visible in the main image. See also the SHOW MODULE/SHARE command.

DBG> CALL testsub (%val 11.11, %val 22.22, %val 33.33)

This example passes floating-point parameters by value, to a C subroutine with the function prototype void testsub (float, float, float). The floating-point parameters are passed in F_floating format.

     SUBROUTINE CHECK_TEMP(TEMPERATURE,ERROR_MESSAGE) 
        REAL TOLERANCE /4.7/ 
        REAL TARGET_TEMP /92.0/ 
        CHARACTER*(*) ERROR_MESSAGE 
        IF (TEMPERATURE .GT. (TARGET_TEMP + TOLERANCE)) THEN 
           TYPE *,'Input temperature out of range:',TEMPERATURE 
           TYPE *,ERROR_MESSAGE 
        ELSE 
           TYPE *,'Input temperature in range:',TEMPERATURE 
        END IF 
     RETURN 
     END
DBG> CALL CHECK_TEMP(%REF 100.0, %DESCR 'TOLERANCE-CHECK 1 FAILED')
Input temperature out of range:   100.0000 
TOLERANCE-CHECK 1 FAILED 
value returned is 0
DBG> CALL CHECK_TEMP(%REF 95.2, %DESCR 'TOLERANCE-CHECK 2 FAILED')
Input temperature in range:   95.2000 
value returned is 0
DBG>

This Fortran routine (CHECK_TEMP) accepts two parameters, TEMPERATURE (a real number) and ERROR_MESSAGE (a string). Depending on the value of TEMPERATURE, the routine prints different output. Each CALL command passes a temperature value (by reference) and an error message (by descriptor). Because this routine does not have a formal return value, the value returned is undefined, in this case, 0.

CANCEL ALL

Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope and type to their default values. Restores the line, symbolic, and G_floating modes established with the SET MODE command to their default values.

Format

CANCEL ALL

QUALIFIERS

/PREDEFINED
Cancels all predefined (but no user-defined) breakpoints and tracepoints.
/USER
Cancels all user-defined (but no predefined) breakpoints, tracepoints, and watchpoints. This is the default unless you specify /PREDEFINED.

DESCRIPTION

The CANCEL ALL command does the following:
Cancels all user-defined eventpoints (those created with the commands SET BREAK, SET TRACE, and SET WATCH). This is equivalent to entering the commands CANCEL BREAK/ALL, CANCEL TRACE/ALL, and CANCEL WATCH/ALL. Depending on the type of program (for example Ada, multiprocess), certain predefined breakpoints or tracepoints might be set automatically when you start the debugger. To cancel all predefined but no user-defined eventpoints, use CANCEL ALL/PREDEFINED. To cancel all predefined and user-defined eventpoints, use CANCEL ALL/PREDEFINED/USER.
Restores the scope search list to its default value (0,1,2,...,n). This is equivalent to entering the CANCEL SCOPE command.
Restores the data type for memory locations that are associated with a compiler-generated type to the associated type. Restores the type for locations that are not associated with a compiler-generated type to "longword integer". This is equivalent to entering the CANCEL TYPE/OVERRIDE and SET TYPE LONGWORD commands.
Restores the line, symbolic, and G_floating modes established with the SET MODE command to their default values. This is equivalent to entering the following command:
DBG> SET MODE LINE,SYMBOLIC,NOG_FLOAT
The CANCEL ALL command does not affect the current language setting or modules included in the run-time symbol table.
Related commands:

(CANCEL,DEACTIVATE) BREAK
CANCEL SCOPE
(CANCEL,DEACTIVATE) TRACE
CANCEL TYPE/OVERRIDE
(CANCEL,DEACTIVATE) WATCH
(SET,CANCEL) MODE
SET TYPE

Examples

DBG> CANCEL ALL

This command cancels all user-defined breakpoints and tracepoints and all watchpoints, and restores scopes, types, and some modes to their default values. In this example, there are no predefined breakpoints or tracepoints.

DBG> CANCEL ALL
%DEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled

Previous | Next | Contents | [Home] | [Comments] | [Ordering info] | [Help]
  4538P030.HTM
  OSSG Documentation
  22-NOV-1996 13:02:16.91
Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal

%ADDR	(Default, except for C and C++.) Passes the argument by address. The format is as follows: CALL routine-name (%ADDR address-expression) The debugger evaluates the address expression and passes that address to the routine specified. For simple variables (such as X), the address of X is passed into the routine. This passing mechanism is how Fortran implements ROUTINE(X). In other words, for named variables, using %ADDR corresponds to a call by reference in Fortran. For other expressions, however, you must use the %REF function to call by reference. For complex or composite variables (such as arrays, records, and access types), the address is passed when you specify %ADDR, but the called routine might not handle the passed data properly. Do not specify a literal value (a number or an expression composed of numbers) with %ADDR.
%DESCR	Passes the argument by descriptor. The format is as follows: CALL routine-name (%DESCR language-expression) The debugger evaluates the language expression and builds a standard descriptor to describe the value. The descriptor is then passed to the routine you named. You would use this technique to pass strings to a Fortran routine.
%REF	Passes the argument by reference. The format is as follows: CALL routine-name (%REF language-expression) The debugger evaluates the language expression and passes a pointer to the value, into the called routine. This passing mechanism corresponds to the way Fortran passes the result of an expression.
%VAL	(Default for C and C++.) Passes the argument by value. The format is as follows: CALL routine-name (%VAL language-expression) The debugger evaluates the language expression and passes the value directly to the called routine.