Contingency Handling
The contingency scheme works as follows. If the subsystem has not called PRIME CONTINGENCY, and a contingency occurs, then the process is stopped with an Oper message SIGNAL FAIL 1. If PRIME CONTINGENCY has been called, the ONTRAP routine is executed, with LNB set to the value of SF at the time of the contingency, and SF set 7 words higher. (If there is deemed to be insufficient space above SF to execute the ONTRAP routine, LNB is set to a suitably lower value. In this case an "OFF STACK TOP" contingency (Class 67) is generated. The ONTRAP routine should be declared to have two integer parameters CLASS and SUBCLASS. CLASS will be set (by Director when it calls the routine) according to the table below. SUBCLASS will normally be zero, except as shown below: (i) for single-character INT: messages (Class 65) it contains the INT: character. (ii) for text messages (Class 66), if non-zero, it contains two half-word pointers, being offsets of the first byte and byte after last byte of a broadcast text message in the file VOLUMS.BROADCAST. (iii) for "off stack top" (Class 67) it is the Class of the original contingency. (iv) for a System Call error (Class 16) it is 0 I-value out of range 1 J-value out of range 2 ACR check (insufficient privilege) 3 New stack invalid (validate fails, SSN+1 not resident, or new stack=current stack) 4 Task call (not implemented) 5 Invalid inward return 33 ACR check (outward call ACR < current ACR, or inward call ACR > current ACR) 34 Invalid code or PLT descriptor in SCT entry. Once PRIME CONTINGENCY has been called, the ONTRAP routine environment remains recorded, and is invoked on the specified contingencies until a further call of PRIME CONTINGENCY specifies a different ONTRAP routine or until a call of DRESET CONTINGENCY (see below) causes the first-set ONTRAP routine environment (if any) to be reinstated. However, before the ONTRAP routine can be re-invoked for a further contingency after a contingency has occurred, the function DRESUME (see below) must be called. Indeed, occurrence of a further synchronous interrupt, other than "instruction counter", before DRESUME is called will cause repeated contingencies, culminating in a SIGNAL FAIL 3 (signal loop stop). Execution of the ONTRAP routine will normally be followed by a call of READ ID (read interrupt data, described below), which gives details of the process environment at the time of the contingency, and then a call of DRESUME. If an asynchronous interrupt has occurred and the ONTRAP routine is entered, further asynchronous interrupts are inhibited until a call of DRESUME is made. Inhibited asynchronous interrupts are queued up to a current maximum of 4, after which they are discarded, with a main Oper message MESSAGE LOST. Note that, at process start-up, asynchronous messages are inhibited until the subsystem calls DRESUME, LNB=-2. Also note that only asynchronous contingencies can be queued. Contingency CLASS Floating overflow 0 Floating underflow 1 Fixed overflow 2 Decimal overflow 3 Zero divide 4 Bound check 5 Size error 6 B overflow 7 Stack error 8 Privilege 9 Descriptor 10 String 11 Instruction 12 Accumulator 13 System Call 16 Instruction counter 17 Disc transfer fail 18 Block wrong length 19 ("should not occur") Hard store fault 20 Illegal OUT 21 Local Controller error 22 Virtual store error 32 Instruction counter 64 Single-character "INT:" 65 Text message 66 Off stack top 67 Failures on the Signal Stack ---------------------------- Director sometimes fails on the 'signal stack' for one of the following reasons: %conststring(36)%array SIGFAIL(1:16) = %C "1 NO CONTINGENCY INFO", "2 PROGERR IN ONTRAP RT", "3 SIGNAL LOOP STOP", "4 FINAL IC INTERRUPT", "5 INT STACK OVERFLOW", "6 DIRECTOR FAILED", "7 ILLEGAL RESUME (LNB TOO HIGH)", "8 ILLEGAL RESUME (NOT STACK 1)", "9 ILLEGAL RESUME (AFTER VSERROR)", "10 ILLEGAL RESUME (NOT FROM ONTRAP)", "11 SHOULD NOT OCCUR", "12 INVALID UNINHIBIT", "13 XST RECEIVED", "14 ST RECEIVED", "15 TOO MANY LOST MESSAGES", "16 DSTOP on user stk. (Not an error)"
DASYNCINH
%externalintegerfn DASYNC INH(%integer ACT, ADR2) This procedure supplies a subsystem with a means of inhibiting asynchronous contingencies for short periods of time (such as that required for updating critical tables). A call with ACT=0 is used to initialise the arrangements for inhibiting contingencies, ADR2 must be the address of two words permanently available in read and write modes to Director (if the words are, or become, inaccessible, Director treats asynchronous contingencies as though this call had not been made). The first of the two words is inspected by Director whenever an asynchronous contingency is received. The contingency is queued if the word is positive, otherwise it takes immediate effect. The second word is updated (if accessible) by Director whenever an asynchronous message is received and whenever one is un-queued, the word contains the number of messages currently queued, and may be inspected by the subsystem, for example when it wishes to uninhibit contingencies by setting the first word to zero. If the second word is positive it may then choose to invoke the queued contingency, by calling DASYNC INH(1,0)
DCLEARINTMESSAGE
%externalintegerfn DCLEAR INT MESSAGE When a terminal user presses the ESC key, the TCP software generates a prompt string "INT:". The message input by the user in response is called an "INT: message" and is transmitted to the user process independently of the input and output streams enabled by the DENABLE TERMINAL STREAM procedure. INT: messages may be at most 15 characters long, the character used to terminate the message not forming part of the message. The EMAS 2900 System distinguishes single-character INT: messages from multi-character INT: messages (null INT: messages are discarded by the TCP). In the former case, the "contingency mechanism" is invoked. The DCLEAR INT MESSAGE procedure has no relevance in this case. Multi-character INT: messages, by contrast, are placed in a location visible to programs running at any level of privilege, and in particular to the subsystem. Thus an INT: message may arrive asynchronously with respect to the user process and may be used by it, for example, to re-direct the course of the computation or to take a particular action and then resume the computation. The location of the INT: message may be referenced by using the address supplied in the AIOSTAT field of the UINF record . The format of the record at this address is given by IOSTATF, below. Access to the location can be achieved as in the following example: . . %recordformat IOSTATF(%integer IAD, %string(15)INT MESS, %integer INBUFLEN, OUTBUFLEN, INSTREAM, OUTSTREAM) %record(IOSTATF)%name IOSTAT %stringname INT MESSAGE . . IOSTAT == RECORD(UINF_AIOSTAT) INT MESSAGE == IOSTAT_INT MESS . . %if INT MESSAGE = "STOP" %start . . When the process has noted the presence of a multi-character INT: message, the message should be cleared so that further examination of the message location will not yield the same message. The message can only be cleared by a call of the procedure DCLEAR INT MESSAGE, since the message location is not writable at the subsystem's level of privilege. Any INT: message arriving before a previous message has been cleared overwrites the previous message.
DISCID
%externalintegerfn DISCID This function has exactly the same effect as calling DRESUME(-1, 0, 0). It should be called from the ONTRAP routine and uninhibits asynchronous contingencies.
DRESETCONTINGENCY
%externalroutine DRESET CONTINGENCY This procedure causes the first-set ONTRAP routine to be reinstated as the contingency procedure.
DRESUME
%externalroutine DRESUME(%integer LNB, PC, ADR18) This routine is provided first to notify Director that the subsystem's ONTRAP routine (see the PRIME CONTINGENCY procedure) has completed that section of its code during execution of which it could not reasonably resume following a subsequent asynchronous contingency. Asynchronous contingencies are inhibited by Director until this notification is received, program or virtual store errors will cause looping. Likely tasks in this inhibited state (called the "ONTRAP state") are i) determination of a new environment (e.g. an "ABORT" position, or a diagnostic routine), or ii) output of a text message, or iii) determination of other subsequent action (e.g. ignore asynchronous interrupt, and continue the former computation). Secondly, DRESUME provides the means for the ONTRAP routine to specify the original or a chosen new environment, for resumption of normal computation. The action taken is determined by the value of the parameter LNB. Parameter ADR18 is relevant only when LNB=0, and PC only when LNB is greater than zero. LNB=-2 At process start-up, asynchronous interrupts are inhibited until the subsystem calls this entry point to DRESUME. This enables the subsystem to initialise itself properly for action. Subsequent calls of this entry point have no effect. LNB=-1 This entry point tells Director that the ONTRAP routine has completed its critical operations and can again accept asynchronous interrupts. If a contingency is in fact queued at the time that this entry point is called by the ONTRAP routine, a new invocation of the ONTRAP routine is immediately created. The environment supplied, by procedure READ ID, to the new ONTRAP routine is that following the call of DRESUME in the previous ONTRAP routine. LNB=0 This entry point may be called only from the ONTRAP state (otherwise the process stops with a main Oper message SIGNAL FAIL 10) following an asynchronous contingency or program error (SIGNAL FAIL 9 following a virtual store error). The call informs Director that computation is to be resumed at the point of interruption. Parameter ADR18 must point to a copy of the environment supplied to the subsystem by the READ ID procedure. The process leaves the ONTRAP state. LNB>0 The values LNB, PC are transferred to the process registers LNB and PC, and computation continues at PC The value ADR18 is placed in the ACC, single length, as a means of passing information to the new computation. The values assigned to the other registers are indeterminate, therefore it is expected that PC will point at or near an EXIT instruction so that a well- defined environment can be reached. The LNB value must be more than 5 words below the SF at the time of the contingency, otherwise SIGNAL FAIL 7 occurs. The process leaves the ONTRAP state.
PRIMECONTINGENCY
%externalintegerfn PRIME CONTINGENCY(%integer DR0, DR1, J, XNBVALUE) The purpose of this procedure is to nominate a routine (the actual parameter) which is to be executed on the occurrence of various contingencies, both synchronous and asynchronous. The types of contingencies which will invoke the ONTRAP routine are as follows: Synchronous *Virtual store errors. *Program errors. *Instruction counter interrupt (treated as program error). Asynchronous *Arrival of single-character "INT:" messages (as in INT:A, for example, from an interactive terminal, or a TERMINATE to a batch process from the main Oper console). *Arrival of text messages from the machine operator or from other processes. *Arrival of "POFF" messages from other processes or from the Supervisor (available only to privileged processes).
READID
%externalintegerfn READID(%integer ADR) This function provides the process environment as it was at the occurrence of the most recent contingency. The information is written to the area whose address is given by parameter ADR. Currently, 18 words - the processor registers plus PC of erring or current instruction - are returned, but space should be left for 32 words altogether (for future extensions). The interrupt data remains available for repeated reading until a call of DRESUME (described below) is executed. An error result of 53 is returned if no interrupt data is available, or of 45 if the address supplied is not accessible.