\magnification=\magstep1
{

\hoffset=1truein
\hsize=5.25truein
\vsize=10.25truein
\font\small=cmssbx10 at 14.4truept
\font\medium=cmssbx10 at 17.28truept
\font\large=cmssbx10 at 20.74truept
\nopagenumbers
\hrule height 0pt
\parindent=0pt
%\parskip=0pt
\hskip 3.9truein
\large
EDOC089\par
\vskip .5truein
\large
EUROGAM PROJECT\par
\vskip 1.5truein
\hrule height 2pt
\vskip 20pt
\large
NSF DATA ACQUISITION SYSTEM\par
\vskip .5truein
Message Handling System\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 1.1\par
\vskip 5pt
June 1994\par
\vfill
\medium
NPSG Software Systems Group\par
\vskip 5pt
UK Engineering and Physical Sciences Research Council\par
\vskip 5pt
Daresbury Laboratory\par
\vskip .5truein

\eject
}
\font\large=cmbx10 scaled \magstep3
\font\small=cmbx10 scaled \magstep2
\parindent=0pt\hsize=6.25truein\vsize=9.75truein
\def\section#1{\bigbreak{\bf #1}\par\nobreak\medskip}
\def\blob{$\bullet$}
\parskip=.5\baselineskip
\def\list{\parindent=2em\parskip=0pt\smallskip}
\def\endlist{\par\parindent=0pt\parskip=.5\baselineskip}
\def\tabrule{\noalign{\hrule\vskip-0.4pt}}
\newbox\tab
\newdimen\tabht\newcount\tablines
\newdimen\savepagetotal\newcount\savepageno
\newcount\label
\newdimen\pagesum
\newtoks\stuff
\newtoks\heading

\def\lb{\hfil\break}
\def\Group#1. #2\par{
\heading={\bf Order Group    #1.\quad #2} 
\hbox{\the\heading}\nobreak}

\def\endGroup{\vfill\eject}

\def\procedure#1. #2\par{
\heading={\bf Procedure #1.\quad #2}}

\def\table{
   \label=0
   \setbox\tab=
   \vbox\bgroup\offinterlineskip
   \tabskip=0pt
   \halign to 2.0 truein \bgroup
   \vrule##\tabskip=0in plus1in\strut&
   \hbox to 0.99truein{\hfil##\hfil}&
   \vrule##&
   \hbox to 0.99truein{\hfil##\hfil}&
   \vrule##\cr
}
\def\byte#1#2{
   \tabrule
   \global\advance\label by 2\relax
   &\sl #1&&\sl #2&\cr
   }
\def\half#1{
   \tabrule
   \global\advance\label by 2\relax
   &\multispan3\hbox to 1.99truein{\hfil\sl #1\hfil}&\cr
   }
\def\full#1{
   \tabrule
   \global\advance\label by 4\relax
   &\multispan3\hbox to 1.99truein{\vrule height14.5pt depth9.5pt width0pt
   \hfil\sl #1\hfil}&\cr
   }
\def\data#1{
   \tabrule
   \global\advance\label by 4\relax
   &\multispan3\hbox to 1.99truein{\vrule height20.5pt depth15.5pt width0pt
   \hfil\sl #1\hfil}&\cr
   }
\def\endtable{\tabrule\egroup\egroup}



\def\desc{
   \tabht=\ht\tab
   \vskip24pt plus 3in\penalty-200\vskip0pt plus -3in
   \hbox{\the\heading}\nobreak\medskip
   \moveright 4.5truein \box\tab
   \savepagetotal=\pagetotal\savepageno=\pageno
   \vskip-\tabht\prevdepth=0pt
   \tablines=\tabht
%  \advance\tablines by \baselineskip
   \divide\tablines by \baselineskip
   \hangindent=-2.0truein \hangafter=-\tablines
   \vskip-\parskip
   \noindent\tolerance=2000
   }
\def\enddesc{
   \par 
   \ifnum\prevgraf<\tablines
      \advance\tablines by -\prevgraf
      \savepagetotal=\baselineskip
      \multiply\savepagetotal by\tablines
     \vskip\savepagetotal\fi}     
   

\def\block{
   \vbox\bgroup\offinterlineskip
   \tabskip=0pt
   \halign to 2.0 truein \bgroup
   \vrule              ##\tabskip=0in plus2in\strut&
                       \hfil##\hfil &
   \vrule              ##\tabskip=0pt         \cr
}

\def\entry#1{
   \tabrule
   &\sl #1 &\cr
   }

\def\fullentry#1{
   \tabrule
   &\vrule height14.5pt depth9.5pt width0pt
   \hfil\sl #1\hfil&\cr
   }

\def\endblock{\tabrule\egroup\egroup}
\tolerance=1000\hfuzz=5pt\raggedbottom
\hyphenation{key-slot}

{\large Introduction }
\vskip .5in

This document describes the Message Handling System which is a 
part of the Eurogam Data Acquisition System. 
 

It is intended that these protocols be available over a number
of communications media and hence the relevant 
{\it Communications Protocol} specification document 
should be consulted for detail in this area.
 
This protocol is an application carried by the RPC protocol
which is described in the Eurogam document 
{\it Remote Procedure Call}.
 
The general structure of the protocol is described in 
the Eurogam document {\it RPC Application Programs}.

\vskip .75in
{\large Document History}
\vskip .5in
 
Version 1.0 Sept 1991 - Initial version.

Version 1.1 June 1994 - Allow source and system names up to 16 bytes long.
 
\vskip .75in
{\large Use }
\vskip .5in
The message and error logging system comprises of three components
each of which equates to a simple RPC program protocol. This 
design allows the reporting and distribution of messages 
to be separated and the RPC methodology to be strictly 
followed.
 
Part One handles the definition  of messages. A client wishing to
report an exception condition or log activity sends the message
text via RPC to a Central Message Server. Clients typically 
will be software running in the VME processors such as the
Event Builder or applications controlling the Data Acquisition 
hardware.
 
Part Two handles requests to the Central Message System from
clients who wish to be informed of the generation of messages.
A client can register an interest in receiving a copy of a particular
subset or number of subsets of the messages sent to the
Central Message System. Clients typically will be software
running in the user workstations.
 
Part Three handles the distribution of messages to interested
parties. In this case the Central Message System acts as the
client and sends copies of messages to server software
running in the workstations nominated to receive them.
 
All messages are allocated a class and severity level by the
generating client and a workstation can nominate to be 
informed for example of all messages of a given class
(say all messages from the Event Builder) or all messages
of higher than a given severity level (say all serious errors
or worse) or any combination of these conditions. 
 
The Central Message Server in addition will timestamp 
and record on disc all received messages for subsequent
offline analysis as desired.
 
\vskip .75in
{\large Severity Level}
\vskip .5in

The following are suggested values
\smallskip
\settabs\+
\qquad&xxxx  \quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\quad&xxxxxxxxxxxxxx\cr
 
\+& 0~~~~~~~~~~~~~~~~~~~~~~~~~  &  &  \cr
\+& 1~~~~~~~test information    &  &  \cr
\+& 2~~~~~~~debug information   &  &   \cr
\+& 3~~~~~~~~~~~~~~~~~~~~~      &   &   \cr
\+& 4~~~~~~~warning~~~~~~~      &  &  \cr
\+& 5~~~~~~~~~~~~~~~~~~~~~~~~~  &  &  \cr
\+& 6~~~~~~~error~~~~~~~~~      &  &  \cr
\+& 7~~~~~~~alarm~~~~~~~~~      &  &  \cr
\+& 8~~~~~~~failure~~~~~~~      &  &  \cr
\+& 9~~~~~~~catastrophic~~      &  &  \cr
 
\vskip .75in
{\large Class}
\vskip .5in

To be supplied.
\vfill\eject

{\large Part One}
\vskip .5in
 
{\large Message Logger Program}
\vskip .2in
 
Allows clients to report exceptions, errors or monitoring information
to a central server.
 

\vskip .2in

{\large Program Specification}          
\vskip .5in

{\bf RPC Information}
\parindent=36pt
\item{}This service uses only the Null authentication  
\item{}This service is supported on the UDP/IP transport only 
\item{}This service is RPC Program 28000240    
\item{}This is Version 1 of the protocol
\item{}This service uses UDP port number 10240 
\parindent=0pt
 
{\bf XDR Information}

 Basic Data Types

\smallskip
\settabs\+
\qquad&xxxx  \quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\quad&xxxxxxxxxxxxxx\cr
\+& typedef~~ enum  $\{$     &  &  \cr
\+& & OK $=$ 0     & \cr    
\+& &                         $   $       & \cr    
\+& &                          $   $       & \cr    
\+&  $\}$ stat;        & & \cr

\smallskip
\+&typedef~~ string~~ message\_source$<$16$>$;  & & \cr   
\+&typedef~~ string~~ message\_body$<$100$>$;  & & \cr   

\smallskip
\+&typedef~~ unsigned~~ message\_id;  & & \cr   
\+&typedef~~ unsigned~~ message\_class;  & & \cr   
\+&typedef~~ unsigned~~ message\_level;  & & \cr   
 
 
\par
\vfill\eject

\section{Procedure 0.\quad Null procedure} 
This procedure does no work. There are no input parameters and
no returned results. It is made available in all RPC
services to allow server response testing and timing.

\section{Procedure 1.\quad Define Message}

\heading={REQUEST}
\table
\half{message id}
\half{class}
\half{level}
\full{source}
\full{body}
\endtable
\desc
Sends an message or error report to the Message Server.
\enddesc
{\sl Message id} is a client generated field which will be used to
distinguish between messages and possible retransmissions. This field
must be different in successive procedure requests. If a client only generates
one message at a time then {\sl message id} need only alternate
between 0 and 1.
 
{\sl Class} identifies the general nature of the message and will have
a value in the range 0 to 99.

{\sl Level} identifies the degree of importance of the message and 
will have a value between 0 (a strictly informative message such as
a process 'hello' message) and 9 (a fatal message such as an 
unrecoverable system error).
 
{\sl Source} is a text string which identifies the generating task.
 
{\sl Body} is a text string containing the message.
\heading={RESPONSE}
\table
\half{procedure status}
\half{message id}
\endtable
\desc
{\sl Procedure status} is a field which 
indicates the result of the request.
 
{\sl Message id} is returned as supplied in the request.
\enddesc
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  &  OK \cr
\+&     &     &                         \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  DefineMessage(id,class,level,source,body)   ~~~returns (status,id) & \cr
\+&        &  message\_id~~     id ;   &   \cr
\+&        &  message\_class~~ class ;   &   \cr
\+&        &  message\_level~~ level ;   &   \cr
\+&        &  message\_source~~ source ;   &   \cr
\+&        &  message\_body~~ body ;   &   \cr
\+&        &  stat~~ status ;   &   \cr
 
{\bf Procedure Interface}
 
{\bf definemessage(id,class,level,source,body)}
 
{\sl id}, {\sl class}, and {\sl level} are integer parameters.
{\sl source} and {\sl body} are character string parameters. 

{\bf Message Log File}

The server will maintain a message log file using a new file 
each day and generate a record in the file for each received
message. The entries will be entirely text, will be time stamped
and in a fixed format (except for the variable length message body).
 
\smallskip
\settabs\+
\qquad&xxxx  \quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\quad&xxxxxxxxxxxxxx\cr
 
\+& bytes~~~0-7~~~~~time stamp  &  &  \cr
\+& byte~~~~8~~~~~~~space       &  &  \cr
\+& bytes~~~9-10~~~~class       &  &   \cr
\+& byte~~~~11~~~~~~space       &   &   \cr
\+& byte~~~~12~~~~~~level       &  &  \cr
\+& byte~~~~13~~~~~~space       &  &  \cr
\+& bytes~~~14-29~~~source      &  &  \cr
\+& byte~~~~30~~~~~~space       &  &  \cr
\+& bytes~~~31 on~~~message body     &  & \cr
 
The maximum record length is thus 131 bytes.
 
\vfill\eject
{\large Part Two}
\vskip .5in
 
{\large Message Signon Program}
\vskip .2in
 
Allows clients to register an interest in receiving copies of messages
of a given class and level range.

The client may either register on behalf of its own workstation
or some other.
 

\vskip .2in

{\large Program Specification}          
\vskip .5in

{\bf RPC Information}
\parindent=36pt
\item{}This service uses only the Null authentication  
\item{}This service is supported on the UDP/IP transport only 
\item{}This service is RPC Program 28000240    
\item{}This is Version 1 of the protocol
\item{}This service uses UDP port number 10240 
\parindent=0pt
 
{\bf XDR Information}

 Basic Data Types

\smallskip
\settabs\+
\qquad&xxxx  \quad&initialiseregisterxxxxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+&typedef~~ enum~~ $\{$ FALSE $=$ 0, TRUE $=$1 $\}$ boolean; & & \cr
\smallskip
\settabs\+
\qquad&xxxx  \quad&initialiseregisterxxxxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& typedef~~ enum  $\{$     &  &  \cr
\+& & OK $=$ 0     & \cr    
\+& &                         $   $       & \cr    
\+& &                          $   $       & \cr    
\+&  $\}$ stat;        & & \cr

\smallskip
\+&typedef~~ string~~ system\_name$<$16$>$;  & & \cr   

\smallskip
\+&typedef~~ unsigned~~ message\_class;  & & \cr   
\+&typedef~~ unsigned~~ message\_level;  & & \cr   
 
 
\par
\vfill\eject

\section{Procedure 0.\quad Null procedure} 
This procedure does no work. There are no input parameters and
no returned results. It is made available in all RPC
services to allow server response testing and timing.

\section{Procedure 2.\quad Signon}

\heading={REQUEST}
\table
\half{name length}
\full{name}
\half{valid$=$true}
\half{class}
\half{low level}
\half{high level}
\half{multiplex count}
\data{:}
\half{valid$=$false}
\endtable
\desc
Allows clients to register an interest in receiving
copies of messages.
\enddesc
{\sl Name} is a string containing the network name of the workstation
on whose behalf this request is made. A null length string implies
that the request is for the client workstation.
  
Following are a number of Signon records each identifying a 
catagory of message to  be received.
For each selection 
the class and range of levels (from {\sl low level} to {\sl high level}
inclusive) of the messages required are specified.
 
{\sl Multiplex count} contains the maximum number of messages the workstation 
is prepared to accept via the Message Distribution Program 
before it must send a response.
  
Each workstation may make only one {\sl Signon} request 
which may contain as may selection requests as desired. A {\sl Signon}
request overwrites any existing request for that workstation.
\heading={RESPONSE}
\table
\half{procedure status}
\endtable
\desc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\enddesc
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  &  OK \cr
\+&     &     &                         \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  Signon(name,item)   ~~~returns (status) & \cr
\+&        &  system\_name~~     name ;   &   \cr
\+& &~~~~typedef~~ union switch (boolean valid)~~ $\{$   & \cr
\+&&~~~~~~~TRUE:                &  \cr
\+&&~~~~~~~struct $\{$           &  \cr
\+&&~~~~~~~~~~message\_class~~ class;     &  \cr
\+&&~~~~~~~~~~message\_level~~ low\_level;     &  \cr
\+&&~~~~~~~~~~message\_level~~ high\_level;     &  \cr
\+&&~~~~~~~~~~unsigned~~ count;     &  \cr
\+&&~~~~~~~~~~entry~~ nextentry;    &  \cr
\+&&~~~~~~~$\}$                &  \cr
\+&&~~~~~~~FALSE:             &  \cr
\+&&~~~~~~~struct $\{$$\}$    &  \cr
\+&&~~~~$\}$ entry;          & \cr
\+&        &  stat~~ status ;   &   \cr
\section{Procedure 3.\quad Signoff}

\heading={REQUEST}
\table
\half{name length}
\full{name}
\endtable
\desc
Cancels any outstanding Signon for the workstation identified by
{\sl name}.
\enddesc
\heading={RESPONSE}
\table
\half{procedure status}
\endtable
\desc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\enddesc
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  &  OK \cr
\+&     &     &                         \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  Signoff(name)   ~~~returns (status) & \cr
\+&        &  system\_name~~     name ;   &   \cr
\+&        &  stat~~             status   ;   &   \cr
\vfill\eject
{\large Part Three}
\vskip .5in
 
{\large Message Distribution Program}
\vskip .2in
 
Allows messages received by the central message server to be 
distributed to parties which have previously expressed an interest by
using the Signon procedure of the Message Signon Program.

\vskip .2in

{\large Program Specification}          
\vskip .5in

{\bf RPC Information}
\parindent=36pt
\item{}This service uses only the Null authentication  
\item{}This service is supported on the UDP/IP transport only 
\item{}This service is RPC Program 28000242    
\item{}This is Version 1 of the protocol
\item{}This service uses UDP port number 10242 
\parindent=0pt
 
{\bf XDR Information}

 Basic Data Types

\smallskip
\settabs\+
\qquad&xxxx  \quad&initialiseregisterxxxxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+&typedef~~ enum~~ $\{$ FALSE $=$ 0, TRUE $=$1 $\}$ boolean; & & \cr
\smallskip
\settabs\+
\qquad&xxxx  \quad&initialiseregisterxxxxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& typedef~~ enum  $\{$     &  &  \cr
\+& & OK $=$ 0     & \cr    
\+& &                         $   $       & \cr    
\+& &                          $   $       & \cr    
\+&  $\}$ stat;        & & \cr

\smallskip
\+&typedef~~ string~~ message\_source$<$16$>$;  & & \cr   
\+&typedef~~ string~~ message\_body$<$100$>$;  & & \cr   
\+&typedef~~ string~~ system\_name$<$16$>$;  & & \cr   

\smallskip
\+&typedef~~ unsigned~~ message\_id;  & & \cr   
\+&typedef~~ unsigned~~ message\_class;  & & \cr   
\+&typedef~~ unsigned~~ message\_level;  & & \cr   
 
 
\par
\vfill\eject

\section{Procedure 0.\quad Null procedure} 
This procedure does no work. There are no input parameters and
no returned results. It is made available in all RPC
services to allow server response testing and timing.

\section{Procedure 1.\quad Receive Message}

\heading={REQUEST}
\table
\half{message id}
\half{class}
\half{level}
\full{source}
\full{body}
\endtable
\desc
This has the same format as the Define Message procedure in the
Message Logger Program.
\enddesc
\heading={RESPONSE}
\table
\half{procedure status}
\half{message id}
\endtable
\desc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\enddesc
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  &  OK \cr
\+&     &     &                         \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  ReceiveMessage(id,class,level,source,body)   ~~~returns (status,id) & \cr
\+&        &  message\_id~~     id ;   &   \cr
\+&        &  message\_class~~ class ;   &   \cr
\+&        &  message\_level~~ level ;   &   \cr
\+&        &  message\_source~~ source ;   &   \cr
\+&        &  message\_body~~ body ;   &   \cr
\+&        &  stat~~ status ;   &   \cr
\vfill\eject
\endGroup
\end
