Updated: 11 December 1998

OpenVMS Debugger Manual

Once you have entered the CONNECT command to interrupt a debuggable image and bring a process under debugger control, you can enter the DISCONNECT command to release the process without terminating it. (In contrast, when you specify a process with the EXIT or QUIT command, the process is terminated.)

When you invoke the debugger with the CTRL/Y-DEBUG sequence or the RUN/DEBUG command, pay careful attention to your use of the DISCONNECT command. Avoid the following situations:

• If you are running only one process in a multiprocess configuration, and you enter the DISCONNECT command for this process, you terminate the debugger main process.
• If you are running n processes in a multiprocess configuration, and you enter the DISCONNECT command for the n-1 process, you terminate all processes.

Bear in mind, also, that the debugger kernel runs in the same process as the image being debugged. If you issue the DISCONNECT command for this process, you release your process, but the kernel remains activated. This activation continues until the program image finishes running. If you install a new version of the debugger while one or more disconnected but activated kernels inhabit user program space, you can experience problems with debugger installation and behavior.

15.3.6 Screen Mode Features for Multiprocess Debugging

Screen mode displays, whether predefined or user defined, are associated with the visible process by default. For example, SRC shows the source code where execution is suspended in the visible process, OUT shows the output of commands executed in the context of the visible process, and so on.

By using the /PROCESS qualifier with the DISPLAY command, you can create process-specific displays or make existing displays process specific, respectively. The contents of a process-specific display are generated and modified in the context of that process. You can make any display process specific except for the PROMPT display. For example, the following command creates the automatically updated source display SRC_3, which shows the source code where execution is suspended in process 3:

DBG_2> DISPLAY/PROCESS=(%PROC 3) SRC_3 AT RS23 - _DBG_2> SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC)

You assign attributes to process-specific displays as for displays that are not process specific. For example, the following command makes display SRC_3 the current scrolling and source display---that is, the output of SCROLL, TYPE, and EXAMINE/SOURCE commands are then directed at SRC_3:

DBG_2> SELECT/SCROLL/SOURCE SRC_3

If you enter a DISPLAY/PROCESS command without specifying a process, the specified display is then specific to the process that was the visible process when you entered the command. For example, the following command makes OUT_X specific to process 2:

DBG_2> DISPLAY/PROCESS OUT_X

The /SUFFIX qualifier appends a process identifying suffix that denotes the visible process to a display name. This qualifier can be used directly after a display name in any command that specifies a display (for example, DISPLAY, EXTRACT, SAVE). It is especially useful within command procedures in conjunction with display definitions or key definitions that are bound to display definitions.

In a multiprocess configuration, the predefined tracepoint on process activation automatically creates a new source display and a new instruction display for each new process that comes under debugger control. The displays have the names SRC_n and INST_n, respectively, where n is the process number. These displays are initially marked as removed. They are automatically deleted on process termination.

Several predefined keypad key sequences enable you to configure your screen with the process-specific source and instruction displays that are created automatically when a process is activated. Key sequences that are specific to multiprocess programs are as follows: PF1 KP9, PF4 KP9, PF4 KP7, PF4 KP3, PF4 KP1. See Section A.5 for the general effect of these sequences. Use the SHOW KEY command to determine the exact commands.

15.3.7 Setting Watchpoints in Global Sections (Alpha Only)

On Alpha processors, you can set watchpoints in global sections. A global section is a region of memory that is shared among all processes of a multiprocess program. A watchpoint that is set on a location in a global section (a global section watchpoint) triggers when any process modifies the contents of that location.

When setting watchpoints on arrays or records, note that performance is improved if you specify individual elements rather than the entire structure with the SET WATCH command.

If you set a watchpoint on a location that is not yet mapped to a global section, the watchpoint is treated as a conventional static watchpoint. For example:

DBG_1> SET WATCH ARR(1) DBG_1> SHOW WATCH watchpoint of PPL3\ARR(1)

When ARR is subsequently mapped to a global section, the watchpoint is automatically treated as a global section watchpoint and an informational message is issued. For example:

DBG_1> GO %DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has been remapped to a global section predefined trace on activation at routine PPL3 in %PROCESS_NUMBER 2 predefined trace on activation at routine PPL3 in %PROCESS_NUMBER 3 watch of PPL3\ARR(1) at PPL3\%LINE 93 in %PROCESS_NUMBER 2 93: ARR(1) = INDEX old value: 0 new value: 1 break at PPL3\%LINE 94 in %PROCESS_NUMBER 2 94: ARR(I) = I

After the watched location is mapped to a global section, the watchpoint is visible from each process. For example:

DBG_2> DO (SHOW WATCH) For %PROCESS_NUMBER 1 watchpoint of PPL3\ARR(1) [global-section watchpoint] For %PROCESS_NUMBER 2 watchpoint of PPL3\ARR(1) [global-section watchpoint] For %PROCESS_NUMBER 3 watchpoint of PPL3\ARR(1) [global-section watchpoint]

15.3.8 Using Multiprocess Commands with the Default Configuration

All commands, qualifiers, and built-in symbols that are provided for multiprocess debugging are also understood in the default debugging configuration (provided you have invoked the debugger with the DEBUG/KEEP command) and have analogous behaviors (where applicable). For example:

• The EXIT command without a parameter ends a debugging session in both configurations.
• A DO command without the /PROCESS qualifier executes the commands specified in all processes.
• In the default configuration, the visible process is the process that runs the entire program. It is identified as process 1 in a SHOW PROCESS display.
• Process-specific built-in symbols, such as %PROCESS_NUMBER and %VISIBLE_PROCESS, are interpreted correctly in the default configuration.

This compatibility enables you to use command procedures designed for multiprocess debugging when debugging programs that run in only one process.

15.3.9 System Requirements for Multiprocess Debugging

Several users debugging multiprocess programs can place a load on a system. This section describes the resources used by the debugger, so that you or your system manager can tune your system for this activity.

Note that the discussion covers only the resources used by the debugger. You might have to tune your system to support the multiprocess programs themselves.

15.3.9.1 User Quotas

Each user needs a PRCLM quota sufficient to create an additional process for the debugger, beyond the number of processes needed by the program.

BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may need to be increased to account for the debugger process as follows:

• Each user's ENQLM quota should be increased by at least the number of processes being debugged.
• Each user's PGFLQUOTA might need to be increased. If a user has an insufficient PGFLQUOTA, the debugger might fail to activate or cause "virtual memory exceeded" errors during execution.
• Each user's BYTLM and FILLM quotas might need to be increased. The debugger requires BYTLM and FILLM quotas sufficient to open each image file being debugged, the corresponding source files, and the debugger input, output, and log files.

The kernel and main debugger communicate through global sections. The main debugger communicates with up to 8 kernel debuggers through a 65-page global section. Therefore, the system global-page and global-section parameters (GBLPAGES and GBLSECTIONS, respectively) might need to be increased. For example, if 10 users are using the debugger simultaneously, 10 global sections using a total of 650 global pages are required by the debugger.

This chapter describes features of the debugger that are specific to vectorized programs (programs that use VAX vector instructions). Use these features in addition to those explained in other chapters.

The information in this chapter enables you to perform the following tasks:

• Display information about the availability and use of the vector processor on your system
• Control and monitor the execution of vector instructions with breakpoints, watchpoints, and so on
• Examine and deposit into the vector control registers (%VCR, %VLR, and %VMR) and the vector registers (%V0 to %V15)
• Examine and deposit vector instructions and their operands
• Perform masked operations when examining vector registers or vector instructions to display only certain register elements or override the masking associated with a vector instruction
• When using the EXAMINE command, specify composite address expressions of a complex form that might be appropriate for a vectorized program
• Display the decoded results of vector floating-point exceptions
• Control synchronization between the scalar and vector processors
• Save and restore the current vector state when using the CALL command to execute a routine that might affect the vector state
• Display vector register data using a screen-mode display

For additional information that is specific to a vectorized high-level language program, see the associated language documentation. For complete information about vector instructions and vector registers, see the OpenVMS MACRO and Instruction Set Reference Manual.

The SHOW PROCESS/FULL command provides some information about the availability and use of the vector processor on your system. For example:

DBG> SHOW PROCESS/FULL . . . Vector capable: Yes Vector consumer: Yes Vector CPU time: 0 00:03:17.18 Fast Vector context switches: 0 Slow Vector context switches: 0 . . . DBG>

The Vector capable field can have the following entries:

Vector-Capable Entry	Description
Yes	The VAX system has a vector processor, and it is available to the process that is running the program.
No (protected)	The VAX system has a vector processor, but the process running the program is denied access to the processor.
VVIEF	The VAX system does not have a vector processor. It is running the VAX Vector Instruction Emulation Facility (VVIEF). The VVIEF is available to the process that is running the program.
No	The VAX system does not have an active vector processor, and the VVIEF is not loaded on the system.

16.2 Controlling and Monitoring the Execution of Vector Instructions

The following sections explain how to perform the following tasks:

• Execute the program to (step to) either the next vector instruction or any one of a set of specified vector instructions.
• Set breakpoints and tracepoints that trigger either on any vector instruction or on any one of a set of specified vector instructions.
• Set watchpoints to monitor changes in vector registers.

To execute the program to the next vector instruction encountered in the program, enter the STEP/VECTOR_INSTRUCTION command.

You can also execute the program to the next vector instruction whose opcode is in a list of opcodes by using the command STEP/INSTRUCTION=(opcode[,...]). For example:

DBG> STEP/INSTRUCTION=(VLDL,VSTL,MOVL)

The SET STEP command enables you to change the default unit of execution of the STEP command as follows:

• Enter the SET STEP VECTOR_INSTRUCTION command to make the STEP command execute the program to the next vector instruction by default.
• Enter the SET STEP INSTRUCTION=(opcode[,...]) command to make the STEP command execute the program to the next instruction that is in the list of opcodes (including a vector instruction) by default.

To set a breakpoint or a tracepoint that triggers whenever a vector instruction is encountered in the program, enter the SET BREAK/VECTOR_INSTRUCTION or SET TRACE/VECTOR_INSTRUCTION command.

To cancel such breakpoints or tracepoints, enter the command CANCEL BREAK/VECTOR_INSTRUCTION or CANCEL TRACE/VECTOR_INSTRUCTION.

You can also set breakpoints and tracepoints on one or more specific vector instructions by using the /INSTRUCTION=(opcode[,...]) qualifier with the SET BREAK and SET TRACE commands. For example:

DBG> SET BREAK/INSTRUCTION=(VVADDL,VVLEQL)

To cancel such breakpoints and tracepoints, enter the CANCEL BREAK/INSTRUCTION or CANCEL TRACE/INSTRUCTION command.

16.2.3 Setting Watchpoints on Vector Registers

You can set watchpoints on the vector registers (V0 to V15) and on the vector control registers (VCR, VLR, and VMR). Section 16.3.1 identifies these registers and their built-in debugger symbols.

These watchpoints are treated like static watchpoints in that, once set, the watchpoint is active until you cancel it explicitly. In the following example, a watchpoint is set on register VCR:

DBG> SET WATCH %VCR

In the case of VMR and V0 to V15, you can set a watchpoint either on the register aggregate (that is, on all elements of the register), on an individual register element, or on a range of elements (a slice). Use the same technique that you use to set a watchpoint on an array variable. (See Section 3.4.)

For example, the following command sets a watchpoint that triggers if any element of register V5 changes:

DBG> SET WATCH %V5

The following command sets a watchpoint that triggers if element 37 of V2 changes (Fortran array syntax):

DBG> SET WATCH %V2(37)

The following command sets a watchpoint that triggers if any element of V2 in the range from element 5 to 13 changes:

DBG> SET WATCH %V2(5:13)

16.3 Examining and Depositing into Vector Registers

The following sections explain how to examine and deposit into the vector control registers (VCR, VLR, and VMR) and the vector registers (V0 to V15).

16.3.1 Specifying the Vector Registers and Vector Control Registers

The VAX architecture provides 16 vector registers (V0 to V15) and 3 vector control registers (VCR, VLR, and VMR). When referencing any of these registers in a debugger command, use the following built-in symbols (the register name preceded by a percent sign (%)):

Symbol	Description
%V0...%V15	Vector registers (V0...V15)
%VCR	Vector count register (VCR)
%VLR	Vector length register (VLR)
%VMR	Vector mask register (VMR)

As with all debugger register symbols, you can omit the percent sign (%) prefix if your program has not declared a symbol with the same name.

16.3.2 Examining and Depositing into the Vector Count Register

The vector count register (VCR) specifies the length of the offset vector generated by the IOTA instruction.

The value of VCR is an integer from 0 to 64. By default, the debugger treats VCR as a longword integer. You can deposit values greater than 64 into VCR, but the debugger issues a diagnostic message that the value is out of bounds in such cases.

The following command sequence shows how to manipulate the value of VCR:

DBG> EXAMINE %VCR 0\%VCR: 8 DBG> DEPOSIT %VCR = 4 DBG> EXAMINE %VCR 0\%VCR: 4 DBG>

16.3.3 Examining and Depositing into the Vector Length Register

The vector length register (VLR) limits the highest element of a vector register that is processed by a vector instruction. The value of VLR is an integer from 0 to 64. This value specifies the number of register elements that are processed, starting with element 0.

In the context of a debugging session, the current value of VLR limits the highest element of a vector register that you can access with an EXAMINE or DEPOSIT debugger command.

The following command sequence shows how to manipulate the value of VLR to examine different numbers of elements of the vector register V1:

DBG> EXAMINE %VLR 0\%VLR: 4 DBG> EXAMINE %V1 0\%V1 (0): 12 (1): 3 (2): 138 (3): 51 DBG> DEPOSIT %VLR = 3 DBG> EXAMINE %VLR 0\%VLR: 3 DBG> EXAMINE %V1 0\%V1 (0): 12 (1): 3 (2): 138 DBG>

You cannot access a register element outside the range from 0 to VLR--1. In the following example, the EXAMINE command specifies element 7 of register V1, which is out of bounds (Fortran array syntax):

DBG> EXAMINE %VLR 0\%VLR: 3 DBG> EXAMINE %V1(7) %DEBUG-E-VECTSUBRNG, vector register subscript out of bounds, bounds are 0..2 DBG>

By default, the debugger treats VLR as a longword integer. You can deposit values greater than 64 into VLR, but the debugger issues a diagnostic message that the value is out of bounds in such cases.

16.3.4 Examining and Depositing into the Vector Mask Register

The vector mask register (VMR) specifies a mask (a bit pattern) that a vector instruction uses to operate on only certain elements of a vector register operand. A masked vector instruction cannot operate on an element of a vector register that is masked by VMR.

VMR has 64 bits (1 quadword) numbered 0 to 63. Each bit corresponds to an element of a vector register. The value of a particular bit (0 or 1) determines whether the corresponding register element is operated on during a masked operation.

Masked operations are explained in Section 16.4.1 and Section 16.5. This section describes how to display and change the value of VMR.

To examine one or more specific elements (bits) of VMR, use the same technique that you use to examine an array variable. (See Section 4.2.3.)

For example, the output of the following command shows that bit 5 of VMR is set (Fortran array syntax):

DBG> EXAMINE %VMR(5) 0\%VMR(5): 1 DBG>

The following command displays the values of bits 4 to 6 of VMR. Bits 4 and 5 are set, and bit 6 is clear:

DBG> EXAMINE %VMR(4:6) 0\%VMR (4): 1 (5): 1 (6): 0 DBG>

By default, when you examine VMR without specifying subscripts, the debugger displays the value of the register as a quadword integer in hexadecimal format to reduce the size of the output display. For example:

DBG> EXAMINE %VMR 0\%VMR (0): 0FFFFFFF FFFFFFFF DBG>

By specifying the EXAMINE/BIN %VMR or EXAMINE %VMR(0:63) command, you can display the value of each bit of VMR in a 64-row array format.

As with an array variable, you can deposit a value into one bit of VMR at a time. For example:

DBG> EXAMINE %VMR(37) 0\%VMR(37): 1 DBG> DEPOSIT %VMR(37) = 0 DBG> EXAMINE %VMR(37) 0\%VMR(37): 0 DBG>

You can also deposit a quadword integer value into the entire aggregate by using the DEPOSIT/QUADWORD command. For example:

DBG> DEPOSIT/QUADWORD %VMR = %HEX 0FFFFF DBG> EXAMINE %VMR 0\%VMR (0): 00000000 000FFFFF DBG>

When specifying an element of VMR in a language expression, remember that VMR is an array of bits. You might have to temporarily set the language to one that allows bit operations, such as C or BLISS. For example:

DBG> SET LANGUAGE C DBG> DEFINE/VALUE K = 0 DBG> FOR I=0 TO 63 DO (IF %VMR[I] == 1 THEN (DEF/VAL K = K + 1))

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

4538PRO_032.HTML