\documentstyle[12pt,a4]{article}
\begin{document}

\begin{titlepage}
{

\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
\hrule height 0pt
\parindent=0pt
%\parskip=0pt
\hskip 3.9truein
\large
EDOC062\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\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 1.1\par
\vskip 5pt
Sept 1991\par
\vfill
\medium
NSF Software Systems Group\par
\vskip 5pt
UK Science and Engineering Research Council\par
\vskip 5pt
Daresbury Laboratory\par
\vskip .5truein

}
\end{titlepage}

\section{Introduction}
 
The document {\it EDOC061} defines a common format for spectra
to be used for both on-line and off-line use. This document
describes a set of procedures which may be used to access
these spectra. Analysis programs using these procedures 
can access the spectrum data in a consistent way which is
independant of the location of the spectra. The procedures
hide all detail of the format of storage from the analysis 
programs which have no requirement to know, for example, 
the format of the spectrum header.
 
 Since in general the analysis programs using these
procedures will be executing in a workstation which is
remote from the actual location of the spectra data
and connected via a local area network (ethernet) features
are provided in the access procedures intended to allow
the volume of data needed to be read across the network 
to be kept to a minimum. The interface procedures will use
the RPC mechanism to access the remote spectrum server. 
The Spectrum Access Program Protocol is described in the
document {\it EDOC078}.
 
 The spectrum format allows for multi dimensional 
data arrays. However most spectra are in practice
of dimension one or two and many existing analysis 
programs have been written for fixed dimensional data.
Hence interface procedures are provided both for the
general case of n dimensional spectra and for the
specific cases of 1 and 2 dimensional spectra.
 
\section{Document History}
 
Version 1.0  July 1991 -  First version of this document in the document server.
\newline
Version 1.1  Sept 1991 - Corresponding to Spectrum Format
V2.1 and Access Protocol V1.1.
 
\section{Server Location}
 
 The spectrum to be accessed is defined throughout this
document by a character string  {\bf pathname} which 
identifies both the server and the spectrum within 
that server.
On-line servers have only a one level name structure and hence 
{\bf pathname} always refers to either the server 
(authorisation, create and read names) or to a spectrum. For
off-line servers {\bf pathname} refers to the server 
(authorisation), a disc directory (create and read names) or
a disc file which contains a spectrum.
 
 The general format of {\bf pathname} is
{\sf /server\_name/local\_name} where {\sf  server\_name} is either the 
name of an on-line spectrum server (e.g. {\bf hist} or {\bf sort})
or of an off-line server for disc based spectra 
(e.g. {\bf disc} which is the default disc spectrum server
or {\bf nnsa} which is a specific disc spectrum server)
and {\sf local\_name} identifies the spectrum within the server
and has a format which is server dependant.
 
 For example: A spectrum in the on-line histogrammer 
may have the
{\bf pathname} {\sf /hist/ge26} and one in the on-line 
sorter may have the {\bf pathname} {\sf /sort/adc20\_gate2}.
 
 
\section{Procedure Specifications}
 
 In all procedures which have a parameter {\bf name} then if
the character string {\bf name} starts with a leading '/'
character it is an absolute name and the character string
{\bf pathname} is just the contents of the character 
string {\bf name}. In all other cases {\bf name} is
relative to the path defined by the procedure 
EGsetSpectrumpath and the character string {\bf pathname} 
is formed by concatenating the character string {\bf path}
and the character string {\bf name}.

 Throughout the procedure specifications parameters in 
normal type (eg.  call) are supplied to the procedure
and parameters in bold type (eg. {\bf reply}) are 
returned by the procedure.
 
 Throughout the procedure specifications {\bf name} is
a character string parameter.
 
 
 
 Throughout this document the possible values of the
parameter {\bf type} are as given in {\it EDOC061}.
 
\hspace{1in}type\newline
\hspace*{1.5in}0\hspace*{1in} 8 bit unsigned integer\newline
\hspace*{1.5in}1\hspace*{1in} 8 bit signed integer\newline
\hspace*{1.5in}2\hspace*{1in} 16 bit unsigned integer\newline
\hspace*{1.5in}3\hspace*{1in} 16 bit signed integer\newline
\hspace*{1.5in}4\hspace*{1in} 32 bit unsigned integer\newline
\hspace*{1.5in}5\hspace*{1in} 32 bit signed integer\newline
\hspace*{1.5in}6\hspace*{1in} 32 bit IEEE floating point
 
 Throughout this document the possible values of the
parameter {\bf layout} are as given in {\it EDOC061}.
 
\hspace{1in}layout\newline
\hspace*{1.5in}0\hspace*{1in} histogram/full maxtrix\newline
\hspace*{1.5in}1\hspace*{1in} half matrix         \newline
 
\subsection{Define Path}
 
\vspace{3 mm}
 {\sf EGsetSpectrumPath}(path)
\vspace{4 mm}
 
 Allows a current path to be defined by the character string
parameter {\em path}.
 
 
\subsection{Access Authorisation}
 
  Certain servers (for example off-line disc servers) 
will require authorisation information before access 
is granted.
 
\vspace{3 mm}
 {\sf EGauthorise}(name,id,password)
\vspace{4 mm}
 
 For the spectrum server identified by {\bf pathname}
an access identifier in the character string parameter {\em id}
and associated password in the character string parameter 
{\em password} are supplied.
 
\subsection{Spectrum Create}
 
 Create a new spectrum in the server and directory identified by {\bf pathname}
(off-line servers) or in the server identified by {\bf pathname}
(on-line servers).
 
\subsubsection{nD spectrum create}
 
 {\sf EGcreateSpectrum}(name,dimension,base,range,layout,type)
\vspace{4 mm}
  
 {\em dimension} is an integer which contains the number of dimensions
in the spectrum.
 
 {\em base} is an integer array having at least {\em dimension}
elements which contains the number of the first channel 
for dimensions 1 to {\em dimension} of the spectrum and
{\em range} is an integer array having at least {\em dimension}
elements which contains the number of channels for dimensions
1 to {\em dimension} of the spectrum.
 
 {\em layout} is an integer which indicates the format of
the spectrum.  
 
 {\em type} is an integer which indicates the format of
each data item in the spectrum.
 
 {\em layout}  and {\em type} may be left undefined by 
setting to the value -1. They must however be defined by a
subsequent call on procedure EGsetSpectrumArray before any 
attempt to write to the spectrum is made.
 
 The error spectrum is undefined by this procedure but may 
be defined by a subsequent call on procedure EGsetSpectrumArray.
 
 
\subsubsection{1D spectrum create}
 
 {\sf EGcreate1dSpectrum}(name,base,range,type)
\vspace{4 mm}
  
 {\em base} is an integer containing the number of the first 
channel in the spectrum and {\em range} is an integer 
containing the number of channels in the spectrum.
 
 {\em type} is an integer which indicates the format of
each data item in the spectrum.
 
 {\em type} may be left undefined by 
setting to the value -1. It must however be defined by a
subsequent call on procedure EGsetSpectrumArray before any 
attempt to write to the spectrum is made.
 
 The error spectrum is undefined by this procedure but may 
be defined by a subsequent call on procedure EGsetSpectrumArray.
 
\subsubsection{2D spectrum create}
 
 {\sf EGcreate2dSpectrum}(name,base1,range1,base2,range2,
layout,type) 
\vspace{4 mm}
  
 {\em base1} is an integer containing the number of the first 
channel in dimension 1 of the spectrum and {\em range1} is an integer 
containing the number of channels in dimension 1 of the spectrum.
 
 {\em base2} is an integer containing the number of the first 
channel in dimension 2 of the spectrum and {\em range2} is an integer 
containing the number of channels in dimension 2 of the spectrum.
 
 {\em layout} is an integer which indicates the format of
the spectrum.  

 {\em type} is an integer which indicates the format of
each data item in the spectrum.
 
 {\em layout}  and {\em type} may be left undefined by 
setting to the value -1. They must however be defined by a
subsequent call on procedure EGsetSpectrumArray before any 
attempt to write to the spectrum is made.
 
 The error spectrum is undefined by this procedure but may 
be defined by a subsequent call on procedure EGsetSpectrumArray.

\subsection{Set Spectrum Array}
 
 Allows the array layout and type to be defined or redefined.
 
\vspace{3 mm}
 {\sf  EGsetSpectrumArray(name,number,layout,type)}
\vspace{4 mm}
 
 {\em number} is 1 to define the spectrum data array and 2 to 
define the error spectrum data array. 
 
 {\em layout} is an integer which indicates the format of
the spectrum.  

 {\em type} is an integer which indicates the format of
each data item in the spectrum.

\subsection{Locate Spectrum}
 
 Locate an existing spectrum  identified by
{\bf pathname}.
Enables the existance of a spectrum to be tested for and the 
result returned.
\par
\vspace{3 mm}
 {\sf EGlocateSpectrum}(name)
\vspace{4 mm}
 
 
\subsection{Delete Spectrum}
 
 Delete the spectrum identified by {\bf pathname}.
\par
\vspace{3 mm}
 {\sf EGdeleteSpectrum}(name)
\vspace{4 mm}
 
\subsection{Define Default Array}
 
 Defines the number of the data array to be accessed 
by subsequent calls of the read spectrum and 
write spectrum procedures.
\par
\vspace{3 mm}
 {\sf EGsetDefaultArray}(number)
\vspace{4 mm}
 
 {\em number} is 1 to access the spectrum data array and 
2 to access the error spectrum data array. By default the 
spectrum data array is accessed.
\vspace{4 mm}

\subsection{Read Spectrum Counts}
 
 Read spectrum data. An area of the spectrum may be fetched
which is of a size (normally greater) different from the
array into which the data is to be returned. In this case
the original data will be summed and scaled in order to
generate a histogram of the requested size and type.

\subsubsection{Define Data Scaling}
 
 Defines the range for each dimension in subsequent calls
of EGread*Spectrum.
 
\vspace{3 mm}
 {\sf EGsetDefaultScale}(dimension,size)
\vspace{4 mm}
 
 {\em dimension} is an integer which contains the number of
dimensions in the spectrum.
 
 {\em size} is an integer array having at least {\em dimension}
elements which contains the number of elements for 
dimensions 1 to {\em dimension} of {\em array} which is 
supplied in subsequent calls of read spectrum procedures.
 
 By default data scaling does not occur. An element of 
{\em size} set to zero implies no  scaling in that dimension.
 
 The effect of this procedure may be reset by a call with the
elements of {\em size} set to zero.
 
\subsubsection{nD Spectrum Data Read}
 
 {\sf EGreadSpectrum}(name,dimension,base,range,{\bf array},
type)
\vspace{4 mm}
 
 
  
 {\em dimension} is an integer which contains the number of
dimensions in the spectrum.

 {\em base} is an integer array having at least {\em dimension}
elements which contains the base channel for dimensions
1 to {\em dimension} to be used by the read request and
{\em range} is an integer array having at least {\em dimension}
elements which contains the number of channels for 
dimensions 1 to {\em dimension} required by the read request.

 The {\em base} and {\em range} arguments must define a region of 
counts lying entirely within the spectrum.
 
 The data is returned in {\em array} with the spectrum
counts stored with the last dimension varying 
fastest (the standard C ordering).

{\em type} is an integer which indicates the format
of each data item in {\em array}. {\em type}
need not be the same as the type of the counts 
held in the spectrum. The appropiate sign extension or
truncation will take place automatically.
 
If the elements of {\em size} have been defined by a 
previous call on procedure EGsetDefaultScale and are different
from the elements of {\em range} then the spectrum data 
requested by {\em base} and {\em range} will be scaled to 
fit the space defined by {\em size}.
 
 
\subsubsection{1D Spectrum Read}
 
 {\sf EGread1dSpectrum}(name,base,range,{\bf array},type)
\vspace{4 mm}
 
 
 {\em base} is an integer
 which contains the base channel
 to be used by the read request and
{\em range} is an integer 
which contains the number of channels  
required by the read request.


 The {\em base} and {\em range} arguments must define a region of 
counts lying entirely within the spectrum.
 
 The data is returned in {\em array}.


 
{\em type} is an integer which indicates the format
of each data item in {\em array}. {\em type}
need not be the same as the type of the counts 
held in the spectrum. The appropiate sign extension or
truncation will take place automatically.
 
 If  {\em size} has been defined by a previous call         
on procedure EGsetDefaultScale and   is  different from  
{\em range} then the spectrum data requested by {\em base} and
{\em range} will be scaled to fit the
space defined by {\em size}.
 
 
\vspace{2 mm}
 {\bf Example}  -   channels 0 to 3000 of a spectrum are to be 
read and returned as 16 bit unsigned integers

 {\sf EGread1dSpectrum}(name,0,3000,array,2)
\vspace{3 mm}

 {\bf Example} - channels 0 to 4095 of a spectrum are to be
read and returned as 16 bit unsigned integers in a 512 element 
array
 
 {\sf EGsetDefaultScale}(512)
\newline
\par
 {\sf EGread1dSpectrum}(name,0,4095,array,2)
\vspace{4 mm}
 
\subsubsection{2D Spectrum Read}
 
 {\sf EGread2dSpectrum}(name,base1,range1,base2,range2,{\bf array},
type)
\vspace{4 mm}
 
 
  
 {\em base1} and {\em base2} are    integers
 which contains the base channels for dimensions 1 and 2
 to be used by the read request and
{\em range1} and {\em range2} are    integers
which contains the number of channels in dimensions 1 and 2
required by the read request.


 The {\em base} and {\em range} arguments must define a region of 
counts lying entirely within the spectrum.
 
 The data is returned in {\em array} with the spectrum
counts stored with the last dimension varying 
fastest (the standard C ordering).



{\em type} is an integer which indicates the format
of each data item in {\em array}. {\em type}
need not be the same as the type of the counts 
held in the spectrum. The appropiate sign extension or
truncation will take place automatically.
 
 If the elements of {\em size} have been defined by a previous call         
on procedure EGsetDefaultScale and   are different from {\em range*} 
then the spectrum data requested by {\em base*} and {\em range*} 
will be scaled to fit the
space defined by {\em size}.
 
 
\vspace{2 mm}
 {\bf Example}  -
a 4K by 4K 2D matrix is to be returned
as 16 bit signed integers.

 {\sf EGread2dSpectrum}(name,0,4096,0,4096,array,3)
\vspace{4 mm}
 
\subsection{Write Spectrum Counts}
 
\subsubsection{nD Spectrum Data Write}
 
 {\sf EGwriteSpectrum}(name,dimension,base,range,array,type)
\vspace{4 mm}
 
 
  
 {\em dimension} is an integer which contains the number of
dimensions in the spectrum.

 {\em base} is an integer array having at least {\em dimension}
elements which contains the base channel for dimensions
1 to {\em dimension} to be used by the write request and
{\em range} is an integer array having at least {\em dimension}
elements which contains the number of channels for 
dimensions 1 to {\em dimension} supplied by the write request.


 The {\em base} and {\em range} arguments must define a region of 
counts lying entirely within the spectrum.
 
 The data is supplied in {\em array} with the spectrum
counts stored with the last dimension varying 
fastest (the standard C ordering).


 
{\em type} is an integer which indicates the format
of each data item in {\em array}. {\em type}
need not be the same as the type of the counts 
held in the spectrum. The appropiate sign extension or
truncation will take place automatically.
 
 
\subsubsection{1D Spectrum Write}
 
 {\sf EGwrite1dSpectrum}(name,base,range,array,type)
\vspace{4 mm}
 
 
  
 {\em base} is an integer
 which contains the base channel
 to be used by the write request and
{\em range} is an integer 
which contains the number of channels  
supplied by the write request.

 The {\em base} and {\em range} arguments must define a region of 
counts lying entirely within the spectrum.
 
 The data is supplied in {\em array}.

{\em type} is an integer which indicates the format
of each data item in {\em array}. {\em type}
need not be the same as the type of the counts 
held in the spectrum. The appropiate sign extension or
truncation will take place automatically.
 

 
\subsubsection{2D Spectrum Write}
 
 {\sf EGwrite2dSpectrum}(name,base1,range1,base2,range2,array,
type)
\vspace{4 mm}
 
 
  
 {\em base1} and {\em base2} are    integers
 which contains the base channels for dimensions 1 and 2
 to be used by the write request and
{\em range1} and {\em range2} are    integers
which contains the number of channels in dimensions 1 and 2
supplied by the write request.


 The {\em base} and {\em range} arguments must define a region of 
counts lying entirely within the spectrum.
 
 The data is supplied in {\em array} with the spectrum
counts stored with the last dimension varying 
fastest (the standard C ordering).


 
{\em type} is an integer which indicates the format
of each data item in {\em array}. {\em type}
need not be the same as the type of the counts 
held in the spectrum. The appropiate sign extension or
truncation will take place automatically.
 
 
\subsection{Read Header String}
 
 The spectrum format allows for up to 16 information 
strings to be held for each spectrum plus one
annotation, one calibration and one efficiency 
string per dimension.
 
\subsubsection{Read Information String}
 
 {\sf EGreadInformation}(name,number,{\bf string})
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the number of
the information string to be returned.

 The data is returned in the character string parameter  {\bf string}.

 
\vspace{2 mm}
Certain of the 16 available information strings are
by convention used to hold specific types of data 
associated with the spectrum. For convenience specific
procedures are available to access these.
 
 
\vspace{2 mm}
 {\sf EGreadTitle}(name,{\bf string})
 
 equivalent to EGreadInformation with number equal 1
 
 
\vspace{2 mm}
 {\sf EGreadExpt}(name,{\bf string})
 
 equivalent to EGreadInformation with number equal 2
 
 
\vspace{2 mm}
 {\sf EGreadRun}(name,{\bf string})
 
 equivalent to EGreadInformation with number equal 3
 
 
\vspace{2 mm}
 {\sf EGreadComment}(name,{\bf string})
 
 equivalent to EGreadInformation with number equal 4
 
 
\subsubsection{Read Annotation String}
 
 {\sf EGreadAnnotation}(name,number,{\bf string})
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the spectrum dimension
associated with the annotation  string to be returned.

 The data is returned in the character string parameter  {\bf string}.


 
 
\subsubsection{Read Calibration String}
 
 {\sf EGreadCalibration}(name,number,{\bf string})
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the spectrum dimension
associated with the calibration  string to be returned.

 The data is returned in the character string parameter  {\bf string}.


 
\subsubsection{Read Efficiency String}
 
 {\sf EGreadEfficiency}(name,number,{\bf string})
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the spectrum dimension
associated with the efficiency  string to be returned.

 The data is returned in the character string parameter  {\bf string}.


 
\subsection{Write Header String}
 
\subsubsection{Write Information String}
 
 {\sf EGwriteInformation}(name,number,string)
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the number of
the information string to be written.  

 The data is supplied in the character string parameter  {\bf string}.

 
Certain of the 16 available information strings are
by convention used to hold specific types of data 
associated with the spectrum. For convenience specific
procedures are available to access these.
 
 
\vspace{2 mm}
 {\sf EGwriteTitle}(name,string)
 
 equivalent to EGwriteInformation with number equal 1
 
 
\vspace{2 mm}
 {\sf EGwriteExpt}(name,string)
 
 equivalent to EGwriteInformation with number equal 2
 
 
\vspace{2 mm}
 {\sf EGwriteRun}(name,string)
 
 equivalent to EGwriteInformation with number equal 3
 
 
\vspace{2 mm}
 {\sf EGwriteComment}(name,string)
 
 equivalent to EGwriteInformation with number equal 4
 
 
 
\subsubsection{Write Annotation String}
 
 {\sf EGwriteAnnotation}(name,number,string)
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the spectrum dimension
associated with the annotation  string to be written. 

 The data is supplied in the character string parameter  {\bf string}.


 
 
\subsubsection{Write Calibration String}
 
 {\sf EGwriteCalibration}(name,number,string)
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the spectrum dimension
associated with the calibration  string to be written. 

 The data is supplied in the character string parameter  {\bf string}.


 
\subsubsection{Write Efficiency String}
 
 {\sf EGwriteEfficiency}(name,number,string)
\vspace{4 mm}
 
 
  
 {\em number} is an integer which contains the spectrum dimension
associated with the efficiency  string to be written. 

 The data is supplied in the character string parameter  {\bf string}.


 
 
 
\subsection{Inquire Spectrum Attributes}
 
 Obtain miscellaneous information about the spectrum.
 
\subsubsection{nD Inquire Attributes}
 
 {\sf EGinquireSpectrum}(name,{\bf dimension},{\bf base},{\bf range},
{\bf layout}, {\bf type})
\vspace{4 mm}
  
 {\bf dimension} is an integer which is returned with the number of dimensions
in the spectrum.
 
 {\bf base} is an integer array having at least {\bf dimension}
elements which is returned with the number of the first channel 
for dimensions 1 to {\bf dimension} of the spectrum and
{\bf range} is an integer array having at least {\bf dimension}
elements which is returned with the number of channels for dimensions
1 to {\bf dimension} of the spectrum.
 
 
 {\bf layout} is an integer array having 2 elements which is 
returned with the format of the data arrays.
 
 {\bf type} is an integer array having 2 elements which is 
returned with the format of each data item in the data arrays.
 
 
 
 
\subsubsection{1D Inquire Attributes}
 
 {\sf EGinquire1dSpectrum}(name,{\bf base},{\bf range},
{\bf type1}, {\bf type2})
\vspace{4 mm}
  
 {\bf base} is an integer which is returned with the number of the first 
channel in the spectrum and {\bf range} is an integer 
which is returned with the number of channels in the spectrum.
 
 {\bf type1} is an integer returned  which indicates the format of
each data item in the spectrum and {\bf type2} is an integer 
returned which indicates the format of each data item in the
error spectrum.
If the error spectrum is undefined the value -1 will be returned.
 
 
 
\subsubsection{2D Inquire Attributes}
 
 {\sf EGinquire2dSpectrum}(name,{\bf base1},{\bf range1},{\bf base2},{\bf range2},{\bf layout1},
{\bf layout2},\newline {\bf type1},{\bf type2})
\vspace{4 mm}
  
 {\bf base1} is an integer which is returned with the number of the first 
channel in dimension 1 of the spectrum and {\bf range1} is an integer 
which is returned with the number of channels in dimension 1 of the spectrum.
 
 {\bf base2} is an integer which is returned with the number of the first 
channel in dimension 2 of the spectrum and {\bf range2} is an integer 
which is returned with the number of channels in dimension 2 of the spectrum.

 {\bf layout1} is an integer returned  which indicates the format of
the spectrum and {\bf layout2} is an integer 
returned which indicates the format of  the
error spectrum.
If the error spectrum is undefined the value -1 will be returned.
 
 {\bf type1} is an integer returned  which indicates the format of
each data item in the spectrum and {\bf type2} is an integer 
returned which indicates the format of each data item in the
error spectrum.
If the error spectrum is undefined the value -1 will be returned.
 
 
\subsection{Miscellaneous}
 
 Available with on-line servers only.
These procedures are intended for use only by data aquisition
software which requires direct access to the spectrum
counts space and are not expected to be of general interest.
 
\subsubsection{Obtain VME address of data array}
 
 Returns the VME address of the base of the data array 
associated with the spectrum.
 
\vspace{3 mm}
 {\sf EGinquireAddress}(name,{\bf address})
\vspace{4 mm}
 
 For the spectrum identified by {\em pathname} returns the VME
address in {\bf address}.
 
 
 
\subsection{Read Names}
 
 Obtain the next name from the location 
identified by {\bf pathname}. For on-line 
spectra {\bf pathname} is just the name of a server. For 
off-line spectra {\bf pathname} should identify a
disc directory.
 
\vspace{3 mm}
 {\sf EGinquireDirectory}(name,{\bf string})
\vspace{4 mm}
 
  The first name is returned in the character string 
parameter {\bf string}.
 
\vspace{3 mm}
 {\sf EGinquireDirectoryMore}({\bf string})
\vspace{4 mm}
 
  The next name is returned in the character string 
parameter {\bf string}.
 
 Successive calls to this procedure allow the names of all
objects within the defined directory or server to be obtained.

 The procedures EGinquireDirectory and EGinquireDirectoryMore
return an integer which indicates the type of the name 
returned.
 
\hspace{1in}value\newline
\hspace*{1.5in}0\hspace*{1in} the name refers to a spectrum   \newline
\hspace*{1.5in}1\hspace*{1in} the name refers to a directory \newline
\hspace*{1.5in}2\hspace*{1in} the name refers to a something else \newline
\hspace*{1.5in}3\hspace*{1in} the directory is empty or the end of \newline
\hspace*{2.6in}               the directory has been reached \newline

\subsection{Generate Error Message}
 
  Converts the error number returned by a procedure
into a meaningfull text message.
 
\vspace{3 mm}
 {\sf spgenerrmess}({\bf text})
\vspace{4 mm}
 
  Converts EGerrno into a text string which is returned
in the character string parameter {\bf text}.
 
 
\section{Return\_Codes}
 
 To be supplied
 
\section{Language Bindings}
 
 The interface procedures support bindings for the C
and Fortran languages.
 
 The procedure names are valid for C. While not valid
for ANSI Fortran 77 they are  valid for Fortran 90
and are acceptable for Sun Fortran. The procedure 
names given in this document may thus 
be used by both Fortran and C bindings within the 
Eurogam environment.
 
 Throughout the procedure specifications variable length
text parameters are identified as {\em character string parameters}.
For the C binding such parameters should be of type {\em char} 
and the text string should follow the C convention and be
terminated by a null character. For procedures which return a
text string the space reserved by the caller should be large
enough to hold the text string plus the terminating 
null character.
 For the Fortran binding such parameters should be of type
{\em character} and be padded as necessary with trailing 
space characters.

 For Fortran use the procedures should be invoked as
subroutines.
 
\section{Implementation}
 
 To be supplied
 
\section{Further Study}
 
  read spectrum projections (slicing)
 
  scaling options for read
 
  debugging (and other) options
 
\end{document}
