\magnification=\magstep1
{

\hoffset=0truein
\hsize=6.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 4.9truein
\large
EDOC315\par
\vskip 2.5truein
\hrule height 2pt
\vskip 20pt
\large
MIDAS DATA ACQUISITION SYSTEM\par
\vskip .5truein
Event Data Transfer - RPC Program Specification\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 1.0\par
\vskip 5pt
April 1997\par
\vfill
\medium
Nuclear Physics Support Group\par
\vskip 5pt
Central Laboratory of the Research Councils\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{}

\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 .4in

This document describes the Event Data Transfer RPC procedure
used within the Midas Data Acquisition System. The procedure is
used to transfer formatted event data between an Event Builder
System and the Midas Tape Server. It is also used to broadcast
formatted event data when the Event Builder and Tape Server are
combined into a single system.

A single procedure is defined within the Tape Server RPC program 
which should be consulted for further details. See documents
EDOC020, EDOC097, EDOC304 and EDOC305.
 
This protocol is an application carried by the RPC protocol
which is described in the Eurogam document 
{\it Remote Procedure Call}.
 
\vskip .5in
{\large History}

Edition 1.0 April 1997 - first entered into document database.

\vskip .5in

{\large Operation }

Formatted event data blocks are 4 Kbytes or 16 Kbytes in length 
(dependent on event builder implementation). These are sent as
a sequence of up to 12 data fragments dependent on the network
medium type being used.

The server operates a "window" for each data stream which is the
number of data fragments which the client may send. The data fragments
are sent using the Event Data Transfer RPC procedure but unlike 
standard RPC procedures the server normally does not send a 
response unless requested by the client. 
The procedure reply may be sent by the server at any time and 
returns to the client the status of all data streams which includes
an update to the permitted transfer window.

This transfer protocol does not claim to be a "reliable" data 
transfer protocol in that no attempt is made to ensure that 
all data from the client is received correctly by the server. There
is however a  significant improvement in the data rates achievable
by the method over the standard "reliable" methods. The server
maintains statistics on the number of data fragments known to have
been lost using the procedure sequence number. Implementations 
can tune the data transfer "window" sizes used to the hardware 
characteristics of the network interfaces. In this way actual 
data lose can be made zero or very close to zero over long
periods of time. 
 
\vfill\eject 


{\large Program Specification}          
\vskip .5in

{\bf RPC Information}
\parindent=36pt
\item{}The EGTS service uses only the Null authentication  
\item{}This is supported on the UDP/IP transport only 
\item{}This is RPC Program 28000205   
\item{}This is Version 4 of the RPC program
\item{}Uses UDP port numbers 10205, 10206 and 10207
\parindent=0pt

The UDP port number is selected by the data acquisition instance in use. 
Several data acquisition systems using different port numbers can be supported by one 
tape server system.

\section{Procedure 31.\quad Transfer Event Data}
\heading={REQUEST}
\table
\half{EG data stream}
\full{capability}
\half{transfer options}
\half{sequence number}
\half{offset}
\half{event data length}
\data{event data}
\endtable
\desc
Transfers a fragment of the current event data block
from the client (event builder)
to the server (tape server).
\enddesc
{\sl EG data stream} identifies the logical data stream  for this data fragment.
It should be in the range 1 to 4. Many event builder implementations only support
one data stream in which case {\sl EG data stream} always has the value 1.  \lb
If {\sl EG data stream} = 0 then no further parameters or data follow and the server 
will send a reply. This can be used by the client to force the server to return its
stream status information.

{\sl capability} is an 8 byte (64 bit)
opaque field generated by the server and used by the client
as an access token. For the event data transfer procedure the 
capability field always contains nulls.
 
{\sl transfer options} \lb
Least significant bit (End bit) = 1 -  The following data is the last fragment of the current 
data block. The next request should have offset = 0. \lb
Least but one significant bit (Reply bit) = 1  -  The client does not require that the server
reply to this request.

{\sl sequence number} should be incremented for each procedure call. At any time 
the client may reset the sequence to zero. The server will  not consider it to be a fatal
error if it detects a sequence number error and will reset its expected sequence number
using the value received.

{\sl offset} is the start address of this data fragment in the current data block. Offset = 0 
implies that the following data fragment starts a new data block. \lb
{\sl event data length} and {\sl event data} define the data fragment.

\heading={RESPONSE}
\table
\half{procedure status = 0}
\half{EGTS state}
\half{value=true}
\half{EG stream}
\half{EG stream state}
\half{sequence}
\half{window}
\data{repeat for all 4 EG streams}
\half{value=false}
\endtable
\desc
The standard reply from the server is sent only for those requests for which a
reply is required. The state of all 4 EG data streams is sent regardless of the
number used by the client implementation.
\enddesc

\smallskip
\settabs\+
\qquad&EGTS state=xxxx\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& EGTS state=&  1  & halted    \cr
\+&     &  2  & going \cr

\smallskip
The fields {\sl EG stream}, {\sl EG stream state}, {\sl sequence} and {\sl window}
are repeated for all 4 EG data streams.

\smallskip
\settabs\+
\qquad& EGTS stream state=xxxx\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& EGTS stream state=&  1  & disabled    \cr
\+&     &  2  & enabled \cr

\smallskip
sequence - last sequence received for this EG data stream

window - number of data fragment requests permitted for this EG data stream 

 
\vfill\eject

\endGroup
\end
