|
||||||||||
|
|
|
|
|
|
|
|
|
|
|
|
||||||||||
|
 |
 |
HP OpenVMS systems documentation |
|
| Previous | Contents | Index |
Activates a tracepoint that you have previously set and then deactivated.
ACTIVATE TRACE [address-expression[,...]]
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.
/ACTIVATING
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.
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
| #1 |
|---|
DBG> ACTIVATE TRACE MAIN\LOOP+10
|
This command activates the user-defined tracepoint at the location MAIN\LOOP+10.
| #2 |
|---|
DBG> ACTIVATE TRACE/ALL
|
This command activates all user-defined tracepoints.
Activates a watchpoint that you have previously set and then deactivated.
ACTIVATE WATCH [address-expression[,...]]
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.
/ALL
Activates all watchpoints.
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
| #1 |
|---|
DBG> ACTIVATE WATCH SUB2\TOTAL
|
This command activates the watchpoint at variable TOTAL in module SUB2.
| #2 |
|---|
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).
ANALYZE/CRASH_DUMP
For OpenVMS I64 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 HP OpenVMS System Analysis Tools Manual.
Related commands:
ANALYZE/PROCESS_DUMP
CONNECT %NODE
SDA
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)
ANALYZE/PROCESS_DUMP dumpfile
dumpfile
The name of the process dump file to be analyzed. The file type must be .DMP.
/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.
(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 HP OpenVMS System Analysis Tools Manual.
Related commands:
ANALYZE/CRASH_DUMP
CONNECT %NODE
SDA
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.
ATTACH process-name
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 (").
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
| #1 |
|---|
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.
| #2 |
|---|
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.
CALL routine-name [(argument[,...])]
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:
/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.
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 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.
- 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 for VAX and Alpha systems and T_floating format for I64.
On VAX and 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 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 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
SET VECTOR_MODE [NO]SYNCHRONIZED (VAX only)
STEP
SYNCHRONIZE VECTOR_MODE (VAX only)
| #1 |
|---|
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.
| #2 |
|---|
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.
| #3 |
|---|
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.
| #4 |
|---|
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.
| #5 |
|---|
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.
| Previous | Next | Contents | Index |