.comment; AMI$LIB:[MESSAGE.DOC]MESSAGE.RNO .comment; Last Edit: jmb - 4-MAY-1988 18:21:34 .comment; Author: Jim Bostwick .comment; History: .comment; .comment; Message definition Chapter of AMI Message System User's Guide .comment; .CHAPTER MESSAGE .skip 2 .center; ABSTRACT .lm +10 .rm -10 .sk 1 This chapter defines the message format in detail, and describes the function of each field. Sample record definitions in both VAX Pascal and Oregon Pascal are provided. .sk 1 .lm -10 .rm +10 .hl 1 Introduction This chapter will define the message system 'external' data structures in detail. External data structures are those 'seen' by the applications programs which use the message system. A message consists essentially of two sections: header and body. The message header contains fields for source, destination, router, and control flags. The body is an arbitrary-length array containing the 'text' of the message. Because messages are variable-length structures, a convenient means of describing any arbitrary message is the message descriptor. .hl 1 Message Descriptor The message descriptor is not part of the message, but rather describes it. It is never sent between systems. In reality, a formal structure called a message descriptor is not required. The message descriptor consists of two words. These are 16-bit words in RSX systems, and 32-bit longwords in VMS. The first word contains the memory address of the start of the message, and the second word contains the byte count of the message. For both systems, the message size is limited to 512. bytes. .note VMS could deal with much larger message sizes. Future extensions to the message system may remove the 512. byte restriction for VMS-VMS messaging. However, RSX will always be restricted to 512. total bytes. Furthermore, applications must agree on the largest message size that they will receive. More on this later. .end note Note that the descriptor treats the entire message (header and body) as a single structure. The message must be contiguous, and must be word-aligned in memory. [The provided record definitions will ensure that messages are word-aligned.] Again, there may not be a formal structure (i.e., Pascal record definition) for the descriptor. A library routine which takes the address as one parameter and the bytecount as another is perfectly permissible. .hl 1 Message Header The message header contains routing and control fields, which govern the handling of the message by the system. The following pseudo-record definition describes the header fields. Detailed explanations of each field follow. .sk .nf Type Message_header = Record Destination_task : Task_name; Destination_node : Node_name; Sender_task : Task_name; Sender_node : Node_name; Router_name : Task_name; Message_Flags : Byte; User_Flags : Byte; User_Protocol : Byte; User_Spare : Byte; Byte_Count : Word; {0..(512.- header_size)} end; Type Node_name = CH6; { 6-char string } Word = 0..65535; { 16-bit word } For VMS: Type Task_Name = CH6; { 6-char string } Const Header_size = 36; For RSX Type Task_Name = RAD56; { 6 Radix-50 characters } Const Header_size = 30; .f .sk .hl 2 Task Names Task names differ between VMS and RSX. For RSX the task name is the installed (e.g., running) task name known to RSX. This is always expressed as two words of RAD-50 data in RSX. For VMS, the 'Task Name' will actually be the name of the associated mailbox. All tasks which use the message system are required to create a named mailbox, and the name must be six or fewer characters. Note that the process name is not restricted - the message system deals only with the mailbox. .hl 2 Node Names All node names are defined as six ASCII characters, trailing blanks allowed. .hl 2 Message Flags The flags byte is treated as a bit mask where each bit controls a given router option. A zero flags byte will result in the defined default routing action. Current definition of the control bits is as follows: .sk .lm +10 .nf b0 = 1 ==> Router Control Message if set b1 = 2 ==> Run Destination Task b2 = 4 ==> UnStop (Wake) Destination Task .f .sk .lm -10 Undefined bits are reserved for future enhancements to the message system. .hl 3 Router Control Message A router control message (or just control message) is destined for the router itself, as opposed to some destination task. Note that router control messages for remote node routers are permitted. If this bit is set, the message is either passed to a remote router, or interpreted directly by the local router, based upon the destination node name. The router's action is dictated by the content of the message body, which is defined in a later section. .hl 3 Run Destination Task If this bit is set, the destination router will attempt to start (run) the destination task, after sending the message to it. This function is intended for RSX systems, and then only for tasks which are seldom run. It allows an installed task to remain dormant, and thus off the ATL, until needed. This saves primary pool. For RSX this implies a VSRC$ (variable send, request, and connect) directive. Documentation indicates that a null status block may be specified, thus transforming the directive into a send and request function. Only installed conventional (non-prototype) tasks may be specified. For VMS, this function is handled as an UnStop request. There is no clean mechanism for running a dormant process in VMS, and little motivation to do so. .hl 3 Unstop Destination Task Many server tasks will process all available messages, then 'sleep' until there is further work to do. This control bit allows such tasks to enter either the 'STOP' (RSX) or 'hibernate' (VMS) state. The message router will then issue an USTP$ (RSX) or $WAKE (VMS) directive after sending the message. This provides a simple, efficient, and general mechanism for implementing server tasks. .hl 2 User Flags A byte is reserved for user-defined flags. The message system ignores this byte. Possible uses for this byte are flags such as "system shutdown", "restart", etc. .hl 2 Message Protocol This field shall hold an integer identifier for the message protocol at the user (application) level. There is only one protocol for the message system itself. Multiple application-level protocols may be defined, which specify message formats, handshaking, and so forth. Thus, the protocol field is only meanigful in the context of the tasks exchanging messages. If the message is a router control function (B0 of the flags byte set), then this field specifies the router control protocol, rather than the user protocol. User protocols are expected to remain unique among AMI supported systems. They are also expected to be documented, and designed with as much generality as is appropriate. It is hoped that the number of distinct protocols supported by AMI may be kept to a minimum. Control protocols are defined independantly of user protocols, but will otherwise conform to the previous paragraph. It is envisioned that very few control protocols will exist. An example control protocol might define handshaking messages for an alternate, store-and-forward, message router. User protocol 0 is reserved, and implies no handshaking, or other special handling. In other words, protocol 0 is as 'vanilla' as it is possible to get. Control protocol zero is reserved, and is used for basic router control messaging. That is, for the default router. Protocols 200-255., inclusive, are reserved for experimental use. Do not use this range for production software. .hl 2 User Spare This byte is undefined, and ignored by the message system. It is guaranteed available for user functions. .hl 2 Byte_Count This field contains the byte count for the message body. Total message size is thus header_size plus the byte count. Messages with zero-length bodies are allowed. Of course, the message length will always be at least header_size bytes. .hl 2 Notes As defined, the header_size is different between VMS and RSX. This is due to the different implementation of task names between the two systems. The router task handles all translations between systems. Because the message will have to be copied from a network buffer into a send-data or mailbox one, the performance penalty will be minimal. .hl 2 User Fields The User FLags and User SPare fields allow simple messages to be application defined which contain no body. This may simplify application design. However, thought should be given to the implication of using the header rather than message body. Header information should remain essentially control information. One possible use of these fields is for acknowlegement. For example, the logical messages "I got your last 5 messages, and here is some new status" could be wrapped in a single messge, with an 'ack' bit in the user flags, '5' in the user byte, and the status message in the body. System-wide functions could also be defined for the user flags byte. Examples might include 'system shutting down', 'resynchronize', 'switch log files' and so on. .hl 1 Message Body The message body consists of a variable length array of bytes, which is contiguous with the message header. No interpretation is made of the body by the message system. Content is strictly up to the sending task. Zero-length messages are permitted, meaning that a header only is sent. Note that neither VMS nor RSX permit true zero-length messages. The message body is often refered to as the 'message text'. .hl 2 Alternate Definitions Although the message header is fixed in length and format, the body is very loosely defined. Multiple record definitions, each defining the body differently, are both permitted and encouraged. For example, a message record whose body consists of a variable-length string is permitted. The only requirement in this case is that the actual (or max) string length, including the string length byte or word, be placed in the Byte_count field of the header. In such a case, the size byte of the string would be unknown to the message system - that is, just another data byte. Complex record definitions are possible. The only restriction is that total message size not exceed 512. bytes, and that the proper bytecount be placed in the header. The Pascal Size functions will return the size of a data structure, and may be of value in this regard. Sender and receiver task need not agree as to the definition of the text field - at least from the message system's standpoint. However, such behavior is obviously highly error prone, and would be used only in special cases.