B (break)

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.

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:

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.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.