HP 3000 Manuals HP 3000 Manuals
B (break)
Debug only
Privileged Mode: BA, BAX, BS
Break. Sets a breakpoint.
Syntax
B logaddr [:pin|@] [count] [loud] [cmdlist] Program
BG logaddr [:pin|@] [count] [loud] [cmdlist] Group library
BP logaddr [:pin|@] [count] [loud] [cmdlist] Account library
BLG logaddr [:pin|@] [count] [loud] [cmdlist] Logon group lib
BLP logaddr [:pin|@] [count] [loud] [cmdlist] Logon account lib
BS logaddr [:pin|@] [count] [loud] [cmdlist] System library
BU fname logaddr [:pin|@] [count] [loud] [cmdlist] User library
BV virtaddr [:pin|@] [count] [loud] [cmdlist] Virtual address
BA cmabsaddr [:pin|@] [count] [loud] [cmdlist] Absolute CST
BAX cmabsaddr [:pin|@] [count] [loud] [cmdlist] Absolute CSTX
The various forms of the BREAK command are used to set process-local and
global (system-wide) breakpoints. Only users with privileged mode (PM)
capability are allowed to set global breakpoints. Users without PM
capability may only specify PINs that are descendant processes (any
generation) of the current PIN.
Setting a breakpoint for another process is implemented such that it
appears the target process set the breakpoint itself. Therefore, when
the target process encounters the breakpoint, it enters Debug with its
output directed to the LDEV associated with the target process.
If a breakpoint is set in CM code that has been translated by the Object
Code Translator (OCT), Debug automatically sets a NM breakpoint in the
closest previous corresponding translated code node point. If more than
one CM breakpoint is set within a given node, only one NM breakpoint is
set; however, a counter is incremented so the number of corresponding CM
breakpoints can be tracked. If a NM breakpoint is set in translated
code, no corresponding CM emulated breakpoint is set. Refer to appendix
C for a discussion of CM object code translation, node points, and
breakpoints in translated CM code.
Parameters
logaddr A full logical code address (LCPTR) specifies three
necessary items:
* The logical code file (PROG, GRP, SYS,, and so on)
* NM: the virtual space ID number (SID)
CM: the logical segment number
* NM: the virtual byte offset within the space
CM: the word offset within the code segment
Logical code addresses can be specified in various
levels of detail:
* As a full logical code pointer (LCPTR):
B procname+20 procedure name lookups return
LCPTRs
B pw+4 predefined ENV variables of type
LCPTR
B SYS(2.200) explicit coercion to a LCPTR
type
* As a long pointer (LPTR):
B 23.2644 sid.offset or seg.offset
The logical file is determined based on the command
suffix, for example:
B implies PROG
BG implies GRP
BS implies SYS
* As a short pointer (SPTR):
B 1024 offset only
For NM, the short pointer offset is converted to a long
pointer using the function STOLOG, which looks up the
SID of the loaded logical file. This is different from
the standard short to long pointer conversion, STOL,
which is based on the current space registers (SRs).
For CM, the current executing logical segment number and
the current executing logical file are used to build a
LCPTR.
The search path used for procedure name lookups is based
on the command suffix letter:
B Full search path:
NM: PROG, GRP, PUB, USER(s), SYS
CM: PROG, GRP, PUB, LGRP, LPUB, SYS
BG Search GRP, the group library.
BP Search PUB, the account library.
BLG Search LGRP, the logon group library.
BLP Search LPUB, the logon account library.
BS Search SYS, the system library.
BU Search USER, the user library.
For a full description of logical code addresses, refer
to the section "Logical Code Addresses" in chapter 2.
fname The file name of the NM user library. Since multiple NM
libraries can be bound with the XL= option on a RUN
command,
:run nmprog; xl=lib1,lib2.testgrp,lib3
it is necessary to specify the desired NM USER library.
For example,
BU lib1 204c
BU lib2.testgrp test20+1c0
If the file name is not fully qualified, the following
defaults are used:
Default account: the account of the program file.
Default group: the group of the program file.
virtaddr The virtual address of NM code.
Virtaddr can be a short pointer, a long pointer, or a
full logical code pointer.
Short pointers are implicitly converted to long pointers
using the STOL (short to long) function.
cmabsaddr A full CM absolute code address specifies three
necessary items:
* Either the CST or the CSTX.
* The absolute code segment number.
* The CM word offset within the code segment.
Absolute code addresses can be specified in two ways:
* As a long pointer (LPTR)
BA 23.2644 Implicit CST 23.2644
BAX 5.3204 Implicit CSTX 5.3204
* As a full absolute code pointer (ACPTR)
BA CST(2.200) Explicit CST
coercion
BAX CSTX(2.200) Explicit CSTX
coercion
BAX logtoabs(prog(1.20)) Explicit absolute
conversion
The search path used for procedure name lookups is based
on the command suffix letter:
BA GRP, PUB, LGRP, LPUB, SYS
BAX PROG
pin | @ The process identification number (PIN) of the process
for which the breakpoint is to be set. If omitted, the
breakpoint is set for the current process. The
character "@" can be used to set a global breakpoint at
which all processes stop.
count Count has a twofold meaning: it specifies a break every
nth time the breakpoint is encountered, and it is used
to set permanent/temporary breakpoints. If count is
positive, the breakpoint is permanent. If count is
negative, the breakpoint is temporary and is deleted as
soon as the process breaks at it. For example, a count
of 4 means break every fourth time the breakpoint is
encountered; a count of -4 means break on the fourth
time, and immediately delete the breakpoint. If count
is omitted, +1 is used, which breaks every time,
permanently.
loud Either LOUD or QUIET. If QUIET is selected the debugger
does not print out a message when the breakpoint is hit.
This is useful for performing a command list a great
number of times before stopping without being inundated
with screen after screen of breakpoint messages. These
keywords may be abbreviated as desired. The default is
LOUD.
cmdlist A single Debug command or a list of Debug commands that
are executed immediately when the breakpoint is
encountered. Command lists for breakpoints are limited
to 80 characters. (If this is too few characters, write
a macro and have the command list invoke the macro.)
Cmdlist has the form:
CMD1
{ CMD1; CMD2; CMD3;...}
NM Code Examples
$nmdebug > loadinfo
nm PROG GRADES.DEMO.TELESUP SID = $115
parm = #0 info = ""
nm GRP XL.DEMO.TELESUP SID = $118
nm USER XL.PUB.SYS SID = $f4
nm SYS NL.PUB.SYS SID = $a
cm SYS SL.PUB.SYS
Show the list of loaded files and the space into which they are loaded.
$nmdebug > b PROGRAM+270
added: NM [1] PROG 115.00006a8c PROGRAM+$270
Set a breakpoint at the procedure PROGRAM plus an offset of $270. This
corresponds to a statement in the outer block of the program being
debugged. The name and offset were determined by looking at the
statement map produced by the Pascal compiler (all language compilers
produce similar maps). The expression evaluator found the procedure
PROGRAM in the program file.
$nmdebug > b 6a90
added: NM [2] PROG 115.00006a90 PROGRAM+$274
Break in the program file at offset $6a90. Remember that when only an
offset is specified as a logical address for this command, the space
(SID) for the program file is assumed. A STOLOG conversion (not STOL)
with the "prog" selector is used to accomplish this.
$nmdebug > b processstudent,,, {wl "Processing #" r26:"d";c}
added: NM [3] PROG 115.00005d24 processstudent
Set a breakpoint at the procedure called processstudent and provide a
command list to be executed each time the breakpoint is encountered. In
this example, we know that the student number being processed is passed
to the routine in general register 26. Each time the routine is entered,
Debug prints the student number and automatically continue execution of
the process.
$nmdebug > b nmaddr("processstudent.highscore"),-1
added: NM T[4] PROG 115.00005b50 processstudent.highscore
Set a breakpoint at the nested procedure highscore that is contained
in the level 1 procedure processstudent. The NMADDR function
is used to specify the breakpoint address since the expression
parent_proc.nested_proc would not have been recognized by the expression
evaluator (a.b implies space.offset, for example, a long pointer). This
breakpoint is a temporary breakpoint, which is automatically deleted
after it is encountered. T[4] indicates a temporary breakpoint with
index number 4.
$nmdebug > b average
added: NM [5] GRP 118.00015c88 average
$nmdebug > bg average+4
added: NM [6] GRP 118.00015c8c average+$4
$nmdebug > b grp(average)+8
added: NM [7] GRP 118.00015c90 average+$8
$nmdebug > bs average
Missing or invalid logical code address. (error #1741)
Set a breakpoint at the procedure average. Notice that the routine was
found in the group (GRP) library. The B command starts searching for
symbol names in the program file and continues through all of the loaded
library files until a match is found. The second example uses the BG
command to explicitly restrict the search for symbol names to the group
library. The third example shows how the coercion function GRP is used
to restrict procedure name lookups to the group library. In the fourth
example above, the BS command is used to restrict the search for
procedure names to the system library. The routine average was not found
in the system library, and so an error was generated.
$nmdebug > dc pc
GRP $118.15c88
00015c88 average 0000400e BREAK (nmdebug bp)
$nmdebug > wl r2
$15c77
$nmdebug > wl sr4
$118
$nmdebug > b r2
The virtual address specified does not exist. (error #1407)
$nmdebug > errl
$28: The virtual address specified does not exist. (error #1407)
$28: The virtual address does not exist. (error #6017)
$28: VADDR= 115.15c74
$28: A pointer was referenced that contained a virtual address outside
of the bounds of an object.
The above example starts by showing that Debug has stopped in the group
library in the average procedure. The B command was used to set a
breakpoint at the address specified in r2, and this caused the command to
fail. Recall that the B command assumes that the breakpoint is to be set
in the program file when only an offset is provided. The SID for the
program file ($115) is retrieved, and a long pointer is generated by
performing a STOLOG conversion. The resulting address ($115.$15c74) does
not exist in the program file; thus an error is generated.
$nmdebug > bg r2
added: NM [3] GRP 118.00015c74 ?average+$8
$nmdebug > bd 3
deleted: NM [3] GRP 118.00015c74 ?average+$8
The BG command is used to set a breakpoint at the offset indicated by the
contents of general register 2. This command assumes the breakpoint is
to be set in the group library. The SID for the group library ($118) is
retrieved, and a long pointer is generated by performing a STOLOG
conversion. The resulting address ($118.$15c74) is a valid group library
virtual address, and so the breakpoint is set. The address corresponds
to the export stub for the average procedure. Refer to the Procedure
Calling Conventions Reference Manual (09740-90015) for an explanation of
the use and purpose of export stubs.
$nmdebug > bv r2
added: NM [3] GRP 118.00015c74 ?average+$8
$nmdebug > bd 3
deleted: NM [3] GRP 118.00015c74 ?average+$8
The BV command is used to set a breakpoint at the offset indicated by
general register 2. Unlike the above example, the offset in r2 is
converted to a long pointer by performing a STOL conversion. The
resulting address (sr4.r2 = $118.$15c74) is a valid group library virtual
address, and so the breakpoint is set. A full long pointer is always
valid, so the command b 118.r2 also results in the breakpoint being set.
$nmdebug > b P_INIT_HEAP
added: NM [8] USER f4.0012f2b8 p_heap:P_INIT_HEAP
$nmdebug > bu xl.pub.sys U_INIT_TRAPS
added: NM [9] USER f4.001f9188 U_INIT_TRAPS
The above example sets a breakpoint at the procedure P_INIT_HEAP. The
routine was found in one of the loaded user libraries (this process only
has one loaded user library). The BU command is used in the second
example to specify which user library to search when looking for
procedure names. The U_INIT_TRAPS routine was found in the user library
XL.PUB.SYS and a breakpoint was set.
$nmdebug > bs ?FREAD,#100,q,{wl "Read another 100 records";c}
added: NM |10| SYS a.0074aa34 FREAD
Set a breakpoint at the FREAD intrinsic. Every #100 times the routine is
called, stop and print out a message. The QUIET option is specified so
this operation produces no extra terminal output. The vertical bars in
the breakpoint notation indicates that the process does not stop the next
time the breakpoint is encountered, since the count is not yet exhausted.
$nmdebug > bs trap_handler:@,,,{trace ,ism}
added: NM @[1] SYS a.00668684 trap_handler
Set a system-wide breakpoint in the trap handler. This routine is in the
system NL. When the breakpoint is hit, perform a stack trace. The "@"
indicates that the breakpoint is a global breakpoint.
$nmdebug > b pw+4
added: NM [11] PROG $115.00006984 initstudentrecord+14
Break at the address specified by adding 4 to the address of the first
line in the program window. In this case, the program window must have
been aimed at initstudentrecord+10.
$nmdebug > bl
NM [1] PROG 115.00006a8c PROGRAM+$270
NM [2] PROG 115.00006a90 PROGRAM+$274
NM [3] PROG 115.00005d24 processstudent
cmdlist: {wl "Processing #" r26:"d";c}
NM T[4] PROG 115.00005b50 processstudent.highscore
NM [5] GRP 118.00015c88 average
NM [6] GRP 118.00015c8c average+$4
NM [7] GRP 118.00015c90 average+$8
NM [8] USER f4.0012f2b8 p_heap:P_INIT_HEAP
NM [9] USER f4.001f9188 U_INIT_TRAPS
NM |10| SYS a.0074aa34 FREAD
[QUIET] count: 0/64 cmdlist: {wl "Read another 100 records";c}
NM [11] PROG $115.00006984 initstudentrecord+14
NM @[1] SYS a.00668684 trap_handler
[QUIET] cmdlist: {trace ,ism}
Now list all of the breakpoints just set above.
CM Code Examples
%cmdebug > loadinfo
cm PROG GRADES.DEMOCM.TELESUP
parm = #0 info = ""
cm GRP SL.DEMOCM.TELESUP
cm SYS SL.PUB.SYS
nm SYS NL.PUB.SYS SID = $a
Show the list of all currently loaded files.
%cmdebug > b ?processstudent
added: CM [1] PROG % 0.1665 ?PROCESSSTUDENT
Set a breakpoint at the entry point (indicated by the ? character) of
the procedure PROCESSSTUDENT. The expression evaluator found the
procedure in the program file in logical segment zero, at an offset of
%1665 CM words from the start of the segment procedure.
%cmdebug > b 0.1670
added: CM [2] PROG % 0.1670 PROCESSSTUDENT+%263
Set a breakpoint %1670 CM words into the program file's logical segment
zero. That address corresponds to the %263rd CM word from the start of
the PROCESSSTUDENT procedure. Note that this command sets a breakpoint
in the program file, no matter where the process was stopped (in the
group library for example), since the B command implies the program file.
%cmdebug > b 1672
added: CM [3] PROG % 0.1672 PROCESSSTUDENT+%265
Set a breakpoint %1672 CM words into the program file. The logical
segment number from the current value of CMPC is used as the segment
number for this command.
%cmdebug > b processstudent+14
added: CM [4] PROG % 0.1421 PROCESSSTUDENT+%14
Set a breakpoint %14 CM words into the start of the procedure
PROCESSSTUDENT. This address corresponds to the first statement of the
nested procedure HIGHSCORE which is contained in the level 1 procedure
PROCESSSTUDENT. The correct offset to use for nested procedures is
determined by looking at the statement map produced by the Pascal
compiler. (All language compilers produce similar maps.) Unfortunately,
information about nested procedure names and size is not available for CM
programs.
%cmdebug > b ob'+40,-3
added: CM T|5| PROG % 0.40 OB'+%40
Set a breakpoint %40 words into the procedure ob' (the outer block of the
Pascal program being run). The third time the breakpoint is encountered,
stop in Debug and delete the breakpoint. The notation T|5| indicates a
temporary breakpoint with index number 2. The vertical bars indicate
that the process does not stop the next time the breakpoint is
encountered, since the count is not yet exhausted.
%cmdebug > b ?average
added: CM [6] GRP % 0.13 ?AVERAGE
%cmdebug > bg ?average+4
added: CM [7] GRP % 0.17 AVERAGE+%17
%cmdebug > b grp(0.20)
added: CM [10] GRP % 0.20 AVERAGE+%20
Set a breakpoint at the entry point to the procedure average. Notice
that the procedure was found in the group (GRP) library. The B command
starts searching for symbol names in the program file and continues
through all of the loaded library files until a match is found. The
second example uses the BG command to explicitly restrict the search for
symbol names to the group library. The third example shows how the
coercion function GRP is used to specify a logical segment in the group
library rather than the program file.
%cmdebug > bs ?fwrite,#100,q,{wl "Another #100 records written";c}
added: CM |11| SYS % 27.4727 ?FWRITE
NM |1| TRANS 30.00737fb4 SUSER1:?FWRITE
The above example sets a breakpoint at the entry point of the FWRITE
intrinsic which is located in the system library SL.PUB.SYS. Every #100
times the routine is called, stop and print out a message. The QUIET
option is specified so this operation produces no extra terminal output.
SL.PUB.SYS has been translated with the Object Code Translator (OCT), and
so Debug automatically sets a breakpoint in the translated native mode
code. Refer to appendix C for a discussion of CM object code
translation, node points, and breakpoints in translated CM code.
%cmdebug > bl
CM [1] PROG % 0.1665 ?PROCESSSTUDENT SEG' (CSTX 1)
CM [2] PROG % 0.1670 PROCESSSTUDENT+%263 SEG' (CSTX 1)
CM [3] PROG % 0.1672 PROCESSSTUDENT+%265 SEG' (CSTX 1)
CM [4] PROG % 0.1421 PROCESSSTUDENT+%14 SEG' (CSTX 1)
CM T|5| PROG % 0.40 OB'+%40 SEG' (CSTX 1)
count: 0/3
CM [6] GRP % 0.13 ?AVERAGE SEG' (CST 112)
CM [7] GRP % 0.17 AVERAGE+%17 SEG' (CST 112)
CM [10] GRP % 0.20 AVERAGE+%20 SEG' (CST 112)
CM |11| SYS % 27.4727 ?FWRITE SUSER1 (CST 30)
[QUIET] count: 0/144 cmdlist: {wl "Another #100 records written";c}
Corresponding NM bp = 1
Now list the breakpoints that were set in the above examples.
Translated Code Examples
%cmdebug > bg ?average
added: CM [1] GRP % 0.13 ?AVERAGE
NM [1] TRANS 3d.0016962c SEG':?AVERAGE
Set a breakpoint in the group library at the entry point to the AVERAGE
procedure. The group library and program file have been translated by
the Object Code Translator (OCT). Debug determined that the code is
translated and thus set a CM breakpoint in the emulated code and a NM
breakpoint in the translated code. Refer to appendix C for a discussion
of CM object code translation, node points, and breakpoints in translated
CM code.
%cmdebug > b ?processstudent
added: CM [2] PROG % 0.1665 ?PROCESSSTUDENT
NM [2] TRANS 48.0000a610 SEG':?PROCESSSTUDENT
Set a breakpoint at the entry point to the PROCESSSTUDENT procedure. As
in the above example, the code is translated, and so Debug sets two
breakpoints.
%cmdebug > b cmpc
added: CM [3] PROG % 0.1672 PROCESSSTUDENT+%265
NM [3] TRANS 48.0000a66c SEG':PROCESSSTUDENT+%265
%cmdebug > b cmpc+1
added: CM [4] PROG % 0.1673 PROCESSSTUDENT+%266
NM [3] TRANS 48.0000a66c SEG':PROCESSSTUDENT+%265
Set a breakpoint at the current CM program counter. Both the CM emulated
and NM translated breakpoints are set. Next, set a breakpoint at the
instruction following the current CM program counter. Again, both the CM
and NM breakpoints are set. Note that the index number for the NM
breakpoint is the same. This is because the two CM breakpoints are
contained in the same node. Appendix C provides a description of node
points.
%cmdebug > nm
$nmdebug > b 20.b940,#100,,{wl "Read another 100 records";c}
added: NM |4| TRANS $20.b940 FSEG:?FREAD
Break in space 20 at the indicated offset. Every 100 times the routine
is called, stop and print out a message. As with all breakpoint
commands, the address typed in is converted to a logical address. In
this example, the long to logical (LTOLOG) routine is used by the
debugger. Space 20 does not correspond to any of the native mode
libraries or the program file. It is, however, found to correspond to a
translated body of CM code (in this instance, the FREAD intrinsic). Note
that the corresponding CM emulator breakpoint is not set by Debug.
%cmdebug > bl
CM [1] GRP % 0.13 ?AVERAGE SEG' (CST 112)
Corresponding NM bp = 1
CM [2] PROG % 0.1665 ?PROCESSSTUDENT SEG' (CSTX 1)
Corresponding NM bp = 2
CM [3] PROG % 0.1672 PROCESSSTUDENT+%265 SEG' (CSTX 1)
Corresponding NM bp = 3
CM [4] PROG % 0.1673 PROCESSSTUDENT+%266 SEG' (CSTX 1)
Corresponding NM bp = 3
%cmdebug > nm
$nmdebug > bl
NM [1] TRANS 3d.0016962c SEG':?AVERAGE
CM Ref count = 1
NM [2] TRANS 48.0000a610 SEG':?PROCESSSTUDENT
CM Ref count = 1
NM [3] TRANS 48.0000a66c SEG':PROCESSSTUDENT+%265
CM Ref count = 2
NM [4] TRANS 20.0000b940 FSEG:?FREAD
count: 0/64 cmdlist: {wl "Read another 100 records";c}
CM Ref count = 1
Now list the breakpoints that have been set.
Limitations, Restrictions
You cannot set a breakpoint on a gateway page.
If breakpoints are set for a process other than the current PIN, Debug
has no knowledge of the procedure names for the specified process unless
the specified process is running the exact same program file.
Having breakpoints set causes slight process overhead. Arming a global
breakpoint causes all processes to suffer this overhead.
Breakpoints are ignored in the following circumstances:
* While on the ICS.
* While disabled.
* In a "dying" process. (See the DYING_DEBUG variable in the ENV
command discussion.)
* In a job. (See the JOB_DEBUG variable in the ENV command
discussion.)
Breakpoints set in CM translated code (which has been optimized) may not
always be hit. In some cases, the optimizer saves an instruction by
targeting a branch to the delay slot immediately following a node point.
As a result, a breakpoint that was set at the node point is not hit.
CAUTION Setting global breakpoints must be done with extreme care, and
only when debugging requires it. Do not try this on a system
under use. A global breakpoint may cause processes to suspend
unexpectedly.
CAUTION The output format of all System Debug commands is subject to
change without notice. Programs that are developed to
postprocess System Debug output should not depend on the exact
format (spacing, alignment, number of lines, uppercase or
lowercase, or spelling) of any System Debug command output.