.comment; AMI$LIB:[MESSAGE.DOC]INTRO.BLR
.comment; Last Edit: jmb - 29-APR-1988 14:53:59
.comment; Author: Jim Bostwick
.comment; History:
.comment;
.comment; Intro to users' guide for AMI network messaging system
.comment;
.CHAPTER INTRODUCTION
.skip 2
.center; ABSTRACT
.lm + 10
.rm - 10
.sk 1
An introduction to and overview of the AMI network messaging system
is presented. Groundwork is laid via comparison of AMINMS with other
common networking/messaging systems, including DECNET. 
.lm - 10
.rm - 10
.sk 2
.hl 1 Getting Started
 The hardest part of describing any serious piece of software is where to 
begin. With software, perhaps more than any similar (and are there similar)
undertaking, one almost has to pick a spot, and go around at least once, 
before things start to make sense. Building a barn is much easier: you start
by describing the dimensions, then the foundation, frame, and so on. 
 The gross functionality of the system described here can be stated fairly
easily:
.sk
.i 10
"Provide a mechanism whereby tasks running on RSX or VMS systems may send
messages to other tasks running on the same or different network nodes."
.sk
Well, that's nice, but, like all one-liners, leaves much to the imagination. 
So, lets start by characterizing and qualifying the above statement a bit. 
.hl 1 Messages
 A message consists of several pieces of information. A good analogy is 
that of the postal letter. A letter consists of destination name and address,
return address, postage, the envelope, and finally whatever the sender 
put in the envelope. 
 A message contains the same information (except for the stamp!), but 
arranged somewhat differently. The envelope is replaced by the MESSAGE
HEADER. This is a record consisting of several fields which identify 
the sender, recipient, and provide control information, plus describe
the size of the TEXT. The Text corresponds to the contents of the letter,
and is a copy of an arbitrary chunk of memory. 
 Like the postman, the message system is only concerned with moving the 
text (the letter) from one place to another. Neither cares what is in
the letter, only how big (heavy) it is, and where it is going. 
 So, we will talk about MESSAGES and TEXTs. The text is the information
which the sending task want's the receiver to have. The rest (the Header)
is overhead required to get the text to it's destination. 
A (not the only) Pascal record definition for 
a MESSAGE is:
.sk .lm + 10
.literal
TYPE
    Message = RECORD
	Hdr: Msg_header;  { a sub-record we haven't defined yet }
	Len: 0..MAX_LEN;  { an RSX, 16-bit, integer }
	Text: Array [1..Len] of byte; 
	end;
.end literal
.sk .lm -10
You will note that this is not quite a legal Pascal definition, as the 
Text field ) is defined in terms of the Len field. However, it
does convey the idea of an arbitrary chunk of 'text' (anything, really),
associated with a byte count and a header. Another point is that, in
a rigorous record definition, the Len field will be part of the header. 
 We have also not defined the constant MAX_LEN yet. It's exact limit
will be defined in a later chapter. For now, assume that 500 bytes is
the longest allowable text field.
.hl 2 Message Descriptors
 Because many record definitions would be required to describe all possible
messages (roughly 500), it is also convenient to define an entity called
a MESSAGE DESCRIPTOR. This is nothing more than a small record:
.sk
.lm +10
.literal
TYPE
	Message_Descriptor = RECORD
		msg_len: 0..max_len+hdr_len;
		msg_adr: Address;
		end;
.end literal
.lm -10
.sk
This is a much more convenient way to describe our arbitrary messages, because
one record suffices to describe all possible messages. Note that the header
has disappeared! This is because the message system views the message record
as just a chunk of bytes starting at some address. The message descriptor
defines the entire message - header and text - as one entity. The header
fields must of course still be in there, or strange and probably unfriendly
things will happen to the message! 
.hl 2 Message Contents
 So far, nothing has been said about the contents of the message text field. 
This is because the messaging system doesn't CARE what is in there. So, it
imposes no restrictions on the content of a message text. Like a postman,
the messaging system does not know or care what is in a letter, only that
the address is legitimate. ( The message system is not concerned with
getting the postage right.)
.sk 2
 In summary, then, a MESSAGE consists of a HEADER (including a byte count )
and a text field,
which must be less than about 500 bytes. A MESSAGE DESCRIPTOR consists of 
a different byte count, plus the address of the entire message.  
We don't care what
is in the text frame, only about it's size. A MESSAGE HEADER consists of 
several fields which identify the sender and recipient of the message. 
.hl 1 Tasks
 Letters are passed between people (occasionally between a computer and a 
person, but that's another can of worms). Messages are passed between tasks. 
Simply put, a TASK is a single program which is known to the system upon
which it is running. Under RSX, the program is called a "task", and is 
known to the system by being INSTALLED. In VMS, a known program
is called a PROCESS (there may be sub-processes or detached processes, but
all are processes). However, the process need not be installed to be known. 
In fact, under VMS, we really identify a potential sender or reciever of 
a message by a Mailbox name. More on this later. 
 For now, suffice it to say that messages are exchanged between programs.
The term 'task' will refer to either an RSX program or the VMS analogue. 
.hl 1 Routers
 A router is, in the messaging system, a task which accepts messages from
other tasks on the local node, and forwards them to a cooperating router
task on a different node. The cooperating router (called the destination router)
then forwards the message to a task (the destination task) on that node. 
Although we use the term router, such a task might also be recognized as
a "message server". 
 In short, the sending task gives its' message to the router, who (like
a postman) passes it to another router, who delivers it to the final
addressee. Because the router is on the same node as the sender, it is
much easier for the sender to talk to him than to the addressee. 
.note
For performance reasons, the messaging system also supports direct
message passing between tasks on the same node. This is done transparently
to the task, in all but the lowest subroutine levels. 
.end note
 There are many reasons for employing routers in a RSX/VMS network. 
While it is certainly possible for two tasks to set up various direct
communications paths, doing so across two nodes involves a considerable
amount of overhead. The programs (and programmers) need a fair amount of 
knowlege of network (DECNET here) mechanics. At run time, the programs
also incur relatively large overhead in establishing network links. 
The system would suffer from the need to maintain large numbers of links, and
their associated data structures. 
 Even in a network environment, most traffic will be between tasks on the
same node. Using a DECNET link between two tasks on the same node is 
possible, but is certainly the long way around, and is horribly inefficient
relative to other available messaging facilities. Even passing a message
through a router is a waste of resources, which is why the system supports
direct links. 
 However, SOME traffic is likely to involve other nodes. By using
a router, all traffic (from the tasks' point of view) is on the same node. 
This allows the task to use one function to talk to any task - local or 
remote. 
 It would seem that involving two additional tasks (the routers)
in a cross-node message would incur large performance penalties. However,
as you will see, in many cases, the performance will actually be much
better through a router than via direct network connections. This is 
especially true when relatively low volumes of data must be exchanged between
relatively large numbers of tasks. A pair of tasks which merely want to 
pump high-volume data between themselves will do better to establish
a dedicated link - and should do so. 
 In the AMI message system 
definition, only two routers will be involved in any message - that is, 
each router talks to all the other routers. This scheme is designed for,
and will only work well on, small networks (perhaps a half-dozen nodes) which
have physical links between all nodes - typically ETHERNET. 
 A router can also handle the complexities of talking between systems - 
RSX and VMS in this case. Actually, very little translation is required. 
By inserting routers between VMS and RSX tasks, each task can talk it's
own native style, which both simplifies the coding, and improves the 
efficiency of VMS-VMS or RSX-RSX messaging. 
 A Router, then, is a task which accepts messages from tasks on it's local
node, and from other routers via the network, and forwards them. The router
exists to simplify application tasks, reduce network overhead, and provide
some minimal translation between systems. 
.hl 1 Philosophy 101
 At this point it seems pertinent to touch on the philosophy embodied in 
the message system design. Since no piece of software can be all things 
to all people, any program is of necessity a compromise. Knowing something
of the design tradeoffs and intended use of a program can go a long way to 
ensuring easy and efficient use of it. So, here goes. 
.hl 2 Why Do it?
 AMI systems tend to be built from sets of relatively small cooperating
programs. The sets act together to perform a given function. For example,
the FMBOS, SCSVC, and RCVWK programs cooperate to automate the car receiving
function. Multiple small tasks are generally much easier to design, write,
maintain, and manage, than would be single all-encompassing applicaitons. 
Under RSX, basic system limits virtually dictate the use of multiple tasks.
While VMS has, to all intents, no such limits, it has been found through 
hard experience that single monolithic applications, while doable under VMS,
are maintenance nightmares. 
 A basic requirement for cooperating tasks is a ready means of communicating
status and command information between themselves. While there is 
frequently also need for other communications paths (such as shared files,
or dedicated network channels), the messging requirement is nearly universal. 
 The messaging mechanism needs to be both simple and quick. Early RSX implementations
used the RSX Send/Recieve Data directives. These directives buffer small
(26. word) messages in the RSX Executive, and implement a receive queue in
each task. The method is very fast and easy to use. 
 The current design is an extension of the basic Send/Receive scheme to 
a multi-node environment. Also, the older Send/Receive is replaced by the
Variable Send/Receive directives on M-PLUS. These allow messages up to 
512. words in length, and buffer them in secondary pool. Otherwise, the 
mechanism is essentially unchanged. 
 The messaging system is intended for situations where relatively small
amounts of information (up to say a couple of thousand bytes per minute), 
are exchanged with a variety of tasks. If higher volumes of data must
be exchanged, a dedicated link, or shared file, would be the better choice.
If only one or two other tasks are in constant communication, a more efficient
method would be to set up 'permanent' dedicated channels between the tasks. 
 While the messaging system is quick and easy to use, bear in mind that there
are limits, and that overuse of the message system (that is, overloading the
system with packets) will eally put the hurt on overall system performance. 





