.!++ .! FACILITY: Supplying Analysis Events Over a Connected Machines Link .! .! ABSTRACT: Internal note on protocol to be used for event requests. .! .! ENVIRONMENT: VAX-11 DSR V2 .! IN66.RNO .! .! $ CREATE IN66.RNT ! empty file .! $ RUNOFF /NOOUTPUT /CONTENTS .! $ RUN SYS$SYSTEM:TOC ! default on all answers .! $ RUNOFF /RIGHT= 10 IN66 .! $ DELETE IN66.BTC.*, IN66.RNT.* .! .! AUTHOR: Vicky White, Peter Heinicke, Creation date: 22-Jan-1982 .! .! MODIFIED BY: .! .! V04-000 THN Thomas H. Nicinski 9-Apr-1984 .! Complete re-write and expansion and clarification of the .! protocol. Expansion included booking/unbooking and data .! transfered in more than one transmission. .! .! V03-000 VW, PHH Vicky White, Peter Heinicke 20-Dec-1982 .! .! V02-000 VW, PHH Vicky White, Peter Heinicke 4-May-1982 .! .! V01-000 VW, PHH Vicky White, Peter Heinicke 22-Jan-1982 .! Initial entry. Internal Note 66. .!-- .page size 58, 65 .layout 1 3 .style headers , 0 .spacing 1 .period .set paragraph 0, 1, 3 .autoparagraph .! .! .! .display number rl .! .title Supplying Analysis Events Over a Connected Machines Link .! .no number .indent +58;IN 66.4 .blank 12 .center;Supplying Analysis Events .center;Over a .center;Connected Machines Link .blank 2 .center;Vicky White, Peter Heinicke, .center;and Tom Nicinski .blank .center;Fermilab Computing Department .blank 2 .center;May 1984 .blank 2 .blank 1.! Replaces DRAFT .blank 5 .! .left margin +5 .right margin -5 This paper describes a high level protocol for requesting and supplying events over a Connected Machines (CD) link. .right margin +5 .left margin -5 .! .left margin +10 .blank -1 .indent -10;KEYWORDS:#Connected Machines, CD .left margin -10 .! .! Do the table of contents stuff .! .send toc .page .send toc .display number rl .send toc .number page 3 .send toc .center;Contents .send toc .blank .! .require 'IN66.rnt' .page size 58, 65 .! .! .! .page .display number d .number running 1 .number page 1 .! .chapter Introduction This paper describes a high level protocol that permits events or buffers of events to be supplied to different processes, usually on different machines, in an operating system independent manner. Some terminology used throughout this document is .! .list 1, "o" .! .list element ^&Link\&. The link refers to the hardware (currently, a DR-11W) or virtual link and software drivers used to communicate among different processes. .! .list element ^&PTC\&. The Packet Type Code is the means of identifying different processes that communicate among each other using the connected machines (CD) software and link. Throughout this document, PTC will be used to refer to both the process it identifies and the identification value itself. .! .list element ^&Requestor\&. The requestor is the process which requests the provider to supply it with an event or buffer of events. This is usually some analysis program. .! .list element ^&Provider\&. The provider is the process which supplies events to a requestor. Usually, this process runs in a data acquistion (DA) machine. .! .list element ^&Message\&. A logical group of bytes sent across the link. It is the basic unit of communication between processes (PTCs). A ^&signal\& is a special message consisting of only one byte. .! .list element ^&Event\& and ^&Buffer of Events\&. An event is a set of data acquired by a data acquisition process. A buffer of events consists of one or more contiguous complete events (i.e., an event cannot be split across buffers). The only restriction (part of the IN#66 protocol) on the event format is that the first word (two bytes) of an event is the event size. The size specifies the number of bytes in the event, including the first word containing the byte count. .! .end list Note that requestor and provider are described in a machine-independent way. Generally, the requestors and provider exist on different machines, but there is nothing within the protocol described below that prohibits both requestors and provider to exist on the same machine. Data structure names follow the naming conventions used in VAX/VMS software. These conventions are described in Chapter 32, "Naming Conventions", in ^&VAX/VMS Internals and Data Structures\&, published by the Digital Press. Also, suggested data structure names for RT-11 and RSX systems (that is, the names are unique among the first six characters) are supplied within parentheses. All have a dollar sign ($) as part of the name; if the particular language/compiler does not support the dollar sign, suggested characters are the period (.), the underscore (__), or the letter "D" (for dollar, to provide some consistency among implementations). This paper does not describe the low level protocol used across the link by the CD drivers or the normal user interface to the link. For interested users, this protocol is described in DS#77, ^&DR11W as a Link Device - The Transmission Protocol\& and a Fortran callable interface is described in PN#159, ^&CDPACK / Fortran-callable Routines for Interprocessor Communication.\& .! .! .! .chapter Messages The protocol is defined by the passing of high level messages between the requestor and the provider. .! .! .! .header level 1 The "Request Event" Message The "request event" message is sent by the requestor to the provider. It asks the provider to perform a service for the requestor. Usually, this service is the supplying of an event or buffer of events. The request event message has the following format: .! .blank .test page 18 .left margin +10 .literal 15 0 +----------------+ | | rqst$w_code (code$w) +----------------+ | | rqst$w_PTC (ptc$w) +----------------+ | | rqst$w_maxbuf_siz (mxbfsz$w) +----------------+ | | rqst$w_event_type (evty$w) +----------------+ | | rqst$w_flags (flags$w) +----------------+ | | rqst$w_device (dev$w) +----------------+ | | rqst$w_spare1 +----------------+ | | rqst$w_spare2 +----------------+ .end literal .left margin -10 .! The different fields are .! .left margin +10 .! .blank;.test page 3 .indent -5;RQST$W__CODE (CODE$W) .break The request code describing what the provider is to do for the requestor. Legal request codes are .! .left margin +5 .! .blank;.test page 3;.indent -5;1####RQST$K__NEXT__EVENT (NEV$K) .break Supply the next event or buffer of events. All request fields are used. .! .blank;.test page 3;.indent -5;2####RQST$K__RELEASE__RQST (RLSE$K) .break Release any requests and events reserved for the requestor, including booked requests. Only field RQST$W__PTC is used. .! .blank;.test page 3;.indent -5;3####RQST$K__TERM__GTEVNT (TRMN$K) .break Terminate the GTEVNT task. None of the other request fields are used. This is legal only for providers existing under an RSX-11M system. .! .blank;.test page 3;.indent -5;4####RQST$K__BOOK__RQST (BOOK$K) .break Book a request. This refers to the collection of events for the requestor. All fields are used, except RQST$W__MAXBUF__SIZ. See Section 3.1.4. .! .blank;.test page 3;.indent -5;5####RQST$K__UNBOOK__RQST (NOBOOK$K) .break Unbook a request. This refers to the collection of events for the requestor. All fields are used, except RQST$W__MAXBUF__SIZ, RQST$W__FLAGS, and RQST$W__DEVICE. See Section 3.1.4. .! .blank;.test page 3;.indent -5;6####RQST$K__CONT__EVENT (CEV$K) .break Supply the next transmission of an event or buffer of events. This request follows a RQST$K__NEXT__EVENT request when the provider replies with RLPY$__CONT__EVENT (signifying that the event or buffer of events will be sent in more than one transmission). With this request code, only field RQST$W__PTC is used. See Sections 3.1.3 and A.1. .! .blank;.test page 3;.indent -5;7####RQST$K__ABORT (ABO$K) .break A general abort request. Currently, this message is defined only for aborting multiple transfer requests (See Section 3.1.3). .! .left margin -5 .! .blank;.test page 3 .indent -5;RQST$W__PTC (PTC$W) .break The request will be performed for the requestor with this PTC, and the reply sent to this PTC. .! .blank;.test page 3 .indent -5;RQST$W__MAXBUF__SIZ (MXBFSZ$W) .break The maximum size of the requestor's buffer. It is an unsigned count of 16-bit words. If the provider has data larger than RQST$W__MAXBUF__SIZ, the entire buffer is still sent, although the requestor may get a truncation error from its read. .! .blank;.test page 3 .indent -5;RQST$W__EVENT__TYPE (EVTY$W) .break The event type to be supplied. Event type 0 (RQST$W__EVENT__TYPE <0:15> = 0) is reserved as a special value: the provider supplies any event type available. A non-zero value can be interpreted in any consistent manner (e.g., as a bitmask or a particular type of event, etc.). .! .blank;.test page 3 .indent -5;RQST$W__FLAGS (FLAGS$W) .break A group of bits specifying the "mode" under which this request is to be handled. Legal values are .! .left margin +9 .! .blank;.indent -9;<0>######RQST$V__BUFFER (BUFF$V) .break If set, supply a buffer of one or more events up to the maximum buffer size of the requestor (RQST$W__MAXBUF__SIZ). .blank If clear, supply a single event. .! .blank;.indent -9;<1>######RQST$V__PENDING (PEND$V) .break If set, the request is to be held pending if it cannot be satisfied immediately. .blank If clear, if the request cannot be satisfied immediately, it is to be discarded, and a reply status sent to the requestor indicating the request cannot be satisfied. .! .blank;.indent -9;<2>######RQST$V__BOOKED (BOOK$V) .break If set, supply an event or buffer of events that has been booked previously using the RQST$K__BOOK__RQST request code (RQST$W__CODE). The field RQST$W__DEVICE is not used. .blank If clear, the request is to be satisfied from the "general pool" of available events. The "general pool" is defined by the implementation; for e.g., the event may still be obtained from booked events, etc. .! .blank;.indent -9;<3:4>####RQST$V__EVENT__TYPE (EVTY$V) .break The type of event to supply if a single event is requested, that is, RQST$V__BUFFER is clear. .! .left margin +2 .! .blank;.indent -9;##00#####RQST$M__ANY (ANY$M) .break Any event type can be supplied. .! .blank;.indent -9;##01#####RQST$M__CALIB__PREF (CALP$M) .break If a calibration event is available, supply it, otherwise, supply a non-calibration event. .! .blank;.indent -9;##10#####RQST$M__CALIB (CAL$M) .break Supply a calibration type event only. .! .blank;.indent -9;##11#####RQST$M__NON__CALIB (NOCAL$M) .break Supply a non-calibration type event only. .! .left margin -2 .! .left margin -9 .! .blank;.test page 3 .indent -5;RQST$W__DEVICE (DEV$W) .break The device from which the provider is to obtain the event from. Legal devices are .! .left margin +5 .! .blank;.test page 3;.indent -5;0####RQST$K__CURDEF (DEF$K) .break The current default device. .! .blank;.test page 3;.indent -5;1####RQST$K__800BPI (MT8$K) .break A magtape drive whose density is set at 800 BPI. .! .blank;.test page 3;.indent -5;2####RQST$K__1600BPI (MT16$K) .break A magtape drive whose density is set at 1600 BPI. .! .blank;.test page 3;.indent -5;3####RQST$K__MEMORY (MEM$K) .break Bulk memory or a DA buffer. .! .left margin -5 .! .blank;.test page 3 .indent -5;RQST$W__SPARE1#####Reserved for future use. .indent -5;RQST$W__SPARE2#####Reserved for future use. .! .left margin -10 .! .! .! .header level 1 The "Reply" Messages The provider will reply to requestor messages with one of two messages: .! .list 1, "o" .! .list element The event or buffer of events requested. This messages can be supplied in one or more transfers across the link. .! .list element A status block describing an error condition. .! .end list .! The requestor differentiates between the two messages by the size of the message received. A "status" message (described further in Section 2.2.2) is always two words (four bytes) in size. .! .! .! .header level 2 The "Event/Buffer of Events" Message An "event" message consists of one event. A "buffer of events" message consists of one or more contiguous complete events. Both messages have no message header or leading byte count in the message. Therefore, both messages are the same (the "event" message being an instance of a "buffer of events" message), and thus will be treated as the same and referred to the "buffer of events" message. .! .! .! .header level 2 The "Status" Message The status message has the following format: .blank .test page 6 .left margin +10 .! .literal 15 0 +----------------+ | | rply$w_status (STS$W) +----------------+ | | rply$w_data1 (STSD1$W) +----------------+ .end literal .! .left margin -10 .! The different fields are .! .left margin +10 .! .blank;.test page 3;.indent -5;RPLY$W__STATUS (STS$W) .break A value specifying the status of the request. .! .blank;.test page 3;.indent -5;RPLY$W__DATA1 (STSD1$W) .break RPLY$W__STATUS dependent data. .! .left margin -10 .! The return status, RPLY$W__STATUS, can contain the following values. Some of the values are operating system dependent and are denoted as such. In either case, all reply messages have unique values. .! .left margin +10 .! .blank;.test page 3;.indent -5;#-1##RPLY$__NOSUCCESS (FAIL$RPLY), completion is not successful .blank;Explanation:##A request failed for some uncategorized reason. This is a general negative acknowledge (NAK) reply. .blank;Requestor#Action:##Report the error. .! .blank;.test page 3;.indent -5;##1##RPLY$__NORUN (NORUN$RPLY), no run is currently active .blank;Explanation:##No data acquisition run is in progress. Therefore, no events are or will be available until a DA run begins. .blank;Requestor#Action:##Experiments (or Run Control Module) should begin a run. After a run is in progress, the request for events should be re-issued. .! .blank;.test page 3;.indent -5;##2##RPLY$__NOEVENT (NOEV$RPLY), no event is currently available .blank;Explanation:##A run is active, but no data is currently available. .blank;Requestor#Action:##Wait and then retry the request. .! .blank;.test page 3;.indent -5;##3##RPLY$__NORQST__EVENT (NOREV$RPLY), requested event type is not currently available .blank;Explanation:##A run is active, but data of the type requested is not currently available. .blank;Requestor#Action:##Wait and then retry the request. .! .blank;.test page 3;.indent -5;##4##RPLY$__RQST__PENDING (PEND$RPLY), request is pending .blank;Explanation:##The request is pending, no event is currently available. .blank;Requestor#Action:##Requestor should do something else until a signal is received from the provider. The signal SGNL$__NOEVENT indicates no event will become available, in which case, the requestor should no longer expect to have its request satisfied. The signal SGNL$__EVENT__AVAIL indicates an event is being held by the provider; the requestor should re-issue its request to receive the event. .! .blank;.test page 3;.indent -5;##5##RPLY$__INVRQST (IVRQ$RPLY), invalid request .blank;Explanation:##Some portion of the request was invalid. .blank;User#Action:##The author of the request should examine his/her code and data structure(s) for programming errors. .! .blank;.test page 3;.indent -5;##6##RPLY$__INVRQST__CODE (IVRC$RPLY), invalid request code .blank;Explanation:##The request code was invalid. .blank;User#Action:##The author of the request should examine his/her code and data structure for programming errors. .! .blank;.test page 3;.indent -5;##7##RPLY$__SUCCESS (SUCC$RPLY), successful completion .blank;Explanation:##A request not involving the obtaining of events was successful. For example, the book request returns this status. .blank;Requestor#Action:##Proceed. .! .blank;.test page 3;.indent -5;##8##RPLY$__CONT__EVENT (CEV$RPLY), request to be sent in multiple transmissions .blank;Explanation:##The provider is unable to satisfy the request with one transmission of the event or buffer or events. The data will be sent using more than one transfer across the link. The status field RPLY$__DATA1 will contain the number of required transmissions. See Section 3.1.3. .blank;Requestor#Action:##Request the data using the RQST$K__CONT__EVENT request code. .! .blank;.test page 3;.indent -5;##9##RPLY$__TOOM__ANAL (TOOM$RPLY), too many analysis processes .blank;Explanation:##The maximum number of allowed simultaneous analysis processes (tasks) has been exceeded. This occurs when the provider's requestor related tables run out of space. .blank;User#Action:##Decrease the number of analysis processes simultaneously requesting events. .! .blank;.test page 3;.indent -5;#10##RPLY$__MTEOF (MTEOF$RPLY), magnetic tape end of file detected .blank;Explanation:##The provider encountered an End Of File while reading a tape in order to supply the requestor with data. .blank;Requestor#Action:##Take action appropriate to an end-of-data-set condition (e.g., print histograms, statistics, etc.). .! .blank;.test page 3;.indent -5;#11##RPLY$__MTDENSE (MTD$RPLY), unable to set magtape density .blank;Explanation:##The provider was unable, for some reason (e.g., the tape drive is offline, etc.), to set the magtape density. .blank;Requestor#Action:##Report the error. .! .blank;.test page 3;.indent -5;#12##RPLY$__MTREADERR (MTR$RPLY), magtape read error .blank;Explanation:##The provider encountered an error reading the magtape. .blank;Requestor#Action:##Report the error if it occurs several times in succession. .! .blank;.test page 3;.indent -5;#13##RPLY$__BULK__MAP (BULK$RPLY), unable to map to bulk memory .blank;Explanation:##RSX-11M specific provider. A programming error. .blank;User#Action:##The author should examine his/her code and data structure for programming errors. .! .blank;.test page 3;.indent -5;#14##RPLY$__GTEVNT__REDUCE (GRED$RPLY), unable to reduce GTEVNT task size .blank;Explanation:##RSX-11M specific provider. The provider was unable to reduce the task size of GTEVNT, in order to eliminate a tape buffer. .blank;Requestor#Action:##Report the error. .! .blank;.test page 3;.indent -5;#15##RPLY$__GTEVNT__EXTEND (GEXT$RPLY), unable to extend GTEVNT task size .blank;Explanation:##RSX-11M specific provider. The provider was unable to extend the task size of GTEVNT, in order to create a tape buffer. .blank;Requestor#Action:##Report the error. .! .left margin -10 .! .! .! .header level 1 Signals A signal is a one byte message used to notify processes of special conditions. Unlike the reply messages, signals can be received asynchronously (that is, they do not have to be requested). .! .blank .test page 4 .left margin +10 .literal 7 0 +--------+ | | sgnl$b_value (sval$w) +--------+ .end literal .left margin -10 .blank .! The different fields are .! .left margin +10 .! .blank;.test page 3;.indent -5;SGNL$B__VALUE (SVAL$W) .break The value of the signal. .! .left margin -10 .! The field SGNL$B__VALUE can contain the following values: .! .left margin +10 .! .blank;.test page 3;.indent -5;##1##SGNL$__ERROR (ERR$SGNL) .blank;Explanation:##Some type of error has occurred on the provider's "end". The next message from the provider will be a status reply message, giving further information about the error. .blank;Requestor#Action:##Re-set the requestor state to receive a status reply message. .! .blank;.test page 3;.indent -5;##6##SGNL$__EVENT__AVAIL (EVAV$SGNL) .blank;Explanation:##The provider has an event available for the requestor. This signal is sent to the requestor when the provider has previously sent a RPLY$__RQST__PENDING status message to the requestor's request. .blank;Requestor#Action:##The requestor should re-send its previous request. .! .blank;.test page 3;.indent -5;##7##SGNL$__NOEVENT (NOEV$SGNL) .blank;Explanation:##The provider will never be able to satisfy the requestor's request for an event or buffer of events. This is usually due to an "end of run" condition, where the DA will no longer acquire data, and therefore no new events will be made available to the provider. .blank;Requestor#Action:##Wait till the next run and request the event at that time. .! .left margin -10 .! .! .! .chapter The Protocol The protocol defines the sequence of messages and signals sent between the provider and a requestor. The protocol consists of sending messages (and signals, which are a special type of message) between the requestor and provider. In general, the protocol consists of the requestor sending a request to the provider and then waiting for a reply from the provider. The provider will always supply the requestor with some type of reply immediately. This back and forth protocol has one exception: the sending of a signal. The provider may send the requestor a signal after sending a reply message (for example, see Section 3.1.2); or the provider may send the requestor a signal in place of a reply message (for example, see Section 3.1.3). In either case, the back and forth protocol resumes; but based on the signal value, it either resumes with the provider sending a reply message or the requestor initiating a request. Another important aspect of the protocol is when a requestor requests an event or buffer of events. The requestor must make a buffer available, to receive the provider's reply, before the request is sent (that is, issue the read for the data before requesting the data). This is necessary, as the CD drivers must have an area to place incoming data. The requestor should assume that once data is requested, it will arrive immediately (issuing the read before the request avoids timing problems). This is not the case when signals are involved. A signal does not need to have a buffer available in order to be received by the requestor. .! .! .! .header level 1 Instances of the Protocol Below, four instances of the protocol are shown. .! .! .! .header level 2 Simple Request The following instance describes the sequence of messages when a requestor requests an event, but does not wish to wait for it. .! .left margin +20 .tab stops 10, 20 .! .blank .test page 5 .indent -20 ^&Provider\& ^&Requestor\& .! .blank;.test page 3;.indent -20 # <----- the requestor requests an event with code RQST$K__NEXT__EVENT and with RQST$V__PENDING clear. .! .blank;.test page 3;.indent -20 -----> # the provider either supplies an available event or responds with one of the status messages described in Section 2.2.2. .! .left margin -20 .! .! .! .header level 2 Simple Request With Signals The following instance describes the sequence of messages when the requestor requests an event and will wait for the event to become available. .! .left margin +20 .tab stops 10, 20 .! .blank .test page 5 .indent -20 ^&Provider\& ^&Requestor\& .! .blank;.test page 3;.indent -20 # <----- the requestor requests an event with code RQST$K__NEXT__EVENT and with RQST$V__PENDING set. .! .blank;.test page 3;.indent -20 -----> # the provider replies with RPLY$__RQST__PENDING, that is, no event is currently available to satisfy the request. .! .blank;.test page 4;.indent -20 # . the #requestor #waits #for a signal #from the .break;.indent -20 # . provider ... .break;.indent -20 # . .break;.indent -20 # . an event becomes available. .! .blank;.test page 2;.indent -20 -----> # the provider signals the requestor with SGNL$__EVENT__AVAIL. .! .blank;.test page 1;.indent -20 # <----- the requestor re-requests the event. .! .blank;.test page 1;.indent -20 -----> # the provider supplies the event. .! .left margin -20 .! .! .! .header level 2 Multiple Tranfer Request The following instance describes the sequence of messages when an event (or buffer of events) is to be sent across the link in more than one transfer. See Section A.1 for more information. .! .left margin +20 .tab stops 10, 20 .! .blank .test page 9 .indent -20 ^&Provider\& ^&Requestor\& .! .blank;.test page 2;.indent -20 # <----- the requestor requests an event with code RQST$K__NEXT__EVENT with RQST$V__PENDING set. .! .blank;.test page 4;.indent -20 -----> # the provider has an event available, thus no signal is sent. The provider notifies the requestor, with a RPLY$__CONT__EVENT message, that the data will be sent N transmissions. .! .blank;.test page 2;.indent -20 # <----- the requestor now requests the first transfer with a RQST$K__CONT__EVENT request. .! .blank;.test page 2;.indent -20 -----> # the provider starts supplying the data with the first transfer. .! .blank;.test page 1;.indent -20 # <----- the requestor requests more data with RQST$K__CONT__EVENT. .! .blank;.test page 3;.indent -20 -----> # the provider sends another chunk of the data. .! .blank;.test page 7;.indent -20 # . the back and forth scheme with #the requestor .break;.indent -20 # . sending #RQST$K__CONT__EVENT #and #the provider .break;.indent -20 # . sending back data continues, until the provider has no more data (N transfers total). .! .blank;.test page 2;.indent -20 # <----- the requestor requests the last transfer of data with another RQST$K__CONT__EVENT. .! .blank;.test page 3;.indent -20 -----> # the provider sends the last piece of data. Even if the data has the length of a status message (remember, message length is the only way to distinguish data from status replies), the requestor "knows" data was received since the provider told the requestor how many transfers were necessary (with the RPLY$__CONT__EVENT message sent at the beginning). .! .blank;.test page 5 this is the end of the sequence of messages. However, if for some reason ... .blank;.test page 3;.indent -20 # <----- the requestor miscounted the number of transfers and sends another RQST$K__CONT__EVENT. .! .blank;.test page 3;.indent -20 -----> # the provider replies with RPLY$__NOSUCCESS, which informs the requestor that a multiple transfer transaction is not in progress (anymore). .! .left margin -20 .! .blank The above instance was shown with RQST$V__PENDING set. The protocol permits RQST$V__PENDING to be clear also. The only difference between the above instance and the first two instances of the protocol is the number of transfers required by the provider to satisfy a request. In order to synchronize the provider and requestor, the back and forth protocol is used at all times. The back and forth protocol can be "disrupted" when the provider is unable to satisfy the requestor's RQST$K__CONT__EVENT request. Rather than just sending a status message, which the requestor may assume is data, the provider "warns" the requestor of the error by sending a signal first, and then the status message. .! .left margin +20 .tab stops 10, 20 .! .blank .test page 5;.indent -20 ^&Provider\& ^&Requestor\& .! .blank;.test page 3;.indent -20 # . .break;.indent -20 # . a multiple transfer request is in progress. .break;.indent -20 # . .! .blank;.test page 3;.indent -20 # <----- the requestor requests more data with RQST$K__CONT__EVENT. .! .blank;.test page 3;.indent -20 -----> # the provider is not able to satisfy the request and informs the requestor with a signal, SGNL$__ERROR. .! .blank;.test page 3 the requestor should treat the next message as a status message rather than the expected data. .! .blank;.test page 3;.indent -20 -----> # the provider sends the requestor a status message describing the problem. At this point the sequence of messages (multiple transfer request) is complete. The back and forth protocol resumes. .! .left margin -20 .! A multiple transfer transaction can be terminated by the requestor by sending any request other than RQST$K__CONT__EVENT. The provider will terminate the multiple transfer request and begin processing the new request. The request RQST$K__ABORT should be when the requestor has no intentions of requesting anything, but wishes to abort the multiple transfer request; the provider will reply with either RPLY$__SUCCESS or RPLY$__NOSUCCESS. .! .! .! .header level 2 Booking/Unbooking Requests The following instance demonstrates the sequence of messages used to set up a booking request and then read events collected for the booking. .! .left margin +20 .tab stops 10, 20 .! .blank .test page 4 .indent -20 ^&Provider\& ^&Requestor\& .! .blank;.test page 2;.indent -20 # <----- the requestor requests a booking with code RQST$K__BOOK__RQST. .! .blank;.test page 3;.indent -20 -----> # the provider notifies the requestor that the booking is successful by returning RPLY$__SUCCESS. .! .blank;.test page 3;.indent -20 # . from this point, #the #protocol for obtaining .break;.indent -20 # . booked events #is the same as shown in either .break;.indent -20 # . of the above examples, except that RQST$V__BOOKED is set (the requestor is permitted to mix booked (RQST$V__BOOKED is set) and non-booked (RQST$V__BOOKED is clear) type requests). Finally, the requestor decides to no longer look at events and ... .! .blank;.test page 3;.indent -20 # <----- the requestor requests that the collection of events be unbooked with code RQST$K__UNBOOK__RQST. .! .blank;.test page 3;.indent -20 -----> # the provider responds with either RPLY$__SUCCESS in which case the collection has been unbooked; or RPLY$__NOSUCCESS, in which case the requestor reports an error (but should also treat this reply as if the collection has been unbooked). .! .left margin -20 As mentioned above, the requestor is permitted to mix booked and non-booked type requests. The requestor should realize that the provider is not restricted as to which event is supplied for the non-booked type request; the data may even be supplied from data collected for a RQST$K__BOOK__RQST request. .! .! .! .appendix Notes for Implementors .! .header level 1 Sending an Event in More Than One Transfer An event or buffer of events may be supplied by the provider in more than one transfer across the link. The requestor must be prepared to receive an event or buffer of events in more than one transfer. This provision is made due to limitations in RSX-11M Bulk Memory DA systems. The provider requires a window into the bulk memory. At present, there is only one 2K word window, as each bulk memory window reduces the amount of physical address space (by 2K words) available to run other tasks. If a whole event, up to 2K words had to be sent across the link in one transfer, it would require two 2K word windows into bulk memory. Larger events or buffers of events would require more 2K word windows. Therefore, to minimize the windows required, multiple transfers per event (or buffer of events) must be permitted. .! .! .! .header level 1 Special Considerations for RSX-11M Systems Besides the consideration mentioned above, in an RSX-11M system, careful consideration must be given to questions of memory residence and checkpointability of tasks. A requestor task which requests an event is at that moment in memory. It should remain in memory (non-checkpointable) until a reply is received. Therefore, replies from the provider should be made immediately. After receiving a reply, the requestor may become checkpointable again. If the requestor is informed that no event is available, it should remain in a checkpointable dormant state until it is signalled that an event is available. At this time, the requestor should re-request the event. The requestor may remain checkpointable when waiting for a signal, as signals sent over the link do not tie up the link. They are received and the signal value is queued to the task, even if the task is not resident in memory. When the task becomes resident, it will receive the signal. Therefore, the requestor will receive the signal and re-request the event, immediately receiving the event. If the block of data (in this case, an event or buffer of events) were to be sent randomly, there would be a risk of tying up the link and producing a memory deadlock condition. For example: .! .left margin +5 .blank .! Task A in machine 1 requests an event from Task B in machine 2. Task A is checkpointed. Task B begins to send a message to Task A. During this transmission, Task C in machine 1 queues a request to write a message over the link to some task in machine 2. Task A cannot become memory resident to receive its message over the link from Task B because Task C has already queued a request to write a message over the link. Task C's message cannot be sent because B's message to A is already in progress tying up the link. .! .left margin -5 .! .blank All such potential deadlock situations can be handled by 1) properly using the protocol and 2) use of provided subroutines which handle checkpointing and timeouts on requests for events, or 3) by making sure the tasks are non-checkpointable.