\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
EDOC304\par
\vskip 2.5truein
\hrule height 2pt
\vskip 20pt
\large
EUROBALL DATA ACQUISITION SYSTEM\par
\vskip .5truein
Euroball Tape Server - RPC Program Specification\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 1.0\par
\vskip 5pt
Sept 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{}

\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 Euroball Tape Server (EGTS) RPC program
specification used by the Euroball data acquisition system.

It is an merging of two previous Eurogam documents (EDOC020 which describes
the general Network Tape System (NTS) and EDOC097 which describes the 
extensions of EDOC020 used by the Eurogam Tape Server). Those parts of
the program specification described in EDOC020 which are not used by the
Eurogam and Euroball Tape Servers have been removed for clarity.
 
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 Sept 1990 - first version. Produced by merging EDOC020 Version 3.0
and EDOC097 Version 2.0.

\vskip .5in

{\large Operation }
 
 
Version 1.0 of the document corresponds to version 4 of the 
program protocol. 

 
\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 Procedure Summary}
\parindent=36pt
\item{}0.  Null procedure
\item{}1.  not used     
\item{}2.  Mount volume 
\item{}3.  Open file 
\item{}4.  not used
\item{}5.  not used
\item{}6.  not used
\item{}7.  Inquire device status  
\item{}8.  Close file  
\item{}9.  Dismount volume 
\item{}10. Deallocate device 
\item{}11. not used
\item{}12. Inquire stream status 
\item{}13. Initialise volume 
\item{}14. Identify volume  
\item{}15. undefined 
\item{}16. Inquire available devices 
\item{}17. not used
\item{}18. Move tape 
\item{}19. Position tape changer 
\item{}20. Inquire element status 
\item{}23. Allocate device
\item{}24. Claim EGTS
\item{}25. Free EGTS
\item{}26. Set EGTS state
\item{}27. Inquire EGTS state
\item{}28. Associate EG data stream
\item{}29. Inquire EG data stream association
\item{}30. Inquire EGTS stream state
\parindent=0pt
 
 
\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 State Variables}
 
\parindent=36pt
\item{}dev\_unalloc = 0         
\item{}dev\_alloc   = 1            
\item{}dev\_mounting = 2  
\item{}dev\_mount = 3         
\item{}dev\_opening = 4          
\item{}dev\_open = 5     
\item{}dev\_closing = 6      
\item{}dev\_executing = 7    
\item{}dev\_initialising = 8    
\item{}dev\_identifying = 9    
\item{}dev\_putting = 10
\item{}dev\_moving = 11
\item{}dev\_err = 16  
\parindent=0pt
 
\vskip .3in
 
{\bf Procedure Status}
 
\parindent=36pt
\item{}ntserr\_inuse = 1       
\item{}ntserr\_stale = 2       
\item{}ntserr\_nores = 3       
\item{}ntserr\_conx = 4       
\item{}ntserr\_dm = 5          
\item{}ntserr\_ral = 6           
\item{}ntserr\_state = 7       
\item{}ntserr\_cap = 8      
\item{}ntserr\_cmd = 10       
\item{}ntserr\_inv = 11    
\item{}ntserr\_nolabel = 12
\item{}ntserr\_noc = 13
\parindent=0pt
 
\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 Allocate Device - Not Used by EGTS}

\section{Procedure 2.\quad Mount Volume}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{volume name length}
\data{volume name}
\endtable
\desc
Requests that the specified volume be loaded onto the device 
currently allocated to the client's {\sl client identifier}.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device. \lb
{\sl Volume name} specifies the volume to be loaded onto the
allocated device. \lb
The current {\sl stream state} for the stream must be {\sl dev\_alloc} 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  & accepted    \cr
\+&     &  2  & unknown client identifier for this client \cr
\+&        &  6  &  mount request rejected    \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl  procedure status} = accepted the current value of the {\sl stream
status} for this  stream changes to {\sl dev\_mounting}.  
\par
When the mount operation has been completed successfully (which
could take some time) the {\sl stream state} for the 
stream changes to {\sl dev\_mount}.     \lb
Should the mount operation fail (for example the requested 
volume cannot be found) {\sl stream state} reverts to 
{\sl dev\_alloc} and {\sl procedure status} is set appropriately.
 
See also procedure 14 - Identify volume
 
\vfill\eject

\section{Procedure 3.\quad Open File}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{access mode}
\half{label type}
\half{record length}
\half{block length}
\half{file name length}
\data{file name}
\endtable
\desc
The device specified by {\sl client identifier} is prepared
for data transfer.\lb
In the case of read access the file is located on the medium.\lb
In the case of write access the medium is positioned and file
labels written.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device. 
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& Access mode=&  0  &  update  \cr
\+&             &  1  &  read only  \cr
\+&             &  2  &  write only \cr
\+&             &  8  &  RAW (update)  \cr
\+&             &  9  &  RAW (read only)  \cr
\+&             & 10  &  RAW (write only)  \cr
\smallskip
\+& label type=  &  0  &  undefined \cr
\+&             &  1  &  IBM labels \cr
\+&             &  2  &  ANSI labels \cr
\+&             &  8  &  unlabelled  \cr
\smallskip
\+& record length=  &  $>$0  &  fixed length records \cr
\+&                 &     &  ie F format  \cr
\+&                 &  0  &  variable length records \cr
\+&                 &     &  ie VB format - IBM  \cr
\+&                 &     &     D format - ANSI \cr
\smallskip
\+& block length=  &  0  &  undefined \cr
If record format = F then {\sl block length} must be a multiple of
{\sl record length}.
\smallskip
{\sl File name} specifies the name of the file to be accessed. \lb
{\sl Label type} = 0 may be used if the server system determines this
information from the medium volume label.\lb
{\sl Record length} and {\sl block length} need not be supplied for read access
if the server system determines this information from the
device file labels.  \lb
Access mode = RAW may be used by clients writting data in
undefined formats. In this case the remaining fields may 
be set as undefined. The server system may place restrictions
on the use of this option for reasons of data security. \lb
The current {\sl stream state} for the stream must be {\sl dev\_mount} 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  & accepted    \cr
\+&     &  2  & unknown client identifier for this client \cr
\+&     &  4  & connect error \cr
\+&     &  5  & data management error \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl  procedure status} = accepted the current value of the {\sl stream
status} for this  stream changes to {\sl dev\_openning}.  
\par
When the open operation has been completed successfully (which
could take some time) the {\sl stream state} for the 
stream changes to {\sl dev\_open}.   \lb
Should the open operation fail (for example the requested file
cannot be found) {\sl stream state} reverts to {\sl dev\_mount}
and {\sl procedure status} is set appropriately.

\section{Procedure 4.\quad Read Data - not used by EGTS}

\section{Procedure 5.\quad Write Data - not used by EGTS}

\section{Procedure 6.\quad Special Device Commands - not used by EGTS}

\section{Procedure 7.\quad Inquire Device Status}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\endtable
\desc
Returns information on the state of the device in use
for this client's {\sl client identifier}.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device.     
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{device type length}
\data{device type}
\half{tape length}
\half{tape remaining}
\half{tape i/o errors}
\half{tape i/o error percentage}
\half{information length}
\data{information}
\endtable
\desc
The field {\sl device type} is the generic name assigned to the
device and may be used to interpret the data which follows. \lb
The fields {\sl tape length} and
{\sl tape remaining} are in units which are dependent on 
{\sl device type}. 
The field {\sl tape i/o error percentage} is expressed in units of 0.1\%.
The value -1 indicates that the information cannot
be supplied for this device.    \lb
{\sl Information} is further device specific 
status which may have length = 0 if none is available or can
be obtained.
\enddesc
\heading={}
\table
\half{length = 26}
\data{device sense data}
\half{length = 17}
\data{device mode sense data}
\half{length = 52}
\data{device inquiry data}
\endtable
\desc
Format of {\sl information}  for {\sl device type} EXB-8200.  \lb
{\sl Information length} = 112.  \lb
The format of data in these fields is define in the Interface 
User's Manual for the Exabyte 8200 Tape Subsystem.  \lb
{\sl Tape length} and {\sl tape remaining} are given in units of
blocks of length 1 Kbyte.
\enddesc
\heading={}
\table
\half{length = 29}
\data{device sense data}
\half{length = 17}
\data{device mode sense data}
\half{length = 106}
\data{device inquiry data}
\endtable
\desc
Format of {\sl information}  for {\sl device type} EXB-8500.  \lb
{\sl Information length} = 172.  \lb
The format of data in these fields is define in the
User's Manual for the Exabyte 8500 Tape Subsystem.  \lb
{\sl Tape length} and {\sl tape remaining} are given in units of
blocks of length 1 Kbyte.
\enddesc
\heading={}
\table
\half{length = 13}
\data{machine status}
\half{length = 5}
\data{configuration status}
\half{length = 11}
\data{error history status}
\half{length = 14}
\data{current status}
\endtable
\desc
Format of {\sl information}  for {\sl device type} CIPHER-M990.  \lb
{\sl Information length} = 68.  \lb
The format of data in these fields is defined in the Technical
Manual for the Cipher GCR CacheTape Series M990. \lb
{\sl Tape written} is given in units of feet.
\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=&  2  & unknown client identifier for this client \cr
\+&        &  8  &  capability is invalid      \cr


\section{Procedure 8.\quad Close File}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\endtable
\desc
For files open in write mode causes file trailer labels to be 
written. No further data transfer requests may be issued
until a further {\sl Open file} request has been received 
for this client's {\sl client identifier}.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device.     \lb
The current {\sl stream state} for the stream must be {\sl dev\_open}
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  & accepted   \cr
\+&     &  2  & unknown client identifier for this client \cr
\+&     &  5  & data management error \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl procedure status} = accepted the current value of the
{\sl stream state} for this stream changes to dev\_closing. \lb
When the operation has been completed (which could take some 
time) the {\sl stream state} for the stream changes to
{\sl dev\_mount}. Should the operation fail then {\sl procedure status}
is set appropriately and {\sl stream state} reverts to dev\_open.

\section{Procedure 9.\quad Dismount Volume}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\endtable
\desc
Reverses the action of the mount command.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device.     \lb
The current {\sl stream state} for the stream must be {\sl dev\_mount} otherwise the request will fail.     \lb
Any medium loaded on the device should if possible be unloaded.
\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
\+&     &  2  & unknown client identifier for this client \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl procedure status} = success the current value of the
{\sl stream state} for this stream changes to {\sl dev\_alloc}.

\vfill\eject

\section{Procedure 10.\quad Deallocate Device}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\endtable
\desc
Deallocates the device currently allocated to the client's
{\sl client identifier}
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device.     \lb
The current {\sl stream state} for the stream must be {\sl dev\_alloc} 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
\+&     &  2  & unknown client identifier for this client \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl procedure status} = success the current value of the
{\sl stream state} for this stream becomes undefined. The server
invalidates the {\sl capability} and no further actions are
permitted on the device.

\section{Procedure 11.\quad Reset client - not used by EGTS} 

\section{Procedure 12.\quad Inquire Stream Status}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\endtable
\desc
Returns information for this client's {\sl client identifier}.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device.     
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{last procedure status}
\half{current stream state}
\half{information length}
\data{information}
\half{device name length}
\data{device name}
\half{real device name length}
\data{real device name}
\half{volume name length}
\data{volume name}
\half{file name length}
\data{file name}
\half{access mode}
\half{label type}
\half{record length}
\half{block length}
\half{spare}
\half{data length}
\half{magic number}
\half{magic number (write)}
\half{magic number (read)}
\half{block count}
\half{byte count}
\half{data rate}
\endtable
\desc

\enddesc
This procedure does not change the value of {\sl procedure status}
and is permitted for any {\sl stream state}. \lb
{\sl Information} may contain a text message to explain
further the reason for any error state indicated by {\sl procedure 
status}. {\sl Information length} must be zero if no 
message is available.  \lb
The field {\sl device name} is that specified by the {\sl allocate
device} procedure and the field {\sl real device name} is that
returned by the procedure. \lb
The field {\sl volume name} is that specified by the {\sl mount
volume} procedure. \lb
The fields {\sl file name}, {\sl access mode}, {\sl label type},
{\sl record length} and {\sl block length} are those 
specified by the {\sl open file} procedure. \lb
The field {\sl data length} is the length of the current 
block/record (read) or the length of data currently in the 
block/record buffer (write).  \lb
The field {\sl magic number} is that specified by the 
last {\sl special device commands} procedure.  \lb
The field {\sl magic number (read)} is that specified by the 
last {\sl read data} procedure.  \lb
The field {\sl magic number (write)} is that specified by the 
last {\sl write data} procedure.
\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=&  2  & unknown client identifier for this client \cr
\+&        &  8  &  capability is invalid      \cr


\section{Procedure 13.\quad Initialise Volume}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{volume name length}
\data{volume name}
\half{label type}
\half{density}
\half{current volume name length}
\data{current volume name}
\endtable
\desc
Requests that the volume currently loaded on the device
specified by {\sl client identifier} be initialised.
Standard volume labels of the type specified by {\sl label type}
are written onto  the tape. Note that this operation will cause all data currently
on the tape to be lost.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device. \lb
{\sl Volume name} specifies the name to be used when writting
the volume labels. \lb
{\sl Label type} specifies the format type of the volume labels
to be written.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& label type=  &  1  &  IBM labels \cr
\+&             &  2  &  ANSI labels \cr
{\sl Density} specifies the option  to be selected on the device when
writting the labels. This field  is only used by those devices which 
support more than one data density.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& density   =  &  0  &  device default \cr
\+&             &  1  &  low -1600 bpi or 8200 mode on Exabyte 8500 \cr
\+&             &  2  &  high - 6250 bpi or 8500 mode on Exabyte 8500 \cr
\+&             &  3  &  compressed mode on Exabyte 8500C/8505 \cr
{\sl Current volume name} must be supplied if the tape already
contains a valid volume label. If the tape is currently unlabelled
this field should be supplied as a null length string or the 
name NONE supplied.  \lb
The current {\sl stream state} for the stream must be either
{\sl dev\_alloc} or {\sl dev\_mount} 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  & accepted    \cr
\+&     &  2  & unknown client identifier for this client \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl  procedure status} = accepted the current value of the {\sl stream
status} for this  stream changes to {\sl dev\_initialising}.  
\par
When the initialise operation has been completed successfully (which
could take some time) the {\sl stream state} for the 
stream reverts to dev\_alloc. \lb
Should the initialise operation fail 
 {\sl stream state} reverts to 
{\sl dev\_alloc} and {\sl procedure status} is set appropriately.

\section{Procedure 14.\quad Identify Volume}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\endtable
\desc
Requests that the volume  loaded on the device 
currently allocated to the client's {\sl client identifier}
be examined for a valid standard volume label and    
a Mount Volume operation be automatically performed if 
one is found.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device. \lb
The current {\sl stream state} for the stream must be {\sl dev\_alloc} 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
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr
If {\sl  procedure status} = accepted the current value of the {\sl stream
status} for this  stream changes to {\sl dev\_identifying}.  
\par
When the identify operation has been completed successfully (which
could take some time) the {\sl stream state} for the 
stream changes to {\sl dev\_mount}
and the label type and volume name found can be obtained by using
the Inquire Stream Status procedure.  \lb
Should the identify operation fail (for example the tape is not
actually labelled) {\sl stream state} reverts to 
{\sl dev\_alloc} and {\sl procedure status} is set appropriately.


\section{Procedure 16.\quad Inquire Available Devices}
\heading={REQUEST}
\desc
Requests a list of the device names available which may be 
specified in the {\sl allocate device} procedure.
\enddesc
There are no procedure specific parameters.
\heading={RESPONSE}
\table
\half{success $= 0$}
\half{valid = true}
\half{status}
\half{real device name length}
\full{real device name}
\half{device name length}
\full{device name}
\data{:}
\half{value = false}
\endtable
\desc
The available devices are returned in a variable length list.
For each device its real device name and generic 
device name are returned with the current status of the device.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Status=&  0  & free \cr
\+&        &  1  &  allocated\cr
\+&        &  2  &  currently not usable       \cr
\par 
\enddesc

 
\section{Procedure 17.\quad Reset Stream - not used by EGTS}
 
\section{Procedure 18.\quad Move Tape}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{magic number}
\half{source location}
\half{destination location}
\endtable
\desc
Requests the device to move a tape from one internal location to another.
This procedure is available for multi-tape handling systems.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device. \lb
{\sl Magic number} is an opaque field supplied by the client to identify this request. 
It is used by the server to identify retried 
requests for which the client may have missed the response.
The client must use different {\sl magic numbers} for 
successive requests. \lb
{\sl Source location} and {\sl destination location} specify the source and destination locations of the tape. The values are device specific. \lb
Values of {\sl locations} for Exabyte EXB-10i Cartridge Handling Subsystem.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& Location = &  0  &  Cartridge Tape Subsystem (CTS), the tape drive\cr
\+&            &  1-10  &  Tape storage slots \cr
\+&            &  11  &  Cartridge Handling Mechanism (CHM) \cr
The current {\sl stream state} for the stream must be {\sl dev\_alloc} 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  & accepted    \cr
\+&     &  2  & unknown client identifier for this client \cr
\+&     &  5  & data management error \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr

If {\sl  procedure status} = accepted the current value of the {\sl stream
status} for this  stream changes to {\sl dev\_moving}.  
\par
When the move operation has been completed (which
 could take some time) the {\sl stream state} reverts to {\sl dev\_alloc}.

\vfill\eject

\section{Procedure 19.\quad Position Tape Changer}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{destination}
\endtable
\desc
Requests the device to move the changer mechanism to a specified internal
location.
This procedure is available for multi-tape handling systems.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device. \lb
{\sl Destination} specifies the location that the mechanism is to be moved to. The value is device specific. \lb
Values of {\sl destination} for Exabyte EXB-10i Cartridge Handling Subsystem.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& Location = &  0  &  Cartridge Tape Subsystem (CTS), the tape drive\cr
\+&            &  1-10  &  Tape storage slots \cr
\+&            &  11  &  Cartridge Handling Mechanism (CHM) \cr
\+&            &  -1  &  Cartridge Handling Subsystem Occupancy Check \cr
This procedure can be used to pre-position the mechanism before a subsequent Move Tape request. If the location is specified as the CHM itself,
the mechanism will be parked to allow access to
the cartridge storage slots and the CTS.

Location = -1. Used to enable the Handling Subsystem to update its information
on storage occupancy if it wishes. The element status information can be
retrieved by procedure 20. The procedure to test all locations in the
stacker for occupancy takes about 1 minute.
\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  & accepted    \cr
\+&     &  2  & unknown client identifier for this client \cr
\+&     &  5  & data management error \cr
\+&        &  7  &  stream is in wrong state\cr
\+&        &  8  &  capability is invalid      \cr

If {\sl  procedure status} = accepted the current value of the {\sl stream
status} for this  stream changes to {\sl dev\_moving}.  
\par
When the move operation has been completed (which
 could take some time) the {\sl stream state} reverts to {\sl dev\_alloc}.

\vfill\eject

\section{Procedure 20.\quad Inquire Element Status}
\heading={REQUEST}
\table
\half{client identifier}
\full{capability}
\half{location}
\endtable
\desc
Requests information about an internal element of the device allocated to the client's {\sl client identifier}.
This procedure is available for multi-tape handling systems.
\enddesc
{\sl Client identifier} identifies the device for the client 
and {\sl capability} is the corresponding access key provided 
by the server for this device.  \lb   
{\sl Location} specifies the location for which the status is requested. The value is device specific. \lb
Value of {\sl location} for Exabyte EXB-10i Cartridge Handling Subsystem.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& Location = &  0  &  Cartridge Tape Subsystem (CTS), the tape drive\cr
\+&            &  1-10  &  Tape storage slots \cr
\+&            &  11  &  Cartridge Handling Mechanism (CHM) \cr
\+&            &  -1  &  Cartridge Handling Subsystem (see procedure 19) \cr
This procedure is permitted for any {\sl stream state}.

The actual hardware it not accessed by this procedure in order to ensure
consistent response time for this procedure. (See procedure 19).
\heading={RESPONSE - success}
\table
\half{success $= 0$}
\half{element state}
\half{occupancy}
\half{source}
\half{information length}
\full{information}
\endtable
\desc
The values are device specific.
\enddesc
Values for Exabyte EXB-10i Cartridge Handling Subsystem.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& Element state=&  0  & normal \cr
\+&        &  1  &  cartridge holder missing\cr
\+&        &  2  &  status unknown       \cr
\+&        &  3  &  CTS door open       \cr
\smallskip
\+& Occupancy=&  0  & empty \cr
\+&        &  1  &  full\cr
{\sl Source} identifies the last location from which the cartridge was moved.
\smallskip
\settabs\+
\qquad&record length:\quad&9999\quad&variable-length-records \cr
\+& Source= &  0  &  Cartridge Tape Subsystem (CTS), the tape drive\cr
\+&            &  1-10  &  Tape storage slots \cr
\+&            &  11  &  Cartridge Handling Mechanism (CHM) \cr
\enddesc
If on request location = -1 then the status of the Cartridge Subsystem hardware
is returned. The status {\sl busy} is returned if the Handling Subsystem is
currently updating its information on storage occupancy as a result of a 
previous request to procedure 19 with location = -1.
\smallskip
\settabs\+
\qquad&xxxxxxxxxxxxxxxxxx\quad&xxxx\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\cr
\+& Element state = &  0  &  idle\cr
\+&                 &  10 &  busy\cr
\enddesc
{\sl Information} is a text string which may contain further information 
about the state of the Cartridge Handling Subsystem.
\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=&  2  & unknown client identifier for this client \cr
\+&        &  8  &  capability is invalid      \cr

 


\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

\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

\vfill\eject
 
\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

\endGroup
\end
