Trailing-Edge - PDP-10 Archives - BB-L288A-RM - swskit-utilities/mtest.mem
There are 5 other files named mtest.mem in the archive. Click here to see a list.

                    Swskit Documentation For MTEST

     MTEST is a program whose purpose is to allow the user  to  insert
     MONITOR  instruction  execution tests at any place in the TOPS-20
     MONITOR.  It functions as an interface to  the  UTEST  JSYS  (see
     page  3-409  of  the  Monitor Calls Reference Manual).  This JSYS
     provides a method for  determining  if  every  instruction  in  a
     section of monitor code actually gets executed.  It confirms that
     a test of the code is complete by reporting the instructions that
     were executed during the test.

     IMPORTANT NOTE:  Never insert a test over monitor data since  the
     tests  cause  a  call  to  an  internal  UTEST JSYS routine to be
     inserted in the words being tested.  If a test is made of monitor
     data, a corruption of the monitor data base is likely.

     To allow  examination  of  the  test  to  be  as  convienient  as
     possible,  the  MTEST  program  provides  a  deassembler  for the
     monitor instructions.  Symbols for various  values  are  obtained
     using  the  SNOOP JSYS.  In this way the output from MTEST should
     present the instructions in a format  similar  to  that  of  DDT.
     Since  the  SNOOP  JSYS  allows  an argument of the module symbol
     table to search first for the symbol, MTEST also allows a user to
     specify a default symbol table to search first.

     One of the restrictions of the UTEST JSYS is that the section  of
     monitor  code  which  is  being  tested  cannot exceed a two page
     window.   This  is  due  to  the  data  structures  that  TOPS-20
     implements  for  this  JSYS.  Not every instruction in the window
     need be tested nor must the tests be contiguous.  In other words,
     as many sections of monitor code as the user wishes can be tested
     at the same time as  long  as  the  distance  between  the  first
     instruction and the last instruction to be tested is no more that
     2000 (octal) words.  If an attempt is made to insert a test which
     exceeds this two page window, an error message will be printed on
     the terminal but all previous tests inserted will be preserved.

     The actual test is not inserted into the MONITOR until  the  test
     is  started.   This allows a user to redefine the test if they so
     wish before the test is started and it allows the user a means of
     setting  up  a  time  window  also for execution of the test.  To
     facilitate the ease of starting  and  stopping  commands,  a  PSI
     channel  is  dedicated as a test toggle.  Each time the specified
     control character is typed, the test will  either  toggle  on  or

     There is a command in MTEST which allows a user to simply examine
     monitor code without affecting any of the tests which are set up.
     This allows the person to determine the exact  instructions  they
     wish to test before they insert the test.  To examine which tests
     the users have already inserted, they need only type the  command
     RESULTS,  which  will  type  out  all  the instructions which are
     marked to be tested.  The RESULTS command is also used to see the
     results  of  a test after the test is finished.  Each instruction
     which was executed will be preceeded  by  an  'X'.   The  results
     command is invalid while a test is in progress.

     A facility to run programs as inferior forks  to  MTEST  is  also
     available, since some tests will need some JSYS, program, or EXEC
     command to be specifically  executed  for  the  test.   For  this
     reason  there  is a command to enter SDDT, to PUSH to an inferior
Swskit Documentation For MTEST                                  Page 2

     EXEC, or to run any program.  These forks are ephemeral.

     Other miscellaneous commands allow the user to  reset  the  MTEST
     data  base,  clear  default  symbol table and redefine the toggle
     control character.

     A summary of commands is listed below:

     MTEST>? one of the following:
      Clear        Examine    Exit       Help       Insert     Push
      Reset        Results    Run        SDDT       Set        Start
      Stop         Toggle
        CLEAR           Clears the  default  symbol table  for  symbol
        EXAMINE         Examines a section of Monitor Code.
        EXIT            Exits from MTEST.   If a test  is in  progress
                        MTEST will not allow the EXIT command.
        HELP            Types this text.
        INSERT          Inserts a Monitor code test.  Note: this  does
                        not actually insert the test into the MONITOR,
                        rather, it sets up the MTEST data base so that
                        when the test  is started, MTEST  will have  a
                        test to insert.
        PUSH            Pushes to an inferior ephemeral EXEC.
        RESET           Resets the MTEST data base.
        RESULTS         Will  type  out  the  tests  which  have  been
                        inserted if  this command  is typed  before  a
                        test is started or  will type out the  results
                        of a test  if this  command is  typed after  a
                        test is stopped.  The command is illegal while
                        a test is in progress.
        RUN             Run a program in a ephemeral fork.
        SDDT            Runs an ephemeral SDDT fork.
        SET             Sets the default symbol table.
        START           Starts testing.
        STOP            Stops testing.
        TOGGLE          Allows user  to specify  toggle character  for
                        test starting and stopping.
     The following is a sample MTEST test.  Assume we are  getting  an
     error  message  from  the SWJFN JSYS and we wish to determine how
     the code decided that there was an error condition.  What we wish
     to do is to set up a test of the SWJFN code and see the path that
     the JSYS will take upon executing it.
Swskit Documentation For MTEST                                  Page 3

     You need to be an enabled WHEEL to run this program
     Do You Want to be enabled?YES
     MTEST>SET (Lookup Module Name to) JSYSF
     MTEST>TOGGLE (Character is) ^D
     MTEST>EXAMINE (Monitor Code) 
     Starting At: .SWJFN
     Ending At: .SWJFN+10
     .SWJFN    MOVE 11,KSTYP
     .SWJFN+1    CAMN 1,CDRST
     .SWJFN+2    JRST BLKF6+116
     .SWJFN+3    PUSHJ 17,F1+556515
     .SWJFN+4    JSP 2,F1+10763
     .SWJFN+5    PUSHJ 17,F1+2040
     .SWJFN+6    JRST BLKF6+122
     .SWJFN+7    PUSH 17,JFN
     .SWJFN+10    XCT 4,BLKF5+317
     MTEST>INSERT (Code Test) 
     Starting At: .SWJFN
     Ending At: .SWJFN+10
     1/   0   1
     2/   0   1
     [MTEST Test Started]
     MTEST>STOP (Testing) 
       X  .SWJFN    MOVE 11,KSTYP
       X  .SWJFN+1    CAMN 1,CDRST
       X  .SWJFN+2    JRST BLKF6+116
          .SWJFN+3    PUSHJ 17,F1+556515
          .SWJFN+4    JSP 2,F1+10763
          .SWJFN+5    PUSHJ 17,F1+2040
          .SWJFN+6    JRST BLKF6+122
          .SWJFN+7    PUSH 17,JFN
          .SWJFN+10    XCT 4,BLKF5+317
     From  this,  it  is  seen that the error return is generated from