Testing New Subsystems

 This section addressses the practicalities of testing a new subsystem.
 In particular, it draws attention to the difficulties of testing code
 which initially has no access to the terminal I/O procedures and which
 cannot satisfactorily diagnose programming errors (that is, until
 correct operation of the contingency mechanisms has been mastered).

 We first describe in more detail the fields in the user record which
 are specially relevant to this situation, namely:

               Field                                  DSFI TYPE value
           Base file name                                   0
           Director version number                          8
           Director monitor level                          16
           Contingency monitor level                       17
           Director monitor filename                       19
           Test basefile name                              35

 Director monitor level and contingency monitor level are cleared to
 zero following an IPL.


Test basefile name

 We have stated that "basefile name" specifies the name of the object
 file that is to be entered as the "subsystem", and that the version
 residing on a fixed site on the System disc is used if that name is
 null.  If the "test basefile name", is non-null, it overrides the
 setting of "basefile name", even if the latter is null, for the next
 invocation.  Thus if the subsystem under test fails disastrously the
 next log-on will yield the default or specified subsystem, which can
 then be used to study the failure and remake the test subsystem.


Director monitor filename

 The Director monitor filename, if non-null, specifies a file belonging
 to the process owner, into which Director places the following:
    * Process failure messages not diagnosed by the subsystem.
    * Extra monitoring of Director procedure entries (see 'Director
      monitor level'), or extra monitoring of contingencies.
    * Text specified, by the process, to Director procedure DPRINTSTRING
    * The contents of areas of store, printed by DDUMP.

 This monitoring file, which must not exceed 512 Kbytes in size, is
 used in a circular manner.


Contingency monitor level

 For the case of being unable to satisfy references to Director
 procedures, and for other programming errors not otherwise diagnosable,
 the  field "contingency monitor level" will be useful.  This
 field is zeroed at IPL, it can be set by a call of Director procedure
 DSFI (TYPE=17).  Bits in this word have meanings as follows:

   Bit value   Meaning and use
      1        Print a routine trace-back on the occurrence of a
               contingency, with contents of stack frames.
      2        Print text describing the contingency in words and codes
               ("CLASS/SUBCLASS").
      4        Print a hexadecimal dump of the stack segment.
      8  2**3      Print a hexadecimal dump of Director GLA.
     16        Print the contents of the virtual memory (relating
               segment number to filename and to disc address).
     32        Print a de-assembly from the code segment of the area
               around the value of the PC register at the time of the
               contingency.
     64        Print out the machine registers.

 A useful value for this field is 99.

 In order to diagnose the situation in which a subsystem has been unable
 to satisfy its references to Director procedures, it is useful to have
 a recognisable pattern in the places where the System Call descriptors
 are intended to be placed.  With the contingency monitor level 64, that
 pattern will be found in the printing of the machine registers DR0 and
 DR1 if the filling of the System Call descriptor was unsuccessful.

 The contingency monitor level field can also be set by typing, at the
 Oper console, a command of the form:
           n/SIGMON m 0
 where   n   is the process number (as displayed on the Oper screen)
         m   is an integer specifying the required value of the field,
             as above.


Director monitor level

 If Director monitor level is set non-zero, see SETDIRMON, a
 message is written to Dirlog after each Director procedure called,
 giving the values of the parameters supplied and the result returned.


Director version

 A System disc has four fixed sites (256 Kbytes each), for up to four
 versions of Director.  Site zero is used by default. Setting the
 Director version field causes the next invocation of the process to use
 the specified Director version (0, 1, 2 or 3) rather than the default
 version (0).  This facility should only be used after consultation with
 the System Manager, as the contents of a given Director site cannot
 always be guaranteed to be valid.


DDUMP

%externalroutine DDUMP(%integer START, FINISH, CH, LIM)

 Prints a hexadecimal dump from virtual address START to virtual address
 FINISH to DIRLOG. The dump has either 16 if LIM = 16, or 32 bytes per
 line.


DPRINTSTRING

%externalroutine DPRINTSTRING(%string(255)S)

 Allows a privileged process to write a string to DIRLOG.


SETDIRMON

 %externalroutine SETDIRMON(%string(255)S)

 If S is null or is the single character '0', Director monitoring is
 switched off, else it is switched on.  When monitoring is on, a record
 is written to Dirlog for each Director procedure called giving the
 parameters used and its result.