HP 3000 Manuals

MPE Debug/Stack Dump Reference Manual

HOW TO DISPLAY AND MODIFY VALUES 

The symbol map produced during compilation by the MAP parameter is the
key to finding the location of most values.  For simple variables to
which values are assigned dynamically in the program, the map gives the
Q-relative location where the assigned value is to be stored.  (Refer to
items I1, I2, and I5 in the main program symbol map, Figure 3-1.)

If, however, the value has been assigned in a DATA statement, is a string
value or array, or has been passed from another program unit via a
program call, the Q-relative location in the symbol table is indirect,
that is, it contains the address where the value is located.  Indirect
addresses are followed by the letter I in the symbol map.  (Refer to
items C, C1, C2, I6, I7, I8, and J1, J2, J3 in the symbol maps, Figure
3-1.)

When the variable contains characters, the location is given as a byte
rather than a word address.  To find the word address, some simple
calculation is usually required.  (Refer to items C, C1, C2, and D1, D2
in the symbol maps, Figure 3-1.)

Data stored in COMMON is specifically indicated in the symbol map.  Its
location is not given as a Q-relative address but as an offset to the
beginning of COMMON. This, in turn, can be found from the PMAP listing
(item 2, Figure 3-2) where the start of COMMON is shown as a DB-relative
address.  (Refer to items I4, I5, and J4, J5 in the symbol maps, Figure
3-1.)  In the example, only unlabelled common is used; any labelled
common would be listed immediately following unlabelled common in the
maps.

DISPLAYING VALUES 

The location of values is usually specified relative to the display bases
DB or Q. To display values stored in a location relative to Q, enter:

     ?D Q+6        (Q is the display base, 6 the offset)

If you want to display more than one value, you must specify a count
separated by a comma from the offset.  For instance, to display the three
values stored in Q+ 6, Q+ 7, Q+ 8, enter:

     ?D Q+6,3 

All values are displayed as octal numbers by DEBUG unless you indicate
that you want them to be decimal (I) or ASCII (A). The mode indicator may
follow the offset separated by a comma or it may follow the count, also
separated by a comma.  For instance, to display the value at Q+ 6 as a
decimal number, enter:

     ?D Q+6,1 

Any values for which you know the DB relative location can be displayed
without specifying the display base.  For instance, to display the
contents of DB+ 31, you can simply enter:

     ?D 31 

So far, the display examples have used octal offsets.  If you want to
display the value in I3 stored at location Q+ 8, you must either indicate
that the offset is decimal, as:

     ?D Q+#8 

or you must enter the octal equivalent of the decimal number, as:

     ?D Q+10 

Usually, it is simpler to use the indicator # than to convert for
yourself.  Because the symbol map shows Q-relative locations as decimal
values, you must be very careful to use the decimal indicator for these
locations.  If you enter a decimal number in a DEBUG command without an
indicator, you will receive an error message.  If, however, the number
appears to DEBUG to be octal, but was meant to be decimal, a value may be
displayed from the wrong location or you may receive a BOUNDS violation.

Indirect Addressing.  To display a value stored in an indirect address,
follow the location with a colon (:).  For example:

     ?D Q+ 3:,3,I 

If a count and/or a mode indicator is included, it must be preceded by a
comma; the colon does not act as a delimiter.  (Refer to item 9, Figure
3-3 for an example displaying indirectly addressed values.)

When indirect addresses are used, DEBUG displays the DB-relative location
to which the Q-relative address points.

Byte Addressing.  The addresses of items containing characters are
specified as bytes rather than as words.  Thus, if you display the
contents of Q+ 1 (the address of character element C), this address is
given as the number of bytes relative to the start of DB rather than as
the number of words.  (Refer to item 10, Figure 3-3.)  To determine the
word address that you will need to display the character element, you
must divide this byte address by 2.  For example, to locate item C:

     ?D Q+1 
     Q+1             000004             (DB+ 4 bytes)
     ?D DB+ 4/2,A 
     DB+ 2        DB

Another method is to use the form that specifies the contents of a
location.  This allows you to perform the same function in fewer steps.
For example:

     ?D 'Q+ 1'/2,A 
     DB+ 2        DB

Note that only the first two characters of C are displayed.  In order to
display the entire character element, you must determine the number of
words per element, In line 3 of the sample FORTRAN program, CHARACTERS* 8
defines the length of each of the succeeding character elements as eight
characters.  To find the number of words per element, divide by 2.  In
this case, C, C1, and C2 require four words per element.  (If the number
of characters per element is an odd number, you must add one character
before dividing by two.)  This value gives you the count so you can
display the entire element.  For example, to display all of C:

     ?D DB+ 2,4,A      or     ?D 'Q+ 1'/2,4,A 

The characters in C1 are displayed in a similar manner.  (Refer to item
11, Figure 3-3.)

Array Addressing.  Note that the address of the array C2 is stored in the
same location (Q+2) as the address of C1.  This is because the FORTRAN
compiler has stored C1 in the unused zero element of array C2.  This is
done frequently in order to save space.  In order to display the first
element of array C2, you must add the number of words per element to the
word address calculated from the byte address stored in Q+ 2.  For
example, to display C2(1), enter:

     ?D DB+ 14/2+ 4,4,A          or     ?D 'Q+ 2'/2+4,4,A 

To display the element C2(3), enter:

     ?D DB+14/2+4*3,4,A       or         ?D 'Q+ 2'/2+ 4*3,4,A 

To display the entire array, enter as the count the number of words per
element multiplied by the total number of elements in the array.  In the
case of C2 with 3 4-word elements, enter:

     ?D DB+ 14/2+ 4,3*4,A 

If you wish, you can perform the calculations for count and expression 
and enter the results.  In performing these calculations, remember that
DEBUG, by default, uses octal values and any decimal values must be
preceded by the prefix #.

The displays resulting from addressing arrays and array elements are
shown in item 12, Figure 3-3.

A general formula for finding the word address of the start of an array
element is:

          B/2 + I*W

where:

B                is the byte address provided by DEBUG

I                is the index to the array element, i.e., 3 for C(3)

W                is the number of words per element.

Addressing Common.  The addresses for items in COMMON are shown in the
symbol table as relative to the start of COMMON. For example, items I4
and J4 are at location 0,I5, and J5 at location 1.  The DB-relative
address of the start of COMMON is given in the PMAP listing generated
during program preparation (Figure 3-2).  In this example, COMMON begins
at location 31.  Thus to display either I4 or J4, enter:

     ?D 31,I 

To display I5 or J5, enter

     ?D 32 

(Refer to item 13, Figure 3-3 for an example of displaying COMMON items.)

Figure 3-4 shows the Q-relative and DB-relative address for the data
items used in the sample FORTRAN program.


          Figure 3-4.  Layout of Items in Data Stack 

MODIFYING VALUES 

Values can be modified with the M command.  This command mirrors the D
command in its specification so that the methods for finding values to be
modified are the same as those described for finding values to be
displayed.

When the M command is executed, DEBUG prints the current value of each
item to be modified followed by :=.  You either enter a new value or
press return to retain the current value.  The values you enter are
assumed to be octal unless surrounded by quotes (ASCII) or preceded by #
(decimal).

When you specify a mode in the M command, this applies only to the
display of current values; it does not apply to the values you enter.
For example, if you want to modify the decimal value in Q+ 10, enter:

     ?M Q+ 10,I 

DEBUG prints the current value as a decimal number and asks for a new
value:

     Q+10        + 00010 :=

You must enter a value or else press return.  If you want to enter a
decimal value, precede the number with #, otherwise, an octal value
replaces the current value in Q+ 10.  (Refer to item 14 in Figure 3-3.)

If you want to modify more than one word, you enter a count:

     ?M Q+6,3 

DEBUG responds by printing the first value followed by :=.  When you have
responded, it prints the second value followed by :=.  This process
continues until all requested values have been displayed and modified.
(Refer to item 15 in Figure 3-3.)

If the value you enter is for some reason unacceptable, the request is
repeated until you enter an acceptable value.  In item 16, Figure 3-3,
the value entered is too large.  When a smaller value is entered, DEBUG
accepts it and issues the next prompt.

When character strings are to be modified, the string is displayed two
characters (one word) at a time.  New character values must be surrounded
by quotes.  (Refer to item 17, Figure 3-3.)


NOTE  Although your program code can be displayed (using DPB, DP, or
      DPL), it cannot be modified.  Any needed modifications should be
      made to the source code followed by a recompilation.


DISPLAYING AND MODIFYING REGISTERS 

A set of machine registers can be displayed and modified with the DR and
MR commands.  (Refer to the DR description in section II for a list of
these registers.)  In addition to the standard registers, four temporary
registers, numbered from 1 through 4, are provided by DEBUG. These
registers are particularly useful during modifications.  The temporary
registers are reset to zero at the start of each break so they cannot be
used to transfer values past a breakpoint.  (Refer to items 18 at Break
74 and then in Break 125, Figure 3-3.)

Suppose you want to set the value of three data items to 32767 (octal
77777), you can first set a temporary register to that value:

     ?MR,1 
     1=0:= 77777

Then use the register contents as a value for modification:

     ?M DB+ 26,3,I 
     DB+ 26               + 10000 := $1 
     DB+ 27               + 00700 := $1 
     DB+ 30               + 00800 := $1 

Note that the register must be preceded by a dollar sign ($) to indicate
that it is a register, not a digit.  (Refer to item 19, Figure 3-3.)

If you enter DR with no parameters, all available registers are
displayed.  (Refer to item 18 at Break 125, Figure 3-3.)  You can modify
all registers by entering MR with no parameters.  The MR description in
section II contains such an example.

Using the $ Command.  Values can be assigned to any register using the $
command.  For example, to assign the octal value 077777 to register 1,
enter:

     ?$1:= 77777 

The value can take the form of an expression.  Any numbers are assumed to
be octal unless preceded by a #, the contents of a location can be
specified by enclosing the address in apostrophes (i.e., 'DB+ 26'), and
an ASCII character can be specified by enclosing it in quotes.  Since
each register is one word in length, no more than two characters can be
assigned.

In each case, an octal value is assigned.  For example, to assign the
octal equivalent of the ASCII character A to register 4, enter:

     ?$4:="A" 

You can then display the register by entering:

     ?DR,4 
     4=101                (DEBUG displays octal value of register 4)

(Refer to items 20 and 22 in Figure 3-3 for examples using the $
command.)

Using the = Command.  The result of any expression can be displayed by
using the = command.  The expression itself can contain register contents
($Q), decimal values (#100), or location contents ('DB+ 51'), as well as
octal values.

For example, if you enter:

     ?=30*42 

DEBUG responds with the result of the calculation preceded by an equals
sign:

     = 1460

The result is always displayed in octal unless a mode parameter is
included.  For instance, if you want to display the contents of location
Q+ 26 in decimal, enter:

     ?= `Q+ 26',I 

DEBUG returns the decimal equivalent of the contents of this location:

     =-1

In the following example, the expression is expanded:

     ?=`Q+ 26'+ #20,I  (request contents of Q+ 26 plus 20 in decimal)
     =+19

Or you can find the decimal equivalent of an ASCII character as follows:

     ?="A",I 
     =+65

If the number entered is positive, DEBUG performs logical arithmetic.  If
the number is negative, DEBUG performs integer arithmetic.

Refer to item 21, Figure 3-3, for examples using the = command.)

DISPLAYING CODE 

If you want an octal dump of a portion of your program code, you can use
the DP, DPB, or DPL commands.  (You can also see the octal code generated
by a compiler by running the program DECOMP or by including the CODE
parameter in the $CONTROL command when you compile.  In both these cases,
the entire program is dumped.)  DP, DPB, and DPL are variations on the D
command that specify a program area to be used as the display base.  DP
displays code relative to the program counter (P) that marks your current
instruction.

DPB displays code relative to the program base (PB). DPL displays code
relative to the program limit (PL). The code in the currently executing
program unit starts at location PB. The program limit PL marks the end of
the segment transfer table (STT) that follows each segment of code.
(Refer to Figure 3-5 for a diagram of the code layout.)

As with the D command, you can specify offsets, a count, and the mode of
the display.  Since you will usually want an octal display, the mode is
omitted from the examples in Figure 3-5.

In item 1, Figure 3-5, twenty words of octal code at the current
P-counter location are displayed.  These words are the translation by the
FORTRAN compiler of line 9 in the sample program (DISPLAY C1,C2).  The
resulting machine instructions start at the entry point of program MAIN,
location 172 relative to PB. Thus, you could achieve the same result by
entering:

     ?DPB+ 172,20 

If you specify an offset in a DP command, it is relative to the
P-counter, as:

     ?DP+20                (20 words past P)

Suppose the P-counter is set to location 172, then the same result is
achieved by entering:

     ?DPB+ 172+ 20 

The resulting display is illustrated in item 2, Figure 3-5.


          Figure 3-5.  Display Code Locations Example 

As shown in item 3, Figure 3-5, if you want to display the contents of
location PB+ 0, enter:

     DPB

PL, the program limit, is at the end of the area allocated to your
program segment and thus can have only a negative offset.  As shown in
item 4, Figure 3-5, PL-1 contains the value zero.  This is the last item
in the stack transfer table and points to the entry point to SUBR. PL-2
is displayed as 172, the entry point to program MAIN. (Refer to the
numbers under STT in the PMAP listing in Figure 3-2.  These numbers
indicate the value to be subtracted from PL to determine values in the
segment transfer table.)  Note that the location pointed to by PL always
contains the length of the STT in the right byte.

DISPLAYING STACK MARKERS 

The T command allows you to trace stack markers through a series of
nested subroutines (FORTRAN) or nested procedures (SPL). When T is
executed, it displays for each routine, the displacement of Q to the
initial Q, the relative P location and the logical segment number (LCST)
to which control returns upon exit.  The trace is useful particularly
when you have a number of nested subroutines and you want to find out
which calls which, where they return, and the displacement of Q for each.

For example, if T is entered at a breakpoint in the main program of the
sample FORTRAN program used in this manual, the following values are
displayed:

     ?T 
     Q-0          ,LCST=S132,P=0

The current displacement of Q from initial Q is zero; the logical code
segment to which control returns, should you exit from the program other
than through TERMINATE', is system segment library segment 132; the P
register is zero, the initial setting for the start of the entire
program.

If you enter T in a subroutine, the display shows the stack markers for
the currently executing routine at the top of the list, followed in turn
by each nested routine back to the main program.  In this case, the main
program T display follows that of the subroutine.  For example:

     ?T 
     Q-0         ,LCST=0   ,P=272 (SUBROUT marker)
     Q-21        ,LCST=S132,P=0   (MAIN marker)

In the subroutine, the displacement from the current Q is zero, the
logical code segment to which control returns should you exit from the
program other than through TERMINATE', is system segment library segment
132; the P register is zero, the initial setting for the entire program.
The display for the main program is unchanged except for the displacement
of initial Q which is shown as 21 locations less than the current Q.

T traces only the subroutines that have led to execution of the current
routine, displaying one line for each.  Thus T displays only one line for
the main program; and in the sample FORTRAN program, a maximum of two
lines are displayed by T. If, however, this subroutine had called
another, the T executed in a breakpoint to that routine would display
three lines.

MPE/iX 5.0 Documentation