B (break)
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| E0201 Edition 4 ♥ | |
| E0300 Edition 3 | |
| E0692 Edition 3 |
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 CSTXThe 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 cod e segment
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
B implies PROG
BG implies GRP
BS implies SYS
As a short pointer (SPTR):
- B 1024
offset only
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.
- 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.
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
- 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+$270Set 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+$274Break 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+$8The 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 PA-RISC Procedure Calling Conventions Reference Manual 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+$8The 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_TRAPSThe 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+14Break 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 ?PROCESSSTUDENTSet 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+%263Set 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+%265Set 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+%14Set 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'+%40Set 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+%20Set 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.)
 |
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. |
|
ALIASL[IST] |
BD |