DS-80 Application Level Protocol D. Ritchie and V. White 10th February 1982 Rules for code executing at an application level in a connected machine system linked by DR-11W's are specified. Application Level Protocol Page 2 1.0 INTRODUCTION We would like to define rules for application-level code so that such code sees pretty much the same environment with respect to the DR-11W link transactions whether it or its partner is executing in RT-11 or RSX-11M. Of course, such code will differ in other respects according to whether it is executing in RT or in RSX, but at least the design of the link parts can remain the same. To take a simple example, we would like it to be possible to bring up a file transfer program in an RT machine and either an RT or an RSX file ______ __ transfer program in a connected machine and transfer files back and forth. The operation of the application in the first RT machine should be oblivious of whether it is talking to an RT machine or to an RSX machine. The same, of course, holds true if the first machine is an RSX one and it is the second which may have either operating system. As another example we would like a MULTI analysis to be able to get its events from either an RSX or an RT DA machine. In Sections 2 and 3 below, we indicate some of the features we wish to see in the application environment and explore some of the implications of such features. Figure 1 represents an example of a system (at application code level) with these features. In the discussion we assume that all handling of the DR11W link can be thought of as in 3 separate layers. Layer 1 - the Link Hardware itself, Layer 2 - the software handling the link transmission protocol (DS77) and Layer 3 - the Application layer. In Section 4 we examine a set of 'rules' or a protocol between applications, which will enable such a system to exist. Application Level Protocol Page 3 Application Level Protocol Page 4 2.0 DESIRABLE FEATURES OF APPLICATION LEVEL CAPABILITIES We present these features in the form of a list; the order is not significant. 1. Multiple link-related applications are allowed and expected (perhaps not immediately, but eventually) in any particular machine, whether it is an RSX machine or an RT machine. In an RSX machine these applications may reside in different tasks. In an RT machine, they will, of course, all be part of the same job, since the single-job monitor is the executive of principal use. There will still though exist different "applications" within the single job. For example, an RTMULTI system which acquired data and made use of the link might contain a "logging" application, a "locally selected events for remote analysis" application, a "run control" application, etc. The link-related activities for these applications will all arise from different parts of the single RTMULTI job, but there will still be the different applications with quite different initiating circumstances and routines. 2. Different applications should not block one another as long as the link is not actually "owned" by a current transmission. Thus, an RT machine say, may indicate its willingness to receive requests from both an analysis application and a logging application in a remote machine. If it has specified completion routines for both such requests, one or the other completion routine is sprung as the remote machine completes its sending of its request. The order in which the RT machine had informed the layer 2 software that it was willing to receive those type of requests is irrelevant as long as both such "ok's" have been processed by the layer 2 software by the time the requests from the remote machine start to arrive. 3. Multiple reads of messages for the same application should be allowed. For example, it is ok for an application such as an analysis application to make several calls to the layer 2 software requesting events to analyze as long as it provides a different buffer for each request. (It could even provide the same buffer; the layer 2 software should not care. In such a case things won't really work right but that is the application layer's problem.) These multiple reads (for the same PTC) are completed in the order in which they were queued by the application. Similarly multiple writes of data to the same application also should be allowed. The layer 2 software should queue these writes up, handling them one at a time. Thus in RT the layer 2 Application Level Protocol Page 5 software would act analogously to the magnetic tape driver in its action on multiple writes: Driver calls would be queued up and processed sequentially. 3.0 IMPLICATIONS We present the implications in the form of a list; no particular meaning is attached to the order of items on the list. 1. Operating-system-independent type applications will have packet type codes agreed upon by the individuals writing the applications under the various (VAX/VMS too!) operating systems. For example, the 8-bit packet type code representing "request for CAMAC event to analyze" will be the same for RT, RSX, and VMS. 2. A requestor does not need to know any of the details of the internal workings of the machine from which it is requesting data or services. 3. The success and error codes which are transmitted back to the application level software from the layer 2 software and the hardware below it are the same in RT and RSX when they pertain to errors noticed by these layers (on either end of the link). __ ______ ___ __ ___ ____ Success and error codes which arise from some action of the application layer at the remote end are contained within the data of a successfully transmitted reply message (with appropriate Packet Type Code) passed through the remote layer 2 and layer 1 and the local layer 1 and layer 2. Such codes are defined by agreement between the persons writing the application layer code and are not influenced by the error/success codes from the intervening layers. 4.0 SOME FORMAL RULES The above desirable features for behaviour of an application (plus some other desirable features) can actually be summarised as a set of formal rules which applications should obey. Just how the applications manage to obey these rules is a matter partly for the application layer software itself but largely for the supporting layer 2 software. A logical channel of communication from application code in one machine _ _______ _______ __ _____________ to application code in a remote machine is established by means of a Packet Type Code (a PTC). The communication channel is one way from A ___ ___ ____ _ Application Level Protocol Page 6 to B. and is established when: __ __ B indicates that it is willing to receive messages whose PTC=n (this is termed opening a session for PTC n), and _______ _ _______ ___ ___ _ A sends (i.e., writes) a message with PTC n. A success, timeout or busy outcome upon sending a message with PTC n is considered to implicitly indicate to A that the channel of communication exists. Messages sent over this communication channel, which want a reply message, must necessarily put the PTC to whom the reply is to be sent as part of the data of the message itself. Whereabouts in the data this PTC information is put is a matter for the protocol of the application code in the two machines. (For example, for the Events-for-Analysis application - IN66 - the reply PTC is the first word of the message.) The logical channel for any reply from B to A will only be established when A has opened a session which specifies the reply PTC contained in the data part of the initial message, and B finally has sent a reply message with the reply PTC. Packet type codes have an operating-system-independent meaning which specifies the application to which they are directed. Some packet type codes will of course be available for 'private' use (i.e., non-Computer Department supplied code, such as "send me the current Cherenkov counter pulse-height-to-energy calibration parameters".) 4.1 Expectations Of The Sender Of A Message 1. When an application sends a message with PTC=n there are the following possible outcomes: 1. Successful transfer of the complete message to an appropriate receiver application. 2. Successful transfer of part of the message to an appropriate receiver application. This occurs when the receiver application does not provide a buffer large enough to contain the complete message. 3. Rejection of PTC. No session has been opened for this PTC at the receiver end. (This outcome corresponds to a PTC NACK being returned by the receiver's Layer 2 software which is executing the link layer protocol - DS77) Application Level Protocol Page 7 4. Hardware error during transfer. There are many specific hardware errors which can occur, e.g., DMA timeout, DMA bad wordcount, receiver machine not responding, etc. 5. Timeout or Busy error. This indicates some serious condition whereby the receiver can not receive the message, although it has a session open for this PTC. Such a situation can arise if the receiver does not provide a buffer to receive the message within a certain time limit, or can not service the application because there are CPU or memory conflicts between applications. (This outcome corresponds to a WC NACK being returned by the layer 2 software of the receiver) The sender expects to get one of these standard outcomes whatever the target system and its associated software may be. We will arrange that the actual 16 bit error codes seen by the application layer are the same for all operating systems. 2. Applications, we assume, will only open sessions for PTCs that they are specifically designed to handle. That is, no code need be put in to handle all possible PTC's, only those that are of interest to the application. When an application receives a PTC it is then bound by the rules of the protocol for that particular class of message. These rules will be specified by the developers of the applications. 3. A channel of communication, once established will normally exist until the receiver program either exits or explicitly closes the session. The sender of messages does not expect to receive a PTC rejection once he has established that his partner is available. In the case where several messages with the same PTC could bombard a receiver it is expected that the ________ receiver end either arranges for sufficient separate buffers, of a suitable size, to be available at all times, to receive messages, or arranges that queuing for access to a single buffer is done. The sender does not expect under normal circumstances to get a 'timeout' or 'busy' outcome which requires it to repeatedly retry. This would waste link bandwidth and give no assurance of fairness of access in a heavy load situation. Application Level Protocol Page 8 4.2 Expectations Of A Receiver Of Messages 1. Application code expects to simultaneously have sessions open for many different PTCs. It must be able to receive the messages with any of these PTCs in whatever order they arrive. 2. An application which is wishing to receive messages (i.e. has one or more open sessions) must be allowed to itself send messages without disturbing its capability to receive messages. 3. An application which opens a session for PTC n does not expect to be informed that no message has arrived, only that a message with this PTC has arrived. 4. When a session is closed by an application either exiting, or explicitly closing the session, any partner with a logical channel to that receiver application should optionally be informed. (This feature is only for a second stage of development - would be very useful for file transfer applications)