HP OpenVMS Systems Documentation

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.

Opens a system dump for analysis by the System Dump Debugger (kept debugger only).

Format

ANALYZE/CRASH_DUMP

Description

For OpenVMS Integrity servers and Alpha systems, invokes the System Dump Debugger (SDD) to analyze a system dump.

SDD is similar in concept to the System Code Debugger (SCD). While SCD allows connection to a running system, with control of the system's execution and the examination and modification of variables, SDD allows analysis of memory as recorded in a system dump.

Use of SDD usually involves two systems, although all of the required environment can be set up on a single system. The description that follows assumes that two systems are being used:

• The build system, where the image that causes the system crash has been built
• The test system, where the image is executed and the system crash occurs

In common with SCD, the OpenVMS debugger user interface allows you to specify variable names, routine names, and so on, precisely as they appear in your source code. Also, SDD can display the source code where the software was executing at the time of the system crash.

SDD recognizes the syntax, data typing, operators, expressions, scoping rules, and other constructs of a given language. If your code or driver is written in more than one language, you can change the debugging context from one language to another during a debugging session.

To use SDD you must do the following:

• Build the system image or device driver that is causing the system crash.
• Boot a system, including the system image or device driver, and perform the necessary steps to cause the system crash.
• Reboot the system and save the dump file.
• Invoke SDD, which is integrated with the OpenVMS debugger.

For more information about using the SDD, including a sample SDD session, see the OpenVMS Alpha System Analysis Tools Manual.

Related commands:

ANALYZE/PROCESS_DUMP
CONNECT %NODE
SDA

Example

DBG> ANALYZE/CRASH_DUMP
DBG>
      

Invokes SDD from within the kept debugger.

Opens a process dump for analysis with the System Code Debugger (kept debugger only)

Format

ANALYZE/PROCESS_DUMP dumpfile

Parameters

dumpfile

The name of the process dump file to be analyzed. The file type must be .DMP.

Qualifiers

/IMAGE_PATH=directory-spec

Specifies the search path for the debugger to find the files that contains the debugger symbol tables (DSTs). The files must be of type .DSF or .EXE, with the same name as the image names in the dumpfile. For example, if image name foo.exe is in the dump file, then the debugger searches for foo.dsf or foo.exe.

Description

(Kept debugger only.) Opens a process dump for analysis with the System Code Debugger (SCD). The qualifier /PROCESS_DUMP is required and distinguishes this command from the one that invokes the System Dump Debugger (SDD), ANALYZE/CRASH_DUMP.

The qualifier /IMAGE_PATH=directory-spec is optional, and specifies the search path the debugger is to use to find the debugger symbol table (DST) files. The debugger builds an image list from the saved process image list. When you set an image (the main image is automatically set), the debugger attempts to open that image in order to find the DSTs.

If you include the /IMAGE_PATH=directory-spec qualifier, the debugger searches for the .DST file in the specified directory. The debugger first tries to translate directory-spec as the logical name of a directory search list. If that fails, the debugger interprets directory-spec as a directory specification, and searches that directory for matching .DSF or .EXE files. A .DSF file takes precedence over an .EXE file. The name of the .DSF or .EXE file must match the image name.

If you do not include the /IMAGE_PATH=directory-spec qualifier, the debugger looks for the DST file first in the directory that contains the dump file. If that fails, the debugger next searches directory SYS$SHARE and then directory SYS$MESSAGE. If the debugger fails to find a DST file for the image, symbolic information available to the debugger is limited to global and universal symbol names.

The debugger checks for link date-time mismatches between the dump file image and the DST file and issues a warning if one is discovered.

The parameter dumpfile is the name of the process dump file to be analyzed. Note that the process dump file type must be .DMP and the DST file type must be either .DSF or .EXE.

For more information about using SCD, see the OpenVMS Alpha System Analysis Tools Manual.

Related commands:

ANALYZE/CRASH_DUMP
CONNECT %NODE
SDA

Example

DBG> ANALYZE/PROCESS/IMAGE_DUMP=my_disk$:[my_dir] 
my_disk$:[my_dir]wecrash.dmp
%SYSTEM-F-IMGDMP, dynamic image dump signal at PC=001C0FA0B280099C, 
 PS=001C003C 
break on unhandled exception preceding WECRASH\ 
th_run 
\%LINE 26412 in THREAD 8 
 26412:         if (verify) { 
DBG> SET RADIX HEXADECIMAL; EXAMINE PC
WECRASH\th_run\%PC:     0000000000030244 
DBG>
      

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

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

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.

1. Saves the current values of the general registers.
2. Constructs an argument list.
3. Executes a call to the routine specified in the command and passes any arguments.
4. Executes the routine.
5. Displays the value returned by the routine in the return status register. 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.
6. Restores the values of the general registers to the values they had just before the CALL command was executed.
7. 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 for Alpha systems and T_floating format for Integrity servers.

On Alpha, passing a floating-point literal in a format other than F_floating is not supported, as shown in 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, 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 SO RT.

If you are debugging a multiprocess program, the CALL command is executed in the context of the current process set. In addition, when debugging a multiprocess program, the way in which execution continues in your process depends on whether you entered a SET MODE [NO]INTERRUPT command or a SET MODE [NO]WAIT command. By default (SET MODE NOINTERRUPT), when one process stops, the debugger takes no action with regard to the other processes. Also by default (SET MODE WAIT), the debugger waits until all processes in the current process set have stopped before prompting for a new command. See Chapter 15 for more information.

Related commands:

GO
EXIT
SET PROCESS
SET MODE [NO]INTERRUPT
STEP

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.