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.