\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
EDOC078\par
\vskip .5truein
\large
EUROGAM PROJECT\par
\vskip 1.5truein
\hrule height 2pt
\vskip 20pt
\large
NSF DATA ACQUISITION SYSTEM\par
\vskip .5truein
Spectrum Access Server Protocol\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 1.2\par
\vskip 5pt
Aug 1992\par
\vfill
\medium
NSF Software Systems Group\par
\vskip 5pt
UK Science and Engineering 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 }
\count0=1
\vskip .5in

This document describes the Spectrum Access Server (SAS) protocol
specification used to provide access to the distributed
spectrum servers which form part of the NSF 
data acquisition system.
 
The protocol is used to implement the Spectrum Access procedures
defines in {\it EDOC062} together with the spectrum format
defined in {\it EDOC061}.

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 .75in
{\large Document History}
\vskip .5in
 
Version 1.0 June 1991 - Initial version
 
Version 1.1 Sept 1991 

Version 1.2 Aug 1992 - Allow authorisation with no password if client machine
is listed in user's .rhosts.sas, /etc/hosts.sas or /etc/hosts.equiv.
\vskip .75in
{\large Use }
\vskip .5in
 
Throughout this document {\it capability} is an 8 byte (64 bit) opaque
field generated by the server and used by the client as 
an access token. 
 
Throughout this document the spectrum being accessed is
identified by the string variable {\it pathname}. For on-line
spectrum servers this is the name of the spectrum within the
server. For off-line spectrum servers 
(ie disc-based spectra) this is either an absolute pathname identifying 
a disc file known to the spectrum server or is a pathname which is
relative to the 'home' directory of the authenicated user
issuing the request.
 
\par

\vfill\eject


{\large Program Specification}          
\vskip .5in

{\bf RPC Information}
\parindent=36pt
\item{}The SAS service uses only the Null authentication except for procedure 1 which can use Unix authentication protocol requests. 
\item{}SAS is supported on the UDP/IP transport only 
\item{}SAS is RPC Program 28000230    
\item{}This is Version 1 of the protocol
\item{}SAS uses UDP port number 10230 
\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    
\+& & authentication\_failure $=$ 1     & \cr    
\+& & already\_in\_use         $=$ 2     & \cr    
\+& & capability\_invalid     $=$ 3     & \cr    
\+& & pathname\_invalid       $=$ 4     & \cr    
\+& & parameter\_invalid       $=$ 5     & \cr    
\+& & not\_a\_spectrum         $=$ 6     & \cr    
\+& & not\_a\_directory        $=$ 7     & \cr    
\+& & data\_access\_error      $=$ 8     & \cr    
\+&  $\}$ stat;        & & \cr

\smallskip
\+&typedef~~ string~~ user$<$32$>$;  & & \cr   
\+&typedef~~ string~~ password$<$32$>$;  & & \cr   
\+&typedef~~ string~~ pathname$<$255$>$;  & & \cr   

\smallskip
\+&typedef~~ string~~ timedate[20];  & & \cr   
 
\smallskip
\+&typedef~~ unsigned~~ map;  & & \cr   
 
\smallskip
\+&typedef~~ opaque~~ capability[8];  & & \cr 
 
\smallskip
\+&typedef~~   signed~~ base[8];  & & \cr 
\+&typedef~~ unsigned~~ range[8];  & & \cr 
\+&typedef~~ unsigned~~ size[8];  & & \cr 
 
\smallskip
\+&typedef~~ unsigned~~~dimension; & & \cr 
\+&typedef~~ unsigned~~ arraytype; & & \cr 
\+&typedef~~ unsigned~~ arraylayout; & & \cr 
\+&typedef~~ opaque~~~~ countvalue;  & & \cr 
\+&typedef~~ unsigned~~ stringtype;  & & \cr 
\+&typedef~~ unsigned~~ stringid;    & & \cr 

Actually {\sl countvalue} is not opaque, the data type is
determined by {\sl type}. 
 
\vfill\eject

\smallskip
\+&typedef~~ struct~~ $\{$ & & \cr
\+&&arraylayout~~layout;    & \cr
\+&&arraytype~~type;& \cr
\+&$\}$ attrib;       & & \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 Authorise}

 Requests authorisation for the client to access the 
spectrum server. For off-line spectrum servers (ie for 
disc-based spectra) a User Identifier must be supplied. 
If the procedure is called with Null authentication an
appropriate password must also be supplied to authenicate the user.
If the procedure is called with Unix authentication
 and the request comes from a machine listed in one of
the files .rhosts.sas in the user's home directory, /etc/hosts.equiv or /etc/hosts.sas, all on the server machine,
a password need not be supplied.
The User Identifier is then used to define a 'home' disc 
directory. Pseudo users may be used for access to 
shared spectrum databases. For on-line 
spectrum servers the User Identifier and password may be
null length strings.
\heading={REQUEST}
\table
\half{user name length}
\full{user name}
\half{password length}
\full{password}
\half{mode}
\endtable
\desc
{\sl User name} and {\sl password} are strings which 
provide user authenication. {\sl Mode} indicates 
whether read only access (mode=0) or read/write access
(mode=1) is required.
\enddesc
\heading={RESPONSE - success}
\table
\half{success = 0}
\full{capability}
\endtable
\desc
If the authorisation request is successful {\sl capability}
is returned as an access token to be used in all
subsequent procedure requests.
\enddesc
  
\heading={RESPONSE - failure}
\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=&  1  &  user authentication error \cr
\+&     &  2  &   server already in use \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  Authorise(id,pass,mode)   ~~~returns (reply) & \cr
\+&        &  user~~     id ;   &   \cr
\+&        &  password~~ pass ;   &   \cr
\+&        &  unsigned~~ mode ;   &   \cr
\+&        &                          &   \cr
\+&        &  union switch (stat status)~~  $\{$             &  \cr
\+&        &  ~~~~OK:                                      &  \cr
\+&        &  ~~~~capability~~cap;                         &  \cr
\+&        &  ~~~~default:                                 &  \cr
\+&        &  ~~~~struct~~  $\{\}$                             &  \cr
\+&        &  $\}$~~reply;     &  \cr


\goodbreak
\section{Procedure 2.\quad Create Spectrum}
\nobreak
\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{dimension}
\half{dimension 1 base}
\half{dimension 2 base}
\full{:}
\half{dimension 8 base}
\half{dimension 1 range}
\half{dimension 2 range}
\full{:}
\half{dimension 8 range}
\half{data array 1 layout}
\half{data array 1 type} 
\half{data array 2 layout}
\half{data array 2 type} 
\endtable
\desc
If the access {\sl capability} is valid creates a spectrum in
the server with name given by {\sl pathname}.       \lb
The remaining fields are as defined in the document 
{\sl EDOC061}. Undefined fields should be set to 
-1 or all one bits.
\enddesc
The array layout and array type parameters may be defined here
or left undefined (set to -1  or all one bits) and defined 
latter using the Change Array Options procedure.  If {\sl data array 1 layout} and
{\sl data array 1 type} are defined here for an on-line spectrum
server then space will be allocated for the data array at this 
point. In the case of disc based spectra space for the data 
arrays will not be allocated until the first Write Spectrum 
procedure.
  
\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  &   success           \cr
\+&     &  3  &   invalid capability  \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  5  &   invalid parameter value \cr
\+&     &  7  &   pathname not a directory\cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure & CreateSpectrum(cap,path,dim,bse,rng,layout1,type1,layout2,type2)&\cr
\+&        & ~~~~~~~~~~ returns (status) &\cr
\+&        &  capability~~ cap;   &   \cr
\+&        &  pathname~~  path;   &   \cr
\+&        &  dimension~~~dim;   &   \cr
\+&        &  base~~      bse; &   \cr
\+&        &  range~~     rng;   &   \cr
\+&        &  arraylayout~~  layout1;  &   \cr
\+&        &  arraytype~~~type1;  &   \cr
\+&        &  arraylayout~~  layout2;  &   \cr
\+&        &  arraytype~~~type2;  &   \cr
\+&        &  stat~~      status;   &   \cr



\section{Procedure 3.\quad Delete Spectrum}

\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\endtable
\desc
If the access {\sl capability} is valid deletes the spectrum in
the server with name given by  {\sl pathname}.
\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  &     success         \cr
\+&     &  3  &   invalid capability  \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  6  &   pathname not a spectrum  \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  DeleteSpectrum(cap,path)   ~~~returns (status)&\cr
\+&        &  capability~~ cap;   &   \cr
\+&        &  pathname~~  path;   &   \cr
\+&        &  stat~~      status;   &   \cr



\section{Procedure 4.\quad Look Up Spectrum}

\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\endtable
\desc
If the access {\sl capability} is valid and the spectrum defined
by  {\sl pathname}  exists attribute information
extracted from the spectrum header is returned.
\enddesc
\heading={RESPONSE - success}
\table
\half{success = 0}
\half{dimension}
\full{creation time and date}
\full{modification time and date}
\half{dimension 1 base}
\full{:}
\half{dimension 8 base}
\half{dimension 1 range}
\full{:}
\half{dimension 8 range}
\half{information string map}
\half{annotation string map}
\half{calibration string map}
\half{efficiency string map}
\half{data array 1 layout}
\half{data array 1 type}
\half{data array 2 layout}
\half{data array 2 type}
\half{data array 1 base address}
\endtable
\desc
The fields returned are as defined in the document {\sl EDOC061}.
Undefined fields are returned set to -1 or all one bits.
\lb
The field {\sl data array 1 base address} will only be defined for
on-line spectra.
\enddesc
The string maps provide a convenient indication of the
existance or not of the various data strings. If string n 
exists then bit n (with the most significant bit being 0 and the least being 31)
is set to 1 otherwise it is set to 0. For example if
information strings 1,2 and 3 are defined then the 
information string map will have the value @70000000.
This avoids the need for a {\sl read string} procedure 
to be used for non-existant strings.
  
\heading={RESPONSE - failure}
\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=&  3  &  invalid capability \cr
\+&     &  4  &  invalid pathname     \cr
\+&     &  6  &   pathname not a spectrum  \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  LookUpSpectrum(cap,path)     ~~~returns (reply)&\cr
\+&        &  capability~~  cap ;   &   \cr
\+&        &  pathname~~ path ;   &   \cr
\+&        &                          &   \cr
\+&        &  union switch (stat status)~~  $\{$             &  \cr
\+&        &  ~~~~OK:                                      &  \cr
\+&        &  ~~~~dimension~~~dim;                     &  \cr
\+&        &  ~~~~timedate~~creation;                      &  \cr
\+&        &  ~~~~timedate~~modification;                  &  \cr
\+&        &  ~~~~base~~bse;                &  \cr
\+&        &  ~~~~range~~rng;                &  \cr
\+&        &  ~~~~map~~information;        &  \cr
\+&        &  ~~~~map~~annotation;         &  \cr
\+&        &  ~~~~map~~calibration;        &  \cr
\+&        &  ~~~~map~~efficiency;         &  \cr
\+&        &  ~~~~attrib~~array1;         &  \cr
\+&        &  ~~~~attrib~~array2;         &  \cr
\+&        &  ~~~~unsigned~~address;      &  \cr
\+&        &  ~~~~default:                                 &  \cr
\+&        &  ~~~~struct~~  $\{\}$                             &  \cr
\+&        &  $\}$~~reply;     &  \cr
 
\vfill\eject
 

\section{Procedure 5.\quad Read String}

\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{string type}
\half{string number}
\endtable
\desc
If the access {\sl capability} is valid and the spectrum 
defined by  {\sl pathname} exists then the string
of type {\sl string type} identified by {\sl string number}
is returned.
\enddesc
\smallskip
\settabs\+
\qquad&xxxxxxxxxxxxxxxxx  \quad&xxxx\quad&xxxxxxxxxxxxxx\cr
\+&string type~~ =& 0  & information   \cr   
\+&& 1  & annotation   \cr   
\+&& 2  & calibration   \cr   
\+&& 3  & efficiency    \cr   
 
{\sl String number} is in the range 1 to 16 for information 
strings and 1 to the spectrum dimension for others.
\heading={RESPONSE - success}
\table
\half{success = 0}
\half{string length}
\full{string}
\endtable
\desc
The requested string is returned.
If the requested string is not defined (but the {\sl type} and
{\sl number} are within valid range) then a null length 
string is returned.
\enddesc
  
\heading={RESPONSE - failure}
\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=&  3  &  invalid capability \cr
\+&     &  4  &  invalid pathname     \cr
\+&     &  5  &  invalid parameter value  \cr
\+&     &  6  &   pathname not a spectrum  \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  ReadString(cap,path,stype,snumber)   ~~~returns (reply)&\cr
\+&        &  capability~~cap ;   &   \cr
\+&        &  pathname~~ path ;   &   \cr
\+&        &  stringtype~~ stype ;   &   \cr
\+&        &  stringid~~ snumber ;   &   \cr
\+&        &                          &   \cr
\+&        &  union switch (stat status)~~  $\{$             &  \cr
\+&        &  ~~~~OK:                                      &  \cr
\+&        &  ~~~~string~~ data $<>$                     &  \cr
\+&        &  ~~~~default:                                 &  \cr
\+&        &  ~~~~struct~~  $\{\}$                             &  \cr
\+&        &  $\}$~~reply;     &  \cr
\vfill\eject



\section{Procedure 6.\quad Write String}

\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{string type}
\half{string number}
\half{string length}
\full{string}
\endtable
\desc
If the access {\sl capability} is valid and the 
spectrum defined by  {\sl pathname} exists
then the string of type {\sl string type} identified
by {\sl string number} is defined with the contents 
of the string parameter {\sl string}.
\enddesc
Any existing string is overwritten and an existing 
string may be undefined by use of a {\sl write string}
procedure request with a null length string.
\par
{\sl String type} and {\sl string number} are as defined for
the {\sl read string } procedure.
  
\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  &   success           \cr
\+&     &  3  &   invalid capability  \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  5  &   invalid parameter value \cr
\+&     &  6  &   pathname not a spectrum  \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  WriteString(cap,path,stype,snumber,data)  ~~~returns (status)&\cr
\+&        &  capability~~cap ;   &   \cr
\+&        &  pathname~~ path ;   &   \cr
\+&        &  stringtype~~ stype ;   &   \cr
\+&        &  stringid~~ snumber ;   &   \cr
\+&        &  string~~ data $<>$;                    &  \cr
\+&        &  stat~~   status ;                        &  \cr
\vfill\eject



\section{Procedure 8.\quad Read Names}

\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{cookie}
\half{count}
\endtable
\desc
If the access {\sl capability} is valid those names 
identified to the server by {\sl pathname} are returned
with a total size of up to {\sl count} bytes.
\enddesc
For on-line spectrum servers which have only a single
level name structure {\sl pathname} should be a null
length string and all names known to the server will be
returned. For off-line spectrum servers (ie disc-based
spectra) {\sl pathname} must define a directory file and
the names of the spectrum files and directory files 
within that directory will be returned.
All other files will be ignored.
\heading={RESPONSE - success}
\table
\half{success = 0}
\half{valid=true}
\half{ name length}
\full{ name}
\half{entry type}
\half{cookie}
\full{:}
\half{valid=false}
\half{eod}
\endtable
\desc
Each entry contains the name of the spectrum or file, 
the type of file and a cookie which is an opaque 
pointer to the next entry.  The cookie can be used 
in the next {\sl read name} call to get more entries
starting at a given point. The special cookie zero
(all bits zero) can be used to get the entries 
starting at the beginning. {\sl Eod} has a value of TRUE 
if there are no more entries and FALSE if there are more.
{\sl Valid} is used to mark the end of the entries.
\enddesc
\smallskip
\settabs\+
\qquad&xxxxxxxxxxxxxxxxx  \quad&xxxx\quad&xxxxxxxxxxxxxx\cr
\+&entry  type~~ =& 1  & spectrum      \cr   
\+&& 2  & directory file  \cr
\heading={RESPONSE - failure}
\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=&  3  &  invalid capability \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  5  &   invalid parameter value \cr
\+&     &  7  &   pathname not a directory\cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  ReadNames (cap,path,k,n)     ~~~returns (reply)&\cr
\+&        &  capability~~ cap;   &   \cr
\+&        &  pathname~~ path;   &   \cr
\+&        &  cookie~~     k;   &   \cr
\+&        &  unsigned~~   n;   &   \cr
\+&        &                          &   \cr
\+&        &  union switch (stat status)~~  $\{$             &  \cr
\+&        &  ~~~~OK:                                      &  \cr
\+& &~~~~typedef~~ union switch (boolean valid)~~ $\{$   & \cr
\+&&~~~~~~~TRUE:                &  \cr
\+&&~~~~~~~struct $\{$           &  \cr
\+&&~~~~~~~~~~string~~ name $<$255$>$;     &  \cr
\+&&~~~~~~~~~~unsigned~~entrytype;&  \cr
\+&&~~~~~~~~~~cookie~~ kk;        &  \cr
\+&&~~~~~~~~~~entry~~ nextentry;    &  \cr
\+&&~~~~~~~$\}$                &  \cr
\+&&~~~~~~~FALSE:             &  \cr
\+&&~~~~~~~struct $\{$$\}$    &  \cr
\+&&~~~~$\}$ entry;          & \cr
\+&        &  ~~~~boolean~~eod;                            &  \cr
\+&        &  ~~~~default:                                 &  \cr
\+&        &  ~~~~struct~~  $\{\}$                             &  \cr
\+&        &  $\}$~~reply;     &  \cr
\vfill\eject


\section{Procedure 9.\quad Read Spectrum}
\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{array number}
\half{offset}
\half{count}  
\half{base1}
\half{base2}
\full{:}
\half{base8}
\half{range1}
\half{range2}
\full{:}
\half{range8}
\half{size1}
\half{size2}
\full{:}
\half{size8}
\half{arraytype}
\endtable
\desc
If the access {\sl capability} is valid and the spectrum 
defined by {\sl pathname} exists then returns 
{\sl count} items of data from the spectrum. \lb
The fields are as defined in the document {\sl EDOC061}. 
Undefined fields should be set to -1 or all one bits.\lb
The elements of the arrays {\sl base},  {\sl range}, and
{\sl size} defined must be consistent with the dimension 
of the spectrum. 
\lb
If {\sl size} are undefined then it is assumed that 
no scaling of the data is required and the spectrum is
returned as it would be if {\sl size} were equal to {\sl range}.
\lb
{\sl Array number} = 1 to access the spectrum and
= 2 to access the error spectrum.
\enddesc
The arrays {\sl base} and {\sl range} define a region 
of counts within the spectrum to be returned and the 
counts may then be considered to form a sequence of
data items of size given by the type of 
the spectrum array. 
Counts are returned starting at 
{\sl offset} data items into the defined region.
The first data item is at {\sl offset} zero.
 
The data returned is scaled such that the region
defined by {\sl base} and {\sl range} is returned 
in an array defined by {\sl size} and {\sl arraytype}.
\heading={RESPONSE - success}
\table
\half{success = 0}
\half{flag}
\half{data length}
\full{data}
\endtable
\desc
The data is returned in the array {\sl data}.
{\sl Flag} will normally be set to zero but will be set to
-1 (all one bits) if truncation/overflow occurred while
scaling the data in order to return it within the array 
requested and/or in the type requested.
\enddesc  
Requests that a region of the spectrum array be returned
with the option that the size of the array elements
and the format of each data item may be different from the
source spectrum. Normally this will be such that the 
amount of data to be returned will be  less than the
original data.

\heading={RESPONSE - failure}
\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=&  3  & invalid capability  \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  5  &   invalid parameter value \cr
\+&     &  6  &   pathname not a spectrum  \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  ReadSpectrum(cap,path,number,offset,count,bse,rng,s,type)      ~~~returns (reply)&\cr
\+&        &  capability~~cap ;   &   \cr
\+&        &  pathname~~ path ;   &   \cr
\+&        &  unsigned~~~~number; &   \cr
\+&        &  unsigned~~~~offset; &   \cr
\+&        &  unsigned~~~~count;  &   \cr
\+&        &  base~~ bse         ;   &   \cr
\+&        &  range~~ rng         ;   &   \cr
\+&        &  size~~ s           ;   &   \cr
\+&        &  arraytype~~~type    ;   &   \cr
\+&        &                          &   \cr
\+&        &  union switch (stat status)~~  $\{$             &  \cr
\+&        &  ~~~~OK:                                      &  \cr
\+&        &  ~~~~unsigned~~~flag;   &   \cr
\+&        &  ~~~~string~~ data $<>$;                    &  \cr
\+&        &  ~~~~default:                                 &  \cr
\+&        &  ~~~~struct~~  $\{\}$                             &  \cr
\+&        &  $\}$~~reply;     &  \cr
\vfill\eject




\section{Procedure 10.\quad Write Spectrum}
\nobreak
\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{array number}
\half{offset}
\half{count}
\half{base1}
\half{base2}
\full{:}
\half{base8}
\half{range1}
\half{range2}
\full{:}
\half{range8}
\half{arraytype}
\half{data length}
\full{data}
\endtable
\desc
If the access {\sl capability} is valid and the spectrum
defined by {\sl pathname} exists then the supplied 
data is written to the spectrum. \lb
The fields are as defined in the document {\sl EDOC061}.
Undefined fields should be set to -1 or all one bits. \lb
The elements of the arrays {\sl base} and {\sl range} defined
must be consistent with the dimension of the spectrum.
\lb
{\sl Array number} = 1 to access the spectrum and
= 2 to access the error spectrum.
\lb
The data to be written is supplied in the array {\sl data}
and {\sl arraytype} defines the format of each data item in
this array.
\enddesc
The arrays {\sl base} and {\sl range} define a region 
of counts within the spectrum to be written  and the 
counts may then be considered to form a sequence of
data items of size determined by {\sl arraytype}.
{\sl count} counts are written  starting at 
{\sl offset} data items into the defined region.
The first data item in a region is at {\sl offset} zero.
Type conversion takes place if {\sl arraytype} differs
from the type of the spectrum array being written.
 
Requests that a region of the spectrum array be written 
with the option that the format of each data item supplied may be
different from that of the target spectrum.

\heading={RESPONSE}
\table
\half{procedure status}
\half{flag}
\endtable
\desc
{\sl Procedure status} is a 4 byte field which 
indicates the result of the request.
\enddesc
If {\sl procedure status}  $=$ 0 then {\sl flag} is also returned which 
will normally be set to zero but will be set to
-1 (all one bits) if truncation/overflow occurred while
converting the data between the type supplied and the type defined
for the data array.
\smallskip
\settabs\+
\qquad&procedure status:\quad&9999\quad&xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \cr
\+& Procedure status=&  0  &   success           \cr
\+&     &  3  &   invalid capability  \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  5  &   invalid parameter value \cr
\+&     &  6  &   pathname not a spectrum  \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  WriteSpectrum(cap,path,number,offset,count,bse,rng,type,data)      ~~~returns (reply)&\cr
\+&        &  capability~~cap ;   &   \cr
\+&        &  pathname~~ path ;   &   \cr
\+&        &  unsigned~~~~number; &   \cr
\+&        &  unsigned~~~~offset; &   \cr
\+&        &  unsigned~~~~count; &   \cr
\+&        &  base~~ bse;  &   \cr
\+&        &  range~~ rng;  &   \cr
\+&        &  arraytype~~~type    ;   &   \cr
\+&        &  string~~ data $<>$;                    &  \cr
\+&        &                          &   \cr
\+&        &  union switch (stat status)~~  $\{$             &  \cr
\+&        &  ~~~~OK:                                      &  \cr
\+&        &  ~~~~unsigned~~~flag;                         &  \cr
\+&        &  ~~~~default:                                 &  \cr
\+&        &  ~~~~struct~~  $\{\}$                             &  \cr
\+&        &  $\}$~~reply;     &  \cr
 
\vfill\eject



\section{Procedure 11.\quad Change Array Options}  

\heading={REQUEST}
\table
\full{capability}
\half{pathname length}
\full{pathname}
\half{array number}
\half{array layout}
\half{array type} 
\endtable
\desc
If the access {\sl capability} is valid and the spectrum defined
by {\sl pathname} exists 
then the array layout and array type for the 
data array defined by {\sl array number} may be set. 
\enddesc
If a data array already exists then it will be destroyed by this 
operation. 
By setting the array layout and array type to undefined (-1 or
all one bits) any existing data array may be just destroyed.

 If {\sl array layout} and
{\sl array type} are defined here for an on-line spectrum
server then space will be allocated for the data array at this 
point. In the case of disc based spectra space for the data 
arrays will not be allocated until the first Write Spectrum 
procedure.
\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  &   success           \cr
\+&     &  3  &   invalid capability  \cr
\+&     &  4  &   invalid pathname    \cr
\+&     &  5  &   invalid parameter value \cr
\+&     &  6  &   pathname not a spectrum \cr
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  ChangeArrayOptions(cap,path,number,layout,type) returns (status) &\cr
\+&        &  capability~~ cap;   &   \cr
\+&        &  pathname~~  path;   &   \cr
\+&        &  unsigned~~   number;  &   \cr
\+&        &  arraylayout~~  layout;  &   \cr
\+&        &  arraytype~~~type;  &   \cr
\+&        &  stat~~      status;   &   \cr
\vfill\eject



\section{Procedure 12.\quad UnAuthorise}

\heading={REQUEST}
\table
\full{capability}
\endtable
\desc
Reverse the action of a previous Authorise procedure call. The 
capability will no longer be accepted.
\enddesc
  
\heading={RESPONSE}
\table
\half{success=0}
\endtable
\desc

\enddesc
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  UnAuthorise(cap) returns (status) &\cr
\+&        &  capability~~ cap;   &   \cr
\+&        &  stat~~~~~~~~ status; &   \cr



\section{Procedure 13.\quad Generate Error Report}

\heading={REQUEST}
\table
\full{capability}
\endtable
\desc
An explanation of the    
last error condition associated with this capability    is returned as a 
text string.
\enddesc
  
\heading={RESPONSE}
\table
\half{success=0}
\half{text length}
\full{text}
\endtable
\desc

\enddesc
XDR Specification
\settabs\+
\qquad&procedure  \quad&initialiseregisterxxxxxxxxxxxxxxxxx\quad&returns(reply)\cr
\+& procedure &  GenerateErrorReport(cap) returns (status,text) &\cr
\+&        &  capability~~ cap;   &   \cr
\+&        &  stat~~~~~~~~ status; &   \cr
\+&        &  string~~~~~~ text;   &   \cr
\endGroup
\end
