\documentstyle[11pt,a4wide]{article}
\title{Spectrum Database Structure}
\author{Jean Zen}
\date{September 1990}
\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
EDOC102\par
\vskip .5truein
\large
EUROGAM PROJECT\par
\vskip 1.5truein
\hrule height 2pt
\vskip 20pt
\medium
VIVITRON DATA ACQUISITION SYSTEM\par
\vskip .5truein
Spectrum Database Structure\par
\vskip 20pt
\hrule height 2pt
\vskip 1truein
\medium
Edition 0.1\par
\vskip 5pt
September 1990\par
\vfill
\medium
Service Acquisition et Traitement de Donnees\par
\vskip 5pt
Centre de Recherches Nucleaires\par
\vskip 5pt
Strasbourg\par
\vskip .5truein

}
\end{titlepage}


\maketitle
\section{Introduction}

	This document outlines a general structure of saved spectrum files
in a disk file system (eg. NFS). It is also intended to be applied to online
spectra, if the online spectra memory can be mapped to a file.

	A spectrum file consists of a header bloc and a counts bloc(s). The
first coded in ASCII and the second in binary are contiguous and accessible
in direct access mode (Fortran) or in stream mode (C). 

	A spectrum file may also contain many spectra (main spectrum + subrange
spectra). A such file is simply obtained by appending as many header and counts
blocs to the main spectrum blocs. In this case, a pointer index table is
necessary for quick access to a subrange spectrum. The index table may be
machine dependent due to the access method used but resides in a seperate
file whose name differs in prefix with that of the spectrum file (on Unix 
machines if the prefix is ".", the index file will be hidden to user).
The location of the index table on a separate file permits no limitation
on the number of subrange spectra.

\section{Header bloc (multiple of 512 bytes)}

All unused (trailing) field must be filled with 'space' characters.

First line (byte 1 to 80):

2:16		run name 

18:24		run number

26:40		spectrum name

42:48		spectrum number

50:68		date of the form NN-MMM-YY HH:MM:SS

70:80		spectrum type (keywords : 1D, 2D, 3D or 4D)



Second line (byte 81 to 160):

80+2:8		precision

		keywords : BIT*1, BIT*2, BIT*4, BIT*8, BIT*16, BIT*32,
		  INT*2, INT*4, REAL*4, REAL*8 or REAL*16
		  (REAL + some BIT precisions not recommanded for exchange)

80+10:16	X range

80+18:24	X base  (counted starting from 0)

80+26:32	Y range (0 if not applicable)

80+34:40	Y base  (0 if not applicable)

80+42:48	Z range (0 if not applicable)

80+50:56	Z base  (0 if not applicable)

80+58:64	T range (0 if not applicable)

80+66:72	T base  (0 if not applicable)

80+74:76	byte ordering (keywords : MSB or LSB)

80+78:80	reserved


Third line (byte 161 to 240) :

Efficiency calibration

number of coefficients followed by the coefficients (in free floating
point format)

Fourth line (byte 241 to 320):

240+2:8	application id (keyword : APPLIC the only one applicable)

240+10:16	header length in bytes (multiple of 512)

240+18:32	experiment name

240+34:40	version number

240+42:50	beam energy (optional)

240+52:60	beam ion species (optional)

240+62:70	target species (optional)

240+72:80	for free use


Fifth line (byte 321 to 400) :

X calibration 

number of coefficients followed by the coefficients (in free floating
point format)

sixth line (byte 401 to 480) :

Y calibration 

number of coefficients followed by the coefficients (in free floating
point format)


seventh line (byte 481 to 512 or farther)

min,max counts (to be elaborated)


\section{Counts array bloc (multiple of 512 bytes)}

The array elements hold the channel counts in the standard Fortran array
element ordering (the X range subscript varies most rapidly). The number
of elements is derived from the specification in the header bloc and
completed to a multiple of 512 bytes.

\section{Spectra index table}

For a spectrum file consisting of more than one spectrum, a separate index
table file is used for quick access to a subrange spectrum. This table is
suggested to be structured as follows :

	1. number of the existing subrange spectra in the file (in integer*4)

	2. number of bytes written (= next free byte address in integer*4)

	3. byte address of the 1st subrange spectrum header bloc (in INT*4)

	4. byte address of the 2nd subrange spectrum header bloc (in INT*4)

	... ...


\section{Spectrum access routines}

	All capital arguments refer to outputs returned by the calls
(eg. IERs are returncodes).

\subsection{create and delete spectrm}


spdef (IDTAG, nsub, ndim, nxyz, nbyte, namsp, IER)

spdel (idtag, nsub, IER)


idtag	= a communication variable to identify the spectrum file

nsub	= 0 (zero) to create or delete a spectrum file
	otherwise to add a new subrange spectrum (in this case
	idtag must be known by a previous spdef or sptag call) or to
	delete a last subrange spectrum


ndim	= number of the dimensions of the spectrum to be created (1, 2 or 3)

nxyz	= a three element array denoting X, Y and Z ranges

nbyte	= number of bytes used for the spectrum counts (1, 2 or 4)

namsp	= a 14 character string for the name of spectrum (and file too if nsub=0)

\subsection{obtain spectrum idtag or subrange}


sptag (IDTAG, namsp, IER)

spsub (idatg, NSUB, namsp, IER)


nsub	= subrange number returned given the name of a subrange spectrum

\subsection{inquire spectrum attributes}

spinq (idtag, nsub, NDIM, NXYZ, NBYTE, IER)

spnam (idtag, nsub, NAMSP, IER)

\subsection{read and write counts}


spread (idtag, nsub, iy, ny, iz, nz, IARR, IER)

spwrit (idtag, nsub, iy, ny, iz, nz, iarr, IER)


iarr	= counts array to be read or written (array elements must be contiguous,
	a minimum of a full range of X dimension is read or written)

iy	= requested base on Y dimension 

ny	= requested range on Y dimension

iz	= requested base on Z dimension 

nz	= requested range on Z dimension

\subsection{read and write annotation strings}

Most of the Daresbury SDB routines are applicable but should have an additional
'nsub' argument and likely be named differently.

\section{Related documents}


Introducing the SDB spectrum access system, Sept 1985, NSF, Daresbury

Accessing spectra, Feb 1988, NSF, Daresbury

Norme spectres sur disquettes, May 1988, IPN/CSNSM, Orsay

Systeme de gestion des fichiers de spectres, Nov 1988, CRN, Strasbourg

\end{document}