Message Passing Procedures

 System components communicate by passing messages to each other.
 This chapter describes the procedures which support this.


DOUT

%externalroutine DOUT(%record(PARMF)%name P)

 This is equivalent to DPON3("",P,0,0,7), causing the message P to be
 dispatched and the calling process to be suspended until a reply
 on the process's "sync2" service number is available, it is then
 received into the record P.


DOUT11

%externalroutine DOUT11(%record(PARMF)%name P)

 This invokes the Supervisor "OUT" no. 11, which causes the message
 P to be dispatched and the calling process's pages to remain in
 main store until a reply is available (not one of the sync1,
 sync2 or async replies referred to above, but one having the DEST
 field equal to the SRCE field of the outgoing message, the Local
 Controller having set the left-hand half of SRCE).  The reply is
 received in the record P.
 This "OUT" number should be invoked only when it is certain that
 a reply will be received, and in a very short time (e.g. the
 duration of a single magnetic tape transfer).


DOUT18

%externalroutine DOUT18(%record(PARMF)%name P)

 This invokes the Supervisor "OUT" no. 18, which causes the message
 P to be dispatched with the following side effects:
 1. The local virtual store described by P_P5 and P_P6 (P5 = number
    of bytes, not exceeding (2**24)-1, P6 = address of start of
    area) is held in main store until a reply is available
    corresponding to the dispatched message.
 2. Director places the caller's ACR value in bits 4-7 of P_P5 before
    executing the OUT instruction.
 3. The Local Controller replaces the contents of P5 and P6 with the
    Local Segment Table base and limit for the process, and the ACR
    value, as required for the first two words of a GPC request
    block.
 4. The caller may in addition set bit 0 of P_P5, in this case the
    Local Controller marks the page table entry (or entries)
    describing the store area as "written-to", thus ensuring that
    the pages are returned to disc when the process is removed from
    store, if required.  (The GPC does not so mark page table
    entries into which it transfers data, for example.)

 On return from this routine, the caller should check that P_DEST is
 not -1, which indicates either a failure to "lock down" the
 specified area of store or a condition preventing dispatch of the
 message.


DPOFF

%externalroutine DPOFF(%record(PARMF)%name P)

 This is equivalent to DPON3("",P,0,0,5) with P_DEST set to zero. "No
 message is generated and the calling process is suspended until a
 message on the process's "sync1" service number is available, it is
 then received into the record P.

 It is not privileged since SS uses it for processes started
 from the OPER (D/START)


DPON

%externalroutine DPON(%record(PARMF)%name P)

 This is equivalent to DPON3("",P,0,0,6), causing the message P to be
 dispatched and allowing the calling process to continue processing.


DPON3

%externalintegerfn DPON3(%string(6)USER, %record(PARMF)%name P,
      %integer INVOC, MSGTYPE, OUTNO)

 This function is used to pass System messages, as referred to in
 Ref. 10.

 Definitions:

 "PON"  means   send a message

 "POFF" means   take next message, or if none available
                 suspend until one is available
 
 "TOFF" means   take next message if one available, otherwise
                set P_DEST=0 and continue execution
 
 "sync1", "sync2" and "async" service numbers, mean the "N2",
       "N3" and "N4" service numbers referred to in Ref. 10.
 
 No checking is performed by Director on the parameters passed to
 this procedure.
 USER        is the 6-character username of a paged process to which
             the record P is to be sent.  (Relevant only when the left-
             hand half of P_DEST=X'FFFF', see Ref. 10.)

 P           is a record containing the 32-byte System message to be
             dispatched.  (The right-hand halves of DEST and SRCE are
             unchanged during the process of dispatching the message,
             the left-hand half of SRCE, and also of DEST when the left-
             hand half of DEST=X'FFFF', are set by the Local Controller)

 INVOC       is the invocation number of the paged process to which the
             record P is to be sent. (Relevant only when the left-hand
             half of P_DEST=X'FFFF', see Ref. 10).

 MSGTYPE     should be set to 1, 2 or 3 to indicate that the message
             generated is of the sync1, sync2 or async (i.e. N2, N3 or
             N4) type respectively.  (Relevant only when the LH half of
             P_DEST=X'FFFF').

 OUTNO       is the "OUT" number which is to be used, valid numbers
             being 5, 6, 7, 8, 9 or 10 (see Ref. 10).
 The result of the function is always zero, except when the left hand
 half of P_DEST=X'FFFF', when it is 61 if there is currently no process
 owned by the given username, the message has not then been dispatched.
 P_DEST may be set on return to indicate error conditions, as described
 in Ref. 10.


DTOFF

%externalroutine DTOFF(%record(PARMF)%name P)

 This is equivalent to DPON2 ("",P,0,6) with P_DEST=0.  No message is
 generated and the calling process always continues to execute.  If
 no message on the process's "sync1" service number was available,
 P_DEST will still be zero, otherwise P contains the received
 message.