\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
EDOC097\par
\vskip 2.5truein
\hrule height 2pt
\vskip 20pt
\large
EUROGAM DATA ACQUISITION SYSTEM\par
\vskip .5truein
Eurogam Tape Server\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 2.0\par
\vskip 5pt
Aug 1995\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{\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 .3in

This document describes the Eurogam Tape Server (EGTS) protocol
specification used by the Eurogam 
 data acquisition system.
 
It is an extension of a previous document (EDOC020) which 
describes the Network Tape System (NTS); a general purpose
tape access method. This document describes only the changes and
extensions required to NTS for the EGTS environment and hence
the document EDOC020 should be read in combination with this
document.
 
It is intended that this protocol 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 .5in
{\large History}

Edition 1.0 Oct  1991 - first entry in Eurogam document server 

Edition 1.1 May 1992 - updated following implementation
 
Edition 1.2 July 1992 - add data rate information to state reply.

Edition 2.0 January 1995 - enhanced associate command (procedure 28/29)

\vskip .5in

{\large Operation }
 
\vskip .5in
 
{\large Use}
 
Throughout this document {\sl capability} is an 8 byte (64 bit)
opaque field generated by the server and used by the client as
an access token.
 
 
\vfill\eject

 
{\large Program Specification}          
\vskip .5in

{\bf RPC Information}
\parindent=36pt
\item{}The EGTS service uses only the Null authentication  
\item{}EGTS is supported on the UDP/IP transport only 
\item{}EGTS is RPC Program 28000205    
\item{}This is Version 4 of the protocol
\item{}EGTS uses UDP port number 10205 
\parindent=0pt

\vskip .3in
 
{\bf Procedures defined by NTS but NOT used by EGTS}
 
procedure 1. \quad Allocate Device \quad -  use EGTS procedure 23
 
 
 
 

\section{Procedure 24.\quad Claim EGTS}
There are no procedure specific parameters.
\desc
Requests access to the EG Tape Server resource.
\enddesc
\heading={RESPONSE - success}
\table
\half{success=0}
\full{capability}
\endtable
\desc

\enddesc
The response returns a 8 byte (64 bit) {\sl capability}
which is an opaque field generated by the server and used
by the client as an access token in subsequent procedure
requests to the EGTS. \lb
The EGTS will currently be in the halted state.

\heading={RESPONSE - failure}
\table
\half{procedure status}
\endtable
\desc

\enddesc
{\sl Procedure status} is a 4 byte field which is non zero and
indicates the cause of the failure.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  4  & EGTS already claimed \cr

\section{Procedure 25.\quad Free EGTS}
\heading={REQUEST}
\table
\full{capability}
\endtable
\desc
Releases the EG Tape Server resource.
\enddesc
The current state of the EGTS must be  halted otherwise the 
request will fail.
\heading={RESPONSE}
\table
\half{procedure status}
\endtable
\desc
\enddesc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  & success                  \cr
\+&                  &  8  & capability is invalid    \cr
\+&                  &  13 & EGTS is in wrong state   \cr

 
 
\section{Procedure 26.\quad Set  EGTS State}
\heading={REQUEST}
\table
\full{capability}
\half{state}
\endtable
\desc
state = 1 requests that the EG tape Server change to the 
{\sl halted} state. \lb
state = 2 requests that the EG Tape Server change to the
{\sl going} state. \lb
state = 3 requests that the EG tape Server change to the 
{\sl test} state.

\enddesc
The transition from halted to going will fail if any EG 
data stream is associated with a tape stream which is not
in the dev\_open state. \lb
While in the going state the close file procedure is not
permitted on any tape stream which is associated 
with a EG data stream. \lb
In the {\sl test} state all data streams are enabled and will
receive data. Data flow is controlled and checked normally but 
the data is discarded without being written to any device. The 
transition from halted to test does not require the EG data streams
to have any current association and is always permitted as long as the
current state is {\sl halted}
\heading={RESPONSE}
\table
\half{procedure status}
\endtable
\desc

\enddesc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  & success                  \cr
\+&                  &  7  & a stream is in wrong state \cr
\+&                  &  8  & capability is invalid    \cr

 
\section{Procedure 27.\quad Inquire  EGTS State}
\heading={REQUEST}
\table
\full{capability}
\endtable
\desc
\enddesc
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{state}
\endtable
\desc
state = 1 indicates that the EG Tape Server is currently in the
{\sl halted} state, state = 2 indicates that it is currently
in the {\sl going} state and state = 3 indicates that it is currently in
the {\sl test} state.
\enddesc

\heading={RESPONSE - failure}
\table
\half{procedure status}
\endtable
\desc

\enddesc
{\sl Procedure status} is a 4 byte field which is non zero and
indicates the cause of the failure.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  8  & capability is invalid    \cr

 
\vfill\eject

\section{Procedure 28.\quad Associate EG Stream}
\heading={REQUEST}
\table
\half{EG stream}
\full{capability}
\half{mode = 2}
\half{valid = true}
\half{list length}
\full{list of client identifiers}
\data{:}
\half{valid=false}
\endtable
\desc
Connects a Eurogam data stream to one or more lists of tape devices (data
duplication). Each list itself is a list of one or more tape devices (data
striping). \lb
Mode = 2 indicates the duplication+striping option implemented in 
version 4 (and later) of the program protocol.
\enddesc
Data received for the Eurogam data stream identified by
{\sl EG stream}  are associated
with all tape streams identified by the following lists of
{\sl client identifiers}.  \lb  
Each list of client identifiers receives a copy of the data for this EG data
stream (data duplication). The data is then written in a "round robin"
manner to each of the tape devices implied by the client identifiers in 
the list (data striping). \lb             
A null request
may be used to cancel any existing association.     \lb
The current state of the EGTS must be halted otherwise 
the request will fail.
\heading={RESPONSE}
\table
\half{procedure status}
\endtable
\desc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  & accepted \cr
\+&    &  2  & unknown client identifier for this client \cr
\+&        &  8  &  capability is invalid      \cr
\+&        &  13 &  EGTS is in wrong state     \cr

 
\vfill\eject

\section{Procedure 29.\quad Inquire EG Stream Association}
\heading={REQUEST}
\table
\half{EG stream}
\full{capability}
\endtable
\desc
Requests a description of the tape devices to which the EG stream is associated.
\enddesc
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{mode = 2}
\half{valid = true}
\half{list length}
\full{list of client identifiers}
\data{:}
\half{valid = false}
\endtable
\desc
A variable number of variable length lists of client identifiers are 
returned. \lb
Only mode = 2 is returned by version 4 of the program protocol.
\enddesc
Each list of client identifiers receives a copy of the data for this EG data
stream (data duplication). The data is then written in a "round robin"
manner to each of the tape devices implied by the client identifiers in 
the list (data striping).

If there is no current stream association for this data stream then a 
null list of lists is returned.
\heading={RESPONSE - failure}
\table
\half{procedure status}
\endtable
\desc

\enddesc
{\sl Procedure status} is a 4 byte field which is non zero and
indicates the cause of the failure.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  8  & capability is invalid \cr
\par 
 
 
\vfill\eject

\section{Procedure 30.\quad Inquire  EGTS Stream State}
\heading={REQUEST}
\table
\half{EG stream}
\full{capability}
\endtable
\desc
\enddesc
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{state}
\half{block count}
\half{byte count}
\half{data rate}
\endtable
\desc
state = 1 indicates that the EG Tape Server is currently in the
{\sl halted} state, state = 2 indicates that it is currently
in the {\sl going} state and state = 3 indicates that it is currently
in the {\sl test} state.  \lb
The number of data blocks received for this EG stream is
returned in {\sl block count} and the number of data 
bytes in {\sl byte count}.
{\sl Data rate} contains the data received in bytes per second 
averaged over the last 10 second period for this EG stream.
\enddesc

\heading={RESPONSE - failure}
\table
\half{procedure status}
\endtable
\desc

\enddesc
{\sl Procedure status} is a 4 byte field which is non zero and
indicates the cause of the failure.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  8  & capability is invalid    \cr

\eject
\section{Procedure 23.\quad Allocate Device}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{device name length}
\data{device name}
\endtable
\desc
Allocates the specified device for exclusive use of the client
to the supplied {\sl client identifier}.
\enddesc
{\sl Stream identifier} is a 4 byte opaque field supplied by
the client to identify this device. It must be different 
from any other {\sl client identifier} currently in use
by  this client for previously allocated devices.    \lb
{\sl Device name} specifies the server resource to be allocated. It
may either be the name of an actual resource or a generic name
given to a group of identical resources. The resources
available are server dependant but a list may be obtained by
use of the Inquire Available Devices procedure.
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{device name length}
\data{device name}
\endtable
\desc

\enddesc
The response  returns the actual device name allocated. This is 
useful when the request supplies a generic name requesting any
one of a group of identical devices.   \lb
The current value of {\sl stream status} for this stream
changes to {\sl dev\_alloc}.         \lb
The current value of {\sl procedure status} for this stream 
changes     to {\sl success} (=0).
\heading={RESPONSE - failure}
\table
\half{procedure status}
\endtable
\desc

\enddesc
{\sl Procedure status} is a 4 byte field which is non zero and
indicates the cause of the failure.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  1  & client identifier already in use for this client \cr
\+&        &  3  &  no free resources    \cr
\+&        &  6  &  requested resource unavailable\cr

\endGroup
\end
