.comment; AMI$LIB:[MECHANICS.DOC]MECHANICS.RNO .comment; Last Edit: jmb - 16-MAY-1988 09:29:12 .comment; Author: Jim Bostwick .comment; History: .comment; .comment; MECHANICS Chapter of AMI Message System User's Guide .comment; .CHAPTER MECHANICS .skip 2 .center; ABSTRACT .lm +10 .rm -10 .sk 1 This chapter defines the overall function and operation of the AMI Message system. An attempt is made to employ plain english narrative style, and to avoid myriad detail. This chapter is intended to present a general knowlege of how the messaging system works. .sk 1 .lm -10 .rm +10 .hl 1 Introduction At this point we know what a message is, and that the AMI Message system (AMIMESS) exchanges these critters between VMS and RSX DECNET nodes. Before delving any deeper into the details of bits, bytes and so on, a narrative description of the use and operation of the system is in order. The aim here is to answer the 'big' questions, while defering the 'little' ones for later chapters. .hl 1 What it is The message system allows one program to exchange messages with another, whether the other program is on the same or different network node. The programs need to know only the task and node names ( we'll call these two names the "address") of the recipient task. It is possible to hard-code the address information into a program, but this is the least desirable and least flexible technique available. A better procedure would be to use logical names to define the address at run-time. Also, a 'directory' function is defined which allows a task to ask the message system to locate the node name of a given task. Either of these methods will allow the tasks to 'move' (usually in response to a hardware failure or major re-configuraton), without requiring recoding of the address information. Note that the general technique will be to have initialization code in the tasks which determines the address info for all, or most, tasks it may wish to talk to. While there is nothing in the message system to prevent dynamic reconfiguration, this is not generally supported on AMI systems. Under RSX, initialization will be optional. Because the underlying mechanism is the send-data facility, a task will be able to send and receive messages without any initialization other than the message header. However, VMS tasks must call an initialization routine. This is because VMS uses the mailbox mechanism, and must create the mailbox before messages may be received. Once the address information is inserted in the message header, the complete message is sent out by calling a library routine. The sending task always calls this routine, regardless of destination. The library routine determines (from the header) whether the destination node is local (that is, the same node as the sender) or remote (some other node). For local addressees, the message is sent directly to the addressee task, while for remote addressees, the message is sent to the message router on the LOCAL node. The 'direct routing' for local messages increases performance greatly, because the router task is bypassed. For remote addressees, the message actually takes three 'hops': from source task to source router, from there to destination router (via DECNET), and from destination router to destination task. .hl 2 Local Send Mechanics On RSX systems, messages are sent locally using the VSDA$ (Variable Send Data) directive. This directive basically copies the message to a RSX-owned buffer in secondary pool, and hangs a notice on the destination task's receive data queue. The receiving task does a VRCV$ directive to pick up the message. For VMS, the mailbox mechanism is used. Each potential receiver task creates a named mailbox during initialization. Messages are then sent (written) to the mailbox, and the receiving task does mailbox reads (e.g., read to the mailbox pseudodevice) to pick them up. While VMS mailboxes are inherently read/write devices, the message system requires that the message mailboxes be read-only to the creating task. Thus each task writes to potentially several addressee's mailboxes, and reads from it's own mailbox. The messaging system does not employ any throttling mechanism to regulate how many messages may be outstanding at any one time. There are, however, both intrinsic and explicit limits imposed by both operating systems. For RSX, the limit is the amount of Secondary Pool available for buffering messages. If this (system-wide) limit is exceeded, the VSDA$ directives will fail, (along with numerous other system functions). Sufficient secpool must be provided, and/or application-defined synchronization mechanisms employed to prevent this situation. VMS limits mailbox traffic on a per-mailbox (actually per-process) basis, and on a system-wide one. Mailbox size (buffer capacity) is defined by the process during the mailbox create call. Writes into a mailbox will fail if the mailbox is full. Although it should never happen, the system-wide buffer capacity may be exceeded, even though no individual mailbox is full. .hl 2 Remote (Router) Mechanics Each node using the messaging system will have one default router task which is always active. Additional, special-purpose routers may exist. These need not actually be message-routers. For example, a translation deamon could be defined to operate within the message system. The default router will open and maintain DECNET links with all other default routers in the system during startup. Thus, a message may pass from source to destination node in a single hop. Multiple hop messages (router forwarding) are not defined. Router tasks perform several functions. They accept messages from the local node and pass them to remote router tasks. Conversely, messages sent by remote routers are passed to destination tasks on the local node. Routers also handle various control messges, which tell the router itself what to do. An important control message is the directory lookup request, which an application task uses to determine the current location of another task. Routers also handle minor translations between VMS and RSX systems. For example, VMS mailbox names are stored in ASCII, while RSX task names are in RAD50. The local router will handle conversion of messages being sent to a 'different' system. Thus, the router always receives messages in a single format - the 'native' format for it's host system. .hl 2 Error Handling There is minimal built-in error detection and handling in the message system. In particular, it is tacitly ASSUMED that, if a source task succeeds in sending a message out, the message is received at the destination. This assumption is obviously not always going to hold up. However, no efficient and general mechanism is available to guarantee receipt of all messages. Instead, 'return receipts' (to once again visit the post-office analogy) are left up to the application tasks to implement. For locally delivered messages, the send routine will know that hte message was delivered to the destination receive queue - but NOT that the destination task actually read it. For remote messages, the sending task will know only that the message was posted to the local router's receive queue. Routers which cannot deliver messages for whatever reason will simply throw the message away. No attempt will be made to inform the sender. Again, even if delivery to the destination receive queue (or mailbox) succeeds, there are no guarantees that the destinatino task read, much less understood, the message. Although this seems a highly draconian behavior on the router's part, it is reasonable for the following reasons. First, really important messages must be acknowleged by the destination task. This is the only way to guarantee that the destination task understood the message. Second, implementation of automatic acknowlegement of all messages would drastically increase the overhead involved in running the message system. Third, many mechanisms are possible which are appropriate to different applications. For example, a periodic "I'm still here" message may suffice for some applications, while a "I got your last ten packets" type would be better for a different application. Finally, certain applications (such as logging tasks) probably don't need to acknowlege messages at all, on the theory that if the system is sick enough to drop error log packets, it needn't bother trying to inform itself of that fact. .hl 2 Receiving Task Notification Although a number of ways exist for making recipient tasks aware of new messages, by default the router will do nothing. The receiving task will be responsible for peridically checking for incomming messages, or for using a mechanism such as receive-data ASTs. However, provision has been made for defining other actions, such as 'send and request', or 'unstop'. If these are used, it is up to the sending task to 'know' which mechanism the reciever is using, and set the appropriate flag(s) in the message header.