DEBUGGING PROGRAM


OBJECT: DBUG


       This program is used as an aid to debugging programs, it may  be
    used to:-
         1) SET and CLEAR breakpoints
         2) Dump out the PSECT, REGISTERS and/or the IMP STACK.
         3) EXAMINE and CHANGE locations in core.
         4) DUMP general areas of core.


       DEBUG  indicates  its  readiness  to  accept  commands by typing
    'DEBUG:'. The following commands may be used.

    T - Set Task number of program to be debugged.
    B - Set breakpoint.
    C - Clear breakpoint.
    N - Set a new program code base.
    R - Dump the REGISTERS, line number etc.
    P - Dump the PSECT.
    E - List the loaded EXTERNALS.
    I - Dump the IMP stack.
    A - Do 'P', 'R', 'E', and 'I'.
    D - Dump an area of core.
    O - Change the output device.
    W - WAIT DEBUG.
    S - Stop DEBUG.
    ? - Print options.

       In addition to these commands,  there  is  an  implied  command,
    activated  by  typing  an  octal  digit,  that  enters  the location
    examination/change part of DEBUG.


       A detailed description of each command follows.



T - SET TASK NUMBER

       The prompt 'TASK NUMBER (OCTAL):' is output and  the  (octal)
    ID  of  the program to be debugged should be entered. It should be
    noted that commands 'R', 'P', 'I', and 'A' will only execute  if
    a task number is set. 'B' will use a base of ZERO for breakpoints.



B - SET BREAKPOINT

       The  prompt  'ADDR:'  is  output,  the  reply  is the RELATIVE
    address (wrt the start of the program) of  the  desired  breakpoint.
    Debug  will  remember  the  contents  and  place  a  'BR ' in the
    location. This will cause the program  to  sit  in  a  loop  if  it
    executes that instruction.





       Debug replies:
    BP:  n  ADDR:  n2  CONT=  n3 - where 'n' is the breakpoint number
    (between 0 and 20), 'n2' is  the  physical  address,  and  'n3'  the
    original contents.

       The  message  'BP  TABLE  FULL'  is  output  if  more than 21
    breakpoints are used. See the command 'N' for setting  breakpoints
    in external routines.



C - CLEAR BREAKPOINTS

       Prompts  'NO?'. The breakpoint number should be typed. 'A' or
    '-1' is typed if ALL the breakpoints are to  be  cleared.  If  the
    specific  breakpoint  has  not  been set, the message '?' is output.
    The original contents are replaced.



N - SET A NEW PROGRAM CODE BASE

       Prompts 'NEW PROGRAM CODE:'. Reply giving the  new  address.
    This  command  is  useful for programs using external routines. To
    set a breakpoint in an external routine , the code base  is  set  to
    that  of  the  external  routine and the relative address specified.
    This does not effect any previously set breakpoints.

       A second use is to put a breakpoint into  a  program  before  it
    starts  executing. ie the code is LOADED from disc, the base set by
    'N', breakpoints  set  with  relative  addresses  and  finally  the
    program  is  STARTED  using  'OIT'.  This  allows  debugging of a
    program that crashes immediately after startup.



R - PRINT REGISTERS AND OTHER PROGRAM INFORMATION.

       This command prints the registers of  the  nominated  task.  In
    addition, if the task has had an address error or similar fault, the
    registers at the time of the crask are also printed (although R3 is
    destroyed by the system).

       The  LINE  NUMBER of the program, its CODE ADDRESS, the IMP
    DISPLAY address and the MINIMUN STACK are also printed.



P - PRINT THE PSECT

       The PSECT (own system  variables)  of  the  nominated  task  is
    printed.












E - LIST THE EXTERNALS USED BY THE PROGRAM


       This  command  will  list  the external routines which have been
    loaded by the program, giving the name followed by  the  address  it
    was loaded at.



I - PRINT THE IMP STACK

       The entire IMP STACK is printed on the output device.
    NOTE:  The base of the DISPLAY (ie the start of the variables) is
    not the same as the start of the stack. There are  PERM  variables
    on the top of the stack. 'R' gives the start of the DISPLAY.



A - PRINT ALL

       The  command executes a print psect (P), print registers (R) ,
    list of externals (E) and the IMP stack  (I).  This  command  is
    useful for dumping all the relevant information about a program onto
    the line printer (see command 'O').



D - DUMP AN AREA OF CORE

       Prompts  'FROM:'  and 'LENGTH:'. Both numbers should be typed
    in octal and the area of core  from  'FROM'  to  'FROM+LENGTH'  is
    output.

    NOTE: 1) On all the dumps 'ZEROES' is ouput if one or more entire
    line contains zero.
    2) An ISO equivalent is printed on the RHS of the dump.



O - CHANGE THE OUTPUT DEVICE

       Prompts  'STREAM:'.  The  reply  is  the stream number for the
    output of commands R,P,I,A and D. The line printer is '2' and the
    teletype '0'.

       This command will change to specify a device or file by name  in
    the near future.



W - WAIT DEBUG

       This  command  is  used  to suspend DEBUG if it is necessary to
    input to a program on the same teletype. It is restarted by
    'OIT:CO DBUG'.





S - STOP DEBUG

       Debug halts.
    Note: at present breakpoints are not cleared.



IMPLIED COMMAND TO EXAMINE/CHANGE CORE ADDRESSES

       This command accepts the following instructions:-
         Please note that all numbers are typed in octal.
         N                     : prints contents of N.
         N+C                   : prints contents of (N+ program base).
         N+I                   : prints  contents  of  (N+  IMP  STK
         base).
         N+RM                  : prints contents of (N+REGISTER M)

         N(+ options)=m        : puts M into N


    eg: DEBUG:100 (cr) - will print contents of locn 100.
        DEBUG:100+R5 (cr) - will print contents of 100 on from reg. 5.
        DEBUG:100+R5=200 (cr) - diito, except plants 200.