HP OpenVMS systems documentation

The following examples show use of the EXAMINE, DEPOSIT, and EVALUATE commands with some integer, real, and Boolean types.

Examine a list of three integer variables:

DBG> EXAMINE WIDTH, LENGTH, AREA SIZE\WIDTH: 4 SIZE\LENGTH: 7 SIZE\AREA: 28 DBG>

Deposit an integer expression:

DBG> DEPOSIT WIDTH = CURRENT_WIDTH + 10 DBG>

The debugger checks that a value to be assigned is compatible with the data type and dimensional constraints of the variable. The following example shows an attempt to deposit an out-of-bounds value (X was declared as a positive integer):

DBG> DEPOSIT X = -14 %DEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT DBG>

If you try to mix numeric types (integer and real of varying precision) in a language expression, the debugger generally follows the rules of the language. Strongly typed languages do not allow much, if any, mixing. With some languages, you can deposit a real value into an integer variable. However, the real value is converted into an integer. For example:

DBG> DEPOSIT I = 12345 DBG> EXAMINE I MOD3\I: 12345 DBG> DEPOSIT I = 123.45 DBG> EXAMINE I MOD3\I: 123 DBG>

If numeric types are mixed in an expression, the debugger performs type conversion as discussed in Section 4.1.6.2. For example:

DBG> DEPOSIT Y = 2.356 ! Y is of type G_floating point. DBG> EXAMINE Y MOD3\Y: 2.35600000000000 DBG> EVALUATE Y + 3 5.35600000000000 DBG> DEPOSIT R = 5.35E3 ! R is of type F_floating point. DBG> EXAMINE R MOD3\R: 5350.000 DBG> EVALUATE R*50 267500.0 DBG> DEPOSIT I = 22222 DBG> EVALUATE R/I 0.2407524 DBG>

The next example shows some operations with Boolean variables. The values TRUE and FALSE are assigned to the variables WILLING and ABLE, respectively. The EVALUATE command then obtains the logical conjunction of these values.

DBG> DEPOSIT WILLING = TRUE DBG> DEPOSIT ABLE = FALSE DBG> EVALUATE WILLING AND ABLE False DBG>

4.2.2 ASCII String Types

When displaying an ASCII string value, the debugger encloses it within quotation marks (") or apostrophes ('), depending on the language syntax. For example:

DBG> EXAMINE EMPLOYEE_NAME PAYROLL\EMPLOYEE_NAME: "Peter C. Lombardi" DBG>

To deposit a string value (including a single character) into a string variable, you must enclose the value in quotation marks (") or apostrophes ('). For example:

DBG> DEPOSIT PART_NUMBER = "WG-7619.3-84" DBG>

If the string has more ASCII characters (1 byte each) than can fit into the location denoted by the address expression, the debugger truncates the extra characters from the right and issues the following message:

%DEBUG-I-ISTRTRU, string truncated at or near DEPOSIT

If the string has fewer characters, the debugger pads the remaining characters to the right of the string by inserting ASCII space characters.

4.2.3 Array Types

You can examine an entire array aggregate, a single indexed element, or a slice (a range of elements). However, you can deposit into only one element at a time. The following examples show typical operations with arrays.

The following command displays the values of all the elements of the array variable ARRX, a one-dimensional array of integers:

DBG> EXAMINE ARRX MOD3\ARRX (1): 42 (2): 17 (3): 278 (4): 56 (5): 113 (6): 149 DBG>

The following command displays the value of element 4 of array ARRX (depending on the language, parentheses or brackets are used to denote indexed elements):

DBG> EXAMINE ARRX(4) MOD3\ARRX(4): 56 DBG>

The following command displays the values of all the elements in a slice of ARRX. This slice consists of the range of elements from element 2 to element 5:

DBG> EXAMINE ARRX(2:5) MOD3\ARRX (2): 17 (3): 278 (4): 56 (5): 113 DBG>

In general, a range of values to be examined is denoted by two values separated by a colon (value1:value2). Depending on the language, two periods (..) can be used instead of a colon.

You can deposit a value to only a single array element at a time (you cannot deposit to an array slice or an entire array aggregate with a single DEPOSIT command). For example, the following command deposits the value 53 into element 2 of ARRX:

DBG> DEPOSIT ARRX(2) = 53 DBG>

The following command displays the values of all the elements of array REAL_ARRAY, a two-dimensional array of real numbers (three per dimension):

DBG> EXAMINE REAL_ARRAY PROG2\REAL_ARRAY (1,1): 27.01000 (1,2): 31.00000 (1,3): 12.48000 (2,1): 15.08000 (2,2): 22.30000 (2,3): 18.73000 DBG>

The debugger issues a diagnostic message if you try to deposit to an index value that is out of bounds. For example:

DBG> DEPOSIT REAL_ARRAY(1,4) = 26.13 %DEBUG-I-SUBOUTBND, subscript 2 is out of bounds, value is 4, bounds are 1..3 DBG>

In the previous example, the deposit operation was executed because the diagnostic message is of I level. This means that the value of some array element adjacent to (1,3), possibly (2,1) might have been affected by the out-of-bounds deposit operation.

To deposit the same value to several components of an array, you can use a looping command such as FOR or REPEAT. For example, assign the value RED to elements 1 to 4 of the array COLOR_ARRAY:

DBG> FOR I = 1 TO 4 DO (DEPOSIT COLOR_ARRAY(I) = RED) DBG>

You can also use the built-in symbols (.) and (^) to step through array elements, as explained in Section 4.1.8.

4.2.4 Record Types

You can examine an entire record aggregate, a single record component, or several components. However, you can deposit into only one component at a time. The following examples show typical operations with records.

The following command displays the values of all the components of the record variable PART:

DBG> EXAMINE PART INVENTORY\PART: ITEM: "WF-1247" PRICE: 49.95 IN_STOCK: 24 DBG>

The following command displays the value of component IN_STOCK of record PART (general syntax):

DBG> EXAMINE PART.IN_STOCK INVENTORY\PART.IN_STOCK: 24 DBG>

The following command displays the value of the same record component using COBOL syntax (the language must be set to COBOL):

DBG> EXAMINE IN_STOCK OF PART INVENTORY\IN_STOCK of PART: IN_STOCK: 24 DBG>

The following command displays the values of two components of record PART:

DBG> EXAMINE PART.ITEM, PART.IN_STOCK INVENTORY\PART.ITEM: "WF-1247" INVENTORY\PART.IN_STOCK: 24 DBG>

The following command deposits a value into record component IN_STOCK:

DBG> DEPOSIT PART.IN_STOCK = 17 DBG>

4.2.5 Pointer (Access) Types

You can examine the entity designated (pointed to) by a pointer variable and deposit a value into that entity. You can also examine a pointer variable.

For example, the following Pascal code declares a pointer variable A that designates a value of type real:

. . . TYPE T = ^REAL; VAR A : T; . . .

The following command displays the value of the entity designated by the pointer variable A:

DBG> EXAMINE A^ MOD3\A^: 1.7 DBG>

In the following example, the value 3.9 is deposited into the entity designated by A:

DBG> DEPOSIT A^ = 3.9 DBG> EXAMINE A^ MOD3\A^: 3.9 DBG>

When you specify the name of a pointer variable with the EXAMINE command, the debugger displays the memory address of the object it designates. For example:

DBG> EXAMINE/HEXADECIMAL A SAMPLE\A: 0000B2A4 DBG>

4.3 Examining and Depositing Instructions

The debugger recognizes address expressions that are associated with instructions. This enables you to examine and deposit instructions using the same basic techniques as with variables.

When debugging at the instruction level, you might find it convenient to first enter the following command. It sets the default step mode to stepping by instruction:

DBG> SET STEP INSTRUCTION DBG>

There are other step modes that enable you to execute the program to specific kinds of instructions. You can also set breakpoints to interrupt execution at these instructions.

In addition, you can use a screen-mode instruction display (see Section 7.4.4) to display the actual decoded instruction stream of your program.

4.3.1 Examining Instructions

If you specify an address expression that is associated with an instruction in an EXAMINE command (for example, a line number), the debugger displays the first instruction at that location. You can then use the period (.), Return key, and circumflex (^) to display the current, next, and previous instruction (logical entity), as described in Section 4.1.8.

For example, on Alpha processors:

DBG> EXAMINE %LINE 12 MOD3\%LINE 12: BIS R31,R31,R2 DBG> EXAMINE MOD3\%LINE 12+4: BIS R31,R2,R0 ! Next instruction DBG> EXAMINE MOD3\%LINE 12+8: ADDL R31,R0,R0 ! Next instruction DBG> EXAMINE ^ MOD3\%LINE 12+4: BIS R31,R2,R0 ! Previous instruction DBG>

Line numbers, routine names, and labels are symbolic address expressions that are associated with instructions. In addition, instructions might be stored in various other memory addresses and in certain registers during the execution of your program.

The program counter (PC) is the register that contains the address of the next instruction to be executed by your program. The command EXAMINE .%PC displays that instruction. The period (.), when used directly in front of an address expression, denotes the contents of operator---that is, the contents of the location designated by the address expression. Note the following distinction:

• EXAMINE %PC displays the current PC value, namely the address of the next instruction to be executed.
• EXAMINE .%PC displays the contents of that address, namely the next instruction to be executed by the program.

On VAX processors, you can use the /OPERANDS qualifier to control the amount of information displayed when you enter the EXAMINE .%PC command:

DBG> EXAMINE .%PC MOD3\%LINE 12: MOVL B^12(R11),R1 DBG> EXAMINE/OPERANDS .%PC MOD3\%LINE 12: MOVL B^12(R11),R1 B^12(R11) MOD3\K (address 1196) contains 1 R1 R1 contains 8 DBG> EXAMINE/OPERANDS=FULL .%PC MOD3\%LINE 12: MOVL B^12(R11),R1 B^12(R11) R11 contains MOD3\N (address 1184), B^12(1184) evaluates to MOD3\K (address 1196), which contains 1 R1 R1 contains 8 DBG>

On VAX processors, use the /OPERANDS qualifier only when examining the current PC instruction. The information might not be reliable if you specify other locations. The command SET MODE [NO]OPERANDS enables you to control the default behavior of the EXAMINE .%PC command.

As shown in the previous examples, the debugger knows whether an address expression is associated with an instruction. If it is, the EXAMINE command displays that instruction (you do not need to use the /INSTRUCTION qualifier). You use the /INSTRUCTION qualifier to display the contents of an arbitrary program location as an instruction---that is, the command EXAMINE/INSTRUCTION causes the debugger to interpret and format the contents of any program location as an instruction (see Section 4.5.2).

When you examine consecutive instructions in a MACRO-32 program, the debugger might misinterpret data as instructions if storage for the data is allocated in the middle of a stream of instructions. The following example shows this problem. It shows some MACRO-32 code with two longwords of data storage allocated directly after the BRB instruction at line 7 (line numbers have been added to the example for clarity).

module TEST 1: .TITLE TEST 2: 3: TEST$START:: 4: .WORD 0 5: 6: MOVL #2,R2 7: BRB LABEL_2 8: 9: .LONG ^X12345 10: .LONG ^X14465 11: 12: LABEL_2: 13: MOVL #5,R5 14: 15: .END TEST$START

The following EXAMINE command displays the instruction at the start of line 6:

DBG> EXAMINE %LINE 6 TEST\TEST$START\%LINE 6: MOVL S^#02,R2 DBG>

The following EXAMINE command correctly interprets and displays the logical successor entity as an instruction at line 7:

DBG> EXAMINE TEST\TEST$START\%LINE 7: BRB TEST\TEST$START\LABEL_2 DBG>

However, the following three EXAMINE commands incorrectly interpret the three logical successors as instructions:

DBG> EXAMINE TEST\TEST$START\%LINE 7+2: MULF3 S^#11.00000,S^#0.5625000,S^#0.5000000 DBG> EXAMINE %DEBUG-W-ADDRESSMODE, instruction uses illegal or undefined addressing modes TEST\TEST$START\%LINE 7+6: MULD3 S^#0.5625000[R4],S^#0.5000000,@W^5505(R0) DBG> EXAMINE TEST$START+12: HALT DBG>

4.3.2 Depositing Instructions (VAX Only)

On VAX processors, you can deposit instructions as well as examine them. Use the following DEPOSIT command syntax:

DEPOSIT/INSTRUCTION address-expression = "language-expression"

You must enclose language-expression (an assembly-language instruction) in either quotation marks or apostrophes. The /INSTRUCTION qualifier indicates that the delimited string is an instruction and not an ASCII string. Or, if you plan to deposit several instructions, you can first enter the SET TYPE/OVERRIDE INSTRUCTION command (see Section 4.5.2). You then do not need to use the /INSTRUCTION qualifier on the DEPOSIT command.

Instructions occupy different numbers of bytes depending on their operands. When depositing instructions of arbitrary lengths into successive memory locations, use the logical successor operator (Return key) to establish the next unoccupied location where an instruction can be deposited. The following example shows the technique:

DBG> SET TYPE/OVERRIDE/INST ! Set the default type to instruction. DBG> DEPOSIT 730 = "MOVB #77, R1"! Deposit an instruction beginning at address 730. DBG> EXAMINE . ! Examine the current entity to verify the deposit. 730: MOVB #77,R1 DBG> EXAMINE [Return] ! Make the logical successor the new current entity. 734: HALT DBG> DEPOSIT . = "MOVB #66, R2" ! Deposit the next instruction. DBG> EXAMINE . ! Display and verify the deposit. 734: MOVB #66,R2 DBG>

When you replace an instruction, be sure that the new instruction, including operands, is the same length in bytes as the old instruction. If the new instruction is longer, you cannot deposit it without overwriting, which will destroy the next instruction. If the new instruction occupies fewer bytes of memory than the old one, you must deposit NOP instructions (instructions that cause no operation) in bytes of memory left unoccupied after the replacement. The debugger does not warn you if an instruction you are depositing will overwrite a subsequent instruction, nor does it remind you to fill in vacant bytes of memory with NOPs.

The following example shows how to replace an instruction with an instruction of equal length:

DBG> SET STEP INSTRUCTION ! Step by instruction. DBG> STEP stepped to 1584: PUSHAL (R11) DBG> STEP stepped to 1586: CALLS #1,L^2224 ! Instruction to be replaced. DBG> EXAMINE .%PC 1586: CALLS #1,L^2224 DBG> EXAMINE [Return] ! Determine start of next 1593: CALLS #0,L^2216 ! instruction (1593). DBG> DEPOSIT/INST 1586 = "CALLS #2,L^2224" ! Deposit new instruction. DBG> EXAMINE . ! Verify that instruction 1586: CALLS #2,L^2224 ! is deposited. DBG> EXAMINE [Return] ! Verify that the next 1593: CALLS #0,L^2216 ! instruction is unchanged. DBG>

4.4 Examining and Depositing into Registers

The EXAMINE command displays contents of any register that is accessible in your program. You can use the DEPOSIT command to change the contents of these registers. The number and type of registers vary for each OpenVMS platform, as described in the following sections.

4.4.1 Examing and Depositing into VAX Registers

The VAX architecture provides 16 general registers and 18 vector registers, some of which are used for temporary address and data storage. Table 4-1 identifies the debugger built-in symbols that refer to VAX registers.

Table 4-1 Debugger Symbols for VAX Registers

Symbol	Description
VAX General Registers
%R0...%R11	General-purpose registers (R0...R11)
%AP (%R12)	Argument pointer (AP)
%FP (%R13)	Frame pointer (FP)
%SP (%R14)	Stack pointer (SP)
%PC (%R15)	Program counter (PC)
%PSL	Processor status longword (PSL)
VAX Vector Registers and Vector Control Registers
%V0...%V15	Vector registers V0...V15
%VCR	Vector count register
%VLR	Vector length register
%VMR	Vector mask register

On VAX processors:

• You can omit the percent sign (%) prefix if your program has not declared a symbol with the same name.
• You can examine the contents of all the registers. You can deposit values into all the registers except for SP. Use caution when depositing values into FP.

Processor Status Longword (VAX Only)

On VAX processors, the processor status longword (PSL) is a register whose value represents a number of processor state variables. The first 16 bits of the PSL (referred to separately as the processor status word, or PSW) contain unprivileged information about the current processor state. The values of these bits can be controlled by a user program. The latter 16 bits of the PSL, bits 16 to 31, contain privileged information and cannot be altered by a user-mode program.

The following example shows how to examine the contents of the PSL:

DBG> EXAMINE %PSL MOD3\PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C n n n n mode mode 1v n n n n n n n n DBG>

See the VAX Architecture Handbook for complete information about the PSL, including the values of the various bits.

You can also display the information in the PSL in other formats. For example:

DBG> EXAMINE/LONG/HEX %PSL MOD3\%PSL: 03C00010 DBG> EXAMINE/LONG/BIN %PSL MOD3\%PSL: 00000011 11000000 00000000 00010000 DBG>

The command EXAMINE/PSL displays the value at any location in PSL format. This is useful for examining saved PSLs on the call stack.

To disable all conditions in the PSL, clear bits 0 to 15 with the following DEPOSIT command:

DBG> DEPOSIT/WORD PSL = 0 DBG> EXAMINE/PSL MOD3\PSL: CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV T N Z V C 0 0 0 0 USER USER 0 0 0 0 0 0 0 0 0 DBG>