\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
EDOC061\par
\vskip .5truein
\large
EUROGAM PROJECT\par
\vskip 1.5truein
\hrule height 2pt
\vskip 20pt
\large
NSF DATA ACQUISITION SYSTEM\par
\vskip .5truein
Unified Spectrum Format\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 2.2\par
\vskip 5pt
Jan 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 \magstep1
\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
 Previous discussion documents have proposed structures for
a spectrum database and for data storage. It has also previously 
been suggested that the same   format be used for on-line 
spectra, disc based spectra and for spectra archived on tape.
The requirements for a spectrum format for both on-line and 
off-line use have been specified in the document EDOC060. This 
document describes a format which meets the requirements of 
EDOC060 and can be used for on-line spectra in the histogrammer or
sorter and for off-line spectra held on disc or tape. Requirements 
for implementation are defined. \par
The  document EDOC060 should be read for
formal specification of the requirements.
The document EDOC062 should be read for details of
program access to the spectrum data.
\vskip .3in
 
{\large Document History}
\vskip .2in
Version 1.0 Dec 1990 -   Initial version
 
Version 2.0 May 1991 - re-order fields in the header and
reduce data arrays to just spectrum and an optional 
error spectrum.
Unused pointers now contain -1 so that pointers may have the
value 0.

Version 2.1 Sept 1991 - Removal of graph type arrays, change to 
data array descriptor, n dimensional arrays stored following
C rather than Fortran ordering convention.
 
Version 2.2 Jan 1992 - Number of Information strings increased to 32.
\vskip .3in
{\large Terminology}
\vskip .2in
Throughout this document several terms in common usage are used 
which are defined here to avoid misinterpretation.       \lb
Spectrum - any collection of data items which includes 
the conventional 1D histogram and 2D matrices in common use.   \lb
Channel - an individual data item in a spectrum.    \lb
On-line - spectra held in memory (normally VME global memory
or a processor memory) which is potentially being incremented 
by either hardware or software. This includes spectra 
being generated by a post experiment data replay. \lb
Off-line - spectra held on secondary storage (normally disc)
which may be read or mapped into processor memory. The data 
contents are not normally being changed. \par
\vskip .3in
{\large General Format}
\vskip .2in
Each spectrum consists of three parts; a header, an string space and
a counts space.  
For on-line spectra the components may not be contiguous but 
would be allocated within a large memory space. For off-line
spectra the components would normally be contiguous within a
space defined by the disc file holding the spectrum with the
header as the first component in the file. \lb
The spectrum header is a fixed length 512 byte data structure which 
is used to access all items in the string and counts spaces. The
associated string space and counts space are allocated in units
of 256 bytes.   \lb
The string space is used to hold character strings which contain 
name, title, annotation and calibration information etc. Each
character string is allocated one (or more) units of
256 bytes from the string space. The
character string is represented using the standard XDR format
which is a 32 bit integer field containing the number of
significant characters which follow. The characters are padded 
to fill the allocated space with trailing null characters. \lb
Note: The minimum space allocation allows for strings of upto
252 characters in length but any required length is possible
by allocating the necessary number of contiguous 256 byte 
fragments.  \lb
The address of each character string expressed as an offset into 
the string space is held as a pointer in the spectrum header. Unused
pointers which do not have string space allocated are set to -1. \lb
The counts space is used to hold data arrays which contain 
the spectrum counts and is used and referenced in the same
way as the string space. 
\vskip .3in
{\large Header Format}
\vskip .2in
\section{}
\heading={}
\table
\half{magic number}
\half{header version number}
\full{spectrum name}
\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 1 pointer}
\full{:}
\half{information 32 pointer}
\half{annotation 1 pointer}
\full{:}
\half{annotation 8 pointer}
\half{calibration 1 pointer}
\full{:}
\half{calibration 8 pointer}
\half{efficiency 1 pointer}
\full{:}
\half{efficiency 8 pointer}
\full{data array 1 descriptor}
\full{data array 2 descriptor}
\half{base address of string space}
\half{string free space}
\half{top of string space}
\half{base address of counts space}
\half{counts free space}
\half{top of counts space}
\full{unused}
\endtable
\desc
Offset 0 - {\sl magic number}. A 32 bit integer field set to the
value 412900921 (decimal). The {\sl magic number}  
can be used as a test that a disc file probably does contain 
a spectrum.  \lb \lb
Offset 4 - {\sl header version number}. A 32 bit integer field set
to the value 1. Available to allow other header formats in the 
future. This document describes version 1 of the header. \lb \lb
Offset 8 - {\sl spectrum name}. A 32 byte field containing
the name of the spectrum padded where necessary with trailing null
characters.
In the on-line mode this field is used to access the spectrum.
In the off-line mode spectra are accessed only by the disc file name
and this field may be ignored (set to all null characters) unless the
spectrum was   previously an on-line spectrum in which case
the name should be preserved but it will not be used for 
spectrum access. \lb \lb
Offset 40 - {\sl dimension}. A 32 bit integer field which 
contains the number of dimensions used to describe this spectrum. 
This version of the header allows for a maximum of 8 dimensions.
\lb \lb
Offset 44 - {\sl creation time and date}. A 20 byte field
containing the time and date at which the spectrum was
first created as ASCII text in the form ``nn-mmm-yyyy hh:mm:ss''
( e.g. 06-Dec-1990 12:07:00 ).
When an on-line spectrum is written to disc this field 
is preserved and the disc file creation time/date used to 
record when the spectrum was written to disc. \lb \lb
Offset 64 - {\sl modification time and date}. A 20 byte field 
containing the time and date at which the spectrum was
last  modified as ASCII text in the form ``nn-mmm-yyyy hh:mm:ss''.
When an on-line spectrum is written to disc this field 
is preserved.   \lb \lb
Offset 84 - {\sl dimension 1 base}. A 32 bit integer field 
containing the coordinate of the first channel for 
dimension 1 of the spectrum. \lb \lb
Offset 88 to 112. Base information for dimensions 2 to 8. Unused
fields should be set to -1.  \lb   \lb
Offset 116 - {\sl dimension 1 range}. A 32 bit integer field
containing the number of channels for dimension 1
of the spectrum. \lb \lb
Offset 120 to 144. Range information for dimensions 2 to 8. Unused
fields should be set to -1.  \lb     \lb
Offset 148  - {\sl information 1 pointer}. A 32 bit integer field
containing the offset from the base of the string space of a character
string holding information about this spectrum. If unused should be set to
-1.  \lb \lb
Offset 152  to 272. Further information pointers. See later for the
use of the information fields. Unused pointers should be set to -1.
\lb \lb
Offset 276 - {\sl annotation 1 pointer}. A 32 bit integer field
containing the offset from the base of the string space of a character
string holding annotation information for dimension 1. If unused  
should be set to -1.  \lb \lb
Offset 280 to 304. Annotation pointers for dimensions 2 to 8.   
Unused pointers should be set to -1.
\lb \lb
Offset 308 - {\sl calibration 1 pointer}. A 32 bit integer field 
containing the offset from the base of the string space of
a character string holding calibration information for dimension 1.
If unused should be set to -1.
\lb \lb
Offset 312 to 336. Calibration pointers for dimensions 2 to 8. Unused
fields should be set to -1. \lb \lb
Offset 340 - {\sl efficiency  1 pointer}. A 32 bit integer field 
containing the offset from the base of the string space of
a character string holding efficiency  information for dimension 1.
If unused should be set to -1.
\lb \lb
Offset 344 to 368. Efficiency pointers for dimensions 2 to 8. Unused
fields should be set to -1. \lb \lb
Offset 372 - {\sl data array 1 descriptor}. A 20 byte  field 
containing a description of the format of the data array
for this spectrum.     \lb \lb
Offset 392 - {\sl data array 2 descriptor}. A 20 byte  field 
containing a description of the format of an error spectrum
associated with this spectrum. If unused this field should be
set to all one bits.  \lb  \lb
Offset 412 - {\sl base address of string space}. A 32 bit integer field
which contains the   address of the base of the string 
space.
For on-line spectra it will be an absolute VME address. For 
off-line spectra it should be set to the offset of the string space
from the base of the header.   \lb  \lb
Offset 416 - {\sl string free space}. A 32 bit integer 
field containing the offset from the base of the string space of the first 
unused location. \lb \lb
Offset 420 - {\sl top of string space}. A 32 bit integer
field containing the offset from the base of the string space
of the last available location. \lb \lb
Offset 424 - {\sl base address of counts space}. A 32 bit integer field
which contains the   address of the base of the  
counts space.
For on-line spectra it will be an absolute VME address. For 
off-line spectra it should be set to the offset of the counts space
from the base of the header.   \lb  \lb
Offset 428 - {\sl counts free space}. A 32 bit integer 
field containing the offset from the base of the counts space of the first 
unused location. \lb \lb
Offset 432 - {\sl top of counts space}. A 32 bit integer
field containing the offset from the base of the counts space
of the last available location. \lb \lb
For further description of the uses of the space address and offset
fields see the section on Implementation.     \lb \lb
Offset 436 to 512. Unused         \lb
\enddesc
\eject
{\small  Data Array Descriptor}
\table
\half{array layout}
\half{array type}
\half{reserved for future use}
\half{reserved for future use}
\half{pointer}
\endtable
\desc
Offset 0 - {\sl array layout}. A 32 bit integer field which is used
to define the format of channel items within a data array (see below).
This field will be -1 for an unused array descriptor.
\lb \lb
Offset 4 - {\sl array type}. A 32 bit integer field which is used 
to define the format of the data item within a channel item 
(see below).  \lb \lb
Offset 16 - {\sl pointer}. A 32 bit integer field containing the
offset from the base of the counts space of the data array.
This field will be -1 for an unused array descriptor.
\vskip .2in
The {\sl array layout} defines the format of each channel item
and the ordering of channel items within the  data array.
\smallskip
\settabs\+
\qquad&xxxxxxxxxxxxxxxx\quad&0000\quad&xxxxxxxxxxxxxxxxx \cr
\+&     array layout = &   0  &  histogram/matrix  \cr
\+&                    &   1  &  histogram/half matrix \cr
For a spectrum having dimension n \lb
{\sl histogram/matrix} - each channel item consists only of a 
data item    ordered following the C language convention for a n 
dimensional array.    \lb
{\sl histogram/half matrix} only stores the upper diagonal of the array.   \lb
\vskip .2in
The {\sl array type} defines the format of the data item    
component of each channel item within the data array.
\smallskip
\settabs\+
\qquad&xxxxxxxxxxxxxxxx\quad&0000\quad&xxxxxxxxxxxxxxxxx \cr
\+&  array type      = &   0  &  8 bit unsigned integer \cr
\+&                    &   1  &  8 bit signed integer \cr
\+&                    &   2  &  16 bit unsigned integer \cr
\+&                    &   3  &  16 bit signed integer \cr
\+&                    &   4  &  32 bit unsigned integer \cr
\+&                    &   5  &  32 bit signed integer \cr
\+&                    &   6  &  32 bit floating point \cr
Signed integers are held in 2s complement format and
floating point numbers in IEEE format.
\vskip .2in
{\small Information strings}
\vskip .2in
Up to 32 information strings are available per spectrum.\lb
String 1 is allocated for spectrum title information. \lb
String 2 is allocated for information about the 
experiment which created the spectrum - for example 
experiment name, beam energy, beam ion species and target species etc. \lb
String 3 is allocated for information about the 
run within the experiment - for example 
run name, run number etc. \lb
Strings 4 and 5 are available for a general comment indicating 
the content of data arrays 1 and 2.      \lb
The remaining strings are available for general user comments
or additional information. \lb
All information strings are free format text and may contain
any printable characters including LF (UNIX end of line).
\vskip .2in
{\small Annotation strings}
\vskip .2in
One string per dimension is available to allow for a 
description of the ``significance of the dimension''.
For example it could contain the ``units'' (MeV , cm etc) of the
calibration.
\vskip .2in
{\small Calibration strings}
\vskip .2in
One string per dimension is available to hold calibration 
information for that dimension. The information is held 
free format in character representation. The first field in the
string is the name of the calibration method and the 
remaining fields are parameters to that calibration routine.
\vskip .2in
{\small Efficiency  strings}
\vskip .2in
One string per dimension is available to hold efficiency  
information for that dimension. The information is held 
free format in character representation. The first field in the
string is the name of the efficiency calculation algorithm  and the
remaining fields are parameters to that algorithm.
\eject
{\large Data Interchange}
\vskip .2in
 This document describes a common format for spectra held in memory
or on disc. On-line spectra will at the end of a run 
be 'saved' and become off-line spectra held on disc. The disc
files can be copied to any available magnetic tape 
medium in the same format for backup and archive purposes
using standard system utilities (for UNIX one would 
use {\it tar} or {\it dump}). Spectra can be moved in this 
format between the UNIX workstations in the Eurogam
colaboration using the utility {\it tar} or by a network
connection.
 
 For interchange of data with laboratories outside the
Eurogam colaboration and for those running other
data analysis systems which may wish to import the 
Eurogam data a more system independant format which can 
be used for writing spectra onto tape is desired. This
format can trade efficiency of access and compactness 
of the data for maximum easy of interchange.
A suitable format for this  purpose is described in the
document {\it EDOC080}.
\vskip .2in
{\large Implementation}
\vskip .2in
Suggestions as to methods of implementation to be provided.
\endGroup
\end
