% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% THE ZEUS PRIMER
% 
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% version 2,00      Aug  94   update
% version 1.04      Jun  93   ZDIS also on ZOW, make style nicer (like zarah pr) 
% version 1.03      Jun  93   include new rules for writing papers
%                             introduction to zarah 
%
% version 1.02      Feb  93   LHK  mail no longer to zow  (use e.g. zow01)
%                             mention Karl Gathers VAX primer and DESY 
%                             computing newsletter for unix, and gv on VXDESY
%                             say to include X11R5 in path
%                             No more lprint on IBM, use PLOT instead
%                             New directory for eaze jobs on IBM
%                             no more support for /zeus/old and /zeus/new     
%
% version 1.01      Jan  93   LHK  mail can be printed out directly on VAX
%                                 (PAWLAK)  CAD picture
% version 1.00      Jan  93   LHK  include comments w.r.t. draft version
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \special{!userdict begin /bop-hook{gsave 200 30 translate
% 65 rotate /Times-Roman findfont 216 scalefont setfont
% 0 0 moveto 0.93 setgray (DRAFT) show grestore}def end}
%\documentstyle[11pt,/users/koepke/a4p,makeidx,epsf]{report}
%\documentstyle[11pt,a4p,palatino,makeidx,epsf,twoside]{report}
\documentstyle[11pt,palatino,makeidx,epsf,manual2]{report}
%\documentstyle[11pt,palatino,twoside,makeidx,a4p,epsf]{report}
\makeindex
\setcounter{tocdepth}{1}
\begin{document}
\pagestyle{headings}
\parindent 0pt
\newenvironment{indentlist}[2]
{\begin{list}{}{\setlength{\labelwidth}{#1}
\setlength{\leftmargin}{#2}}}{\end{list}}
\newcommand{\indentitem}[1]{\item[#1\hfill]}
\newcommand{\indentbf}[1]{\item[\bf{#1}\hfill]}
\newcommand{\indenttt}[1]{\item[\tt{#1}\hfill]}
\newcommand{\indentem}[1]{\item[\em{#1}\hfill]}
\newcommand{\type}[1]{\begin{quote}{\tt{#1}}\end{quote}}
\newcommand{\tp}[1]{{\tt{#1}}}
\newcommand{\ind}[1]{#1\index{#1}}
\newcommand{\degree} {$^\circ$}
\newcommand{\cth}    {$|\cos\theta|$}
\def\mytopsep{2pt}
\def\myitemsep{1pt}
\def\myrightmargin{24pt}
\def\myleftmargin{42pt}
\def\mylabelsep{10pt}
\def\mytitle{ZEUS Primer}
% this is a nice one; makes annotation at right hand margin
\def\margtxt#1{\marginpar{\raggedright\footnotesize\bf{#1}}}
%
\parskip12pt plus 1pt minus 1pt
\topsep0pt plus 1pt

% make fancy header page: to change date and version number you 
% will have to edit postscript file !
%\pagestyle{empty}
\begin{picture}(300,500)
\centerline{\epsffile{/users/koepke/texfiles/cover_zeus_primer.eps}}
\end{picture} 
\newpage
\vfill
\pagebreak
\pagenumbering{roman}
%\title{\Huge\bf The ZEUS Primer}
%\author{\LARGE\bf L. K\"opke}
%\date{\LARGE\bf Version 1.4 \\ June 25, 1993 }
%\maketitle
%\renewcommand{\Huge}{\huge}
 
%========================================================================
 
\small
\tableofcontents
\normalsize
 
%========================================================================
\chapter{Introduction}
\pagenumbering{arabic} 
This Primer is intended as an introduction to the tools and
facilities available to people wanting to analyse ZEUS data
offline. Wherever possible the reader is referred to more
comprehensive documentation elsewhere and only a brief
summary is included in this Primer. 
This is also the case for information that is expected 
to change frequently and that is stored better in help files than
in a manual. The order of the sections
is somewhat arbitrary since it is not really intended to be
read through from start to finish but rather accessed randomly
via the index. I  have included many examples to make the
PRIMER as practical as possible. Please try them out and tell
me if they don't work.
\noindent
Several people have contributed to this Primer and several
sections  have been  copied directly from other ZEUS documentation.
Some parts have been copied from a similar 
-- very appreciated -- PRIMER written for
the OPAL Collaboration by Steve Lloyd.
 
\noindent
The PostScript and \TeX versions of this file are kept in the 
ZEUS documentation folder ``manuals'' ({\tt /zeus/doc/manuals/zeus\_primer.ps})
on the ZOW cluster. You can print the file by using the {\tt lpr} command.

The version in the ``manuals'' folder will be updated from time to time
with a change of the version number. Version 2.0 
contains only minor changes with respect to version 1.0, that was distributed as 
ZEUS note 93-006.

Suggestions and
improvements are highly welcome.
Periodically or
after major changes,
% a new version will be dispatched to the
% institutes and
printed copies will be made available at DESY.
 
\noindent
% Please send comments, criticisms, suggestions etc to koepke\mbox{@}zow.desy.de.
 
%========================================================================
 
\chapter{The \ind{ZEUS detector}}
 
ZEUS
% ({\bf Z}???-{\bf E}?????? {\bf U}???      for {\bf S}??)
 is
a multipurpose apparatus designed to reconstruct efficiently
events from e p interactions. Full
details of the ZEUS detector can be found in\cite{zeus_detector} and
only a very brief introduction is given here. The essential elements are
a vertex detector, a central track detector plus transition radiation detectors,
and planar drift chambers in the field of a thin magnetic solenoid, an 
electromagnetic and a hadronic calorimeter surrounding the coil over the full
solid angle, a backing calorimeter, barrel and rear muon detectors, and a forward
muon spectrometer. A silicon pad detector is inserted in the backward calorimeter
at a depth of 3 radiation lengths to improve hadron electron separation.
 In addition there are, near the beam line, photon and electron
taggers for the luminosity measurement and detector stations for the observation of
forward scattered protons and neutrons.
The detectors with their mnemonic names are
listed in the following table. The numbers for the radii and z-position of the 
detectors are approximate -- in particular in the case of non-cylindrical elements --
and have only illustrative purpose. 

\footnotesize
\begin{center}
\begin{tabular}{|c|c|l|l|l|}
\hline
Mnemonic & Description & radius [cm] & z [cm] & polar angle [$^\circ$]\\
\hline
VXD & vertex detector & $\approx$[9.9,15.9] & $\approx $[102,-57] & 
$\approx $[8.6,165]\\
CTD & central track detector & $\approx$[16.2,85.0] & $\approx $[105,-100] &
$\approx $ [15,164] \\
TRD & transition radiation detector in FDET & $\approx$[20.7,95.7] & 
147,158,184,194 & $\approx$ [7,26]\\
FTD & planar drift chambers in FDET (forward) & $\approx $[18,108.5] &
$\approx$130,166,203 & $\approx $[7.5,28]\\
RTD & planar drift chambers in RDET (backward)  & $\approx$[22.0,49.5] &
$\approx$ -130 & $\approx$[159,170]\\
SOLENOID & magnetic solenoid & $\approx$[86,111] & $\approx $[+130,-120] &  \\
FCAL & forward calorimeter & $\approx$[10,240] & $\approx $[220,373] &
$\approx $ [2.2,39.9]\\
BCAL & barrel calorimeter  & $\approx $[122,229] & $\approx $[+210,-120] &
$\approx$[36.7,129.1]\\
RCAL & rear calorimeter  & $\approx $[10,240] & $\approx$[-148,-157] & 
$\approx$[128.1,176.5]\\
SRTD & small angle tagger & $\approx $[10,34] & $\approx$[-146] & 
$\approx$[167,176]\\
BAC & backing calorimeter & $\approx$[320,430]  & $\approx $[+590,-390] &
$\approx$ [6,168]\\
RHES & rear hadron electron separator &$\approx$ [11,190]  & $\approx$ -154 & 
$\approx$[128.1,176.5]\\
BMUI & inner barrel muon detector (BMUON) &$\approx 310$ & $\approx $[+450,-330]
& $\approx$[34,135] \\
BMUO & outer barrel muon detector (BMUON) &$\approx 450$ & $\approx $[+640,-460]
& $\approx$[34,133]\\
RMUI & inner rear muon detector (RMUON) & $\approx $ [35,280]-& $\approx$ -320 & 
$\approx$ [139,173]\\
RMUO & outer rear muon detector (RMUON) & $\approx$ [75,430]  & $\approx$ -445 & 
$\approx $[135,170] \\
FMUI & inner layer of forward muon detector &$\approx$ [62,303] & $\approx $ +490 & 
$\approx $ [8,30] \\
FMUON & forward muon spectrometer (drift chambers) & $\approx$ [62,310] &$\approx $
[810,1020] & $\approx$ [5,20] \\
      & {\bf L}imited {\bf S}treamer {\bf T}ube walls & $\approx$ [170,450]
 & $\approx$ [680,750] &
$\approx $[18,36] \\
LUMI & photon and electron taggers for luminosity & 
& $\approx $ -350, -1060 &  \\
LPS & far forward proton spectrometer &  & 24,41,44,63,81,90 m &  \\
FNC & far forward neutron spectrometer & & 105 m & \\
VETO & veto wall & $\approx$[50,400] & $\approx$ -740 &$\approx$ [150,176]  \\
C5 & C5 scintillation counter & $\approx$[3.5,14] & $\approx $ -315 &  \\
\hline
\end{tabular}
\end{center}
\normalsize
Other detectors, such as FHES, BHES, presamplers, new beam pipe calorimeter, are
in prepararation.
The FCAL and BCAL calorimeters consists of an electromagnetic section (EMC) and 
two hadronic sections (HAC1 + HAC2); the rear calorimeter contains one electromagnetic
and one hadronic section plus the hadron electron separator RHES.
%==============================
\begin{figure}[h]
\epsfxsize=15cm
%\centerline{\epsffile[0 0 567 567]{/zeus/doc/pictures/zeusf.ps}}
\centerline{\epsffile[0 0 800 800]{/zeus/doc/pictures/zeusf.ps}}
\caption{\label{fig:detector}The ZEUS Detector as implemented in GEANT}
\end{figure}
 
\begin{figure}[h]
\epsfxsize=25cm
%\centerline{\epsffile[7 18 776 589]{/zeus/doc/pictures/3dzeus.ps}}
\centerline{\epsffile[-100 -100 900 750]{/zeus/doc/pictures/3dzeus.ps}}
\caption{\label{fig:detecto2}The ZEUS Detector as implemented in CAD drawing}
\end{figure} 


%==============================
\section{VXD}\index{ZEUS detector ! VXD}
The decays of short lived particles can be detected in a vertex detector which has
a time-expansion type drift chamber cell structure. The chamber has twelve layers
of sense wires spaced radially by 3~mm with 150~cm wire length. The expected average
position resolution is 50 $\mu$m.
\section{CTD}\index{ZEUS detector ! CTD}
The central track detector consists of a cylindrical jet type drift chamber with an 
outer radius of 85~cm and an overall length of 240~cm. Track position and 
d$E$/d$x$ losses
are measured in nine superlayers each with eight layers of sense wires. Four of the 
superlayers have stereo wires. A resolution of 260~$\mu$m is currentlty 
achived leading to a 
momentum resolution of $\sigma (p_t) / p_t = 0.005~p_t~\oplus~0.016$ 
($p_t$ in GeV/$c$) for a 
magnetic field of 1.43~T.
\section{TRD}\index{ZEUS detector ! TRD}
The transition radiation detector, consisting of four modules, is installed in the 
forward direction. The detector is expected to yield a hadron rejection factor of 30
below 10~GeV/$c$ for the detection of electrons. 
\section{FTD and RTD}\index{ZEUS detector ! FTD}\index{ZEUS detector ! RTD}
Particle tracking at small forward and backward angles to the beam is done with four 
planar drift chambers. Each chamber has three planes rotated by $60^{\circ}$ with 
respect to each other. Each plane has six layers of sense wires with an expected 
position resolution of 120~$\mu$m yielding a momentum resolution of $\sigma (p)/p = 
0.01~p$ at a forward angle of 140~mrad.
\section{SOLENOID}\index{ZEUS detector ! SOLENOID}
The solenoid magnet is superconducting and provides a maximal field of currently
1.43~T.
It has an inner radius of 86~cm, a length of 280~cm and is 0.9 radiation lengths thick.
A compensating solenoid installed in the rear of the detector with a field of 5~T
compensates the influence of the detector solenoid on the beam.
\section{FCAL, BCAL, RCAL}\index{ZEUS detector ! CAL}
The  calorimeter~\cite{heartofzeus}
consists of plates of depleted uranium interleaved with 
plastic scintillator in order to achieve compensation and the best possible energy
resolution for hadrons. The scintillator tiles form towers which are read out via wave
length shifter bars, light guides, and photomultipliers. The calorimeter is segmented
longitudinally into an electromagnetic and one or two hadronic sections. Typical tower
sizes are 5~cm~$\times$~20~cm in the electromagnetic section and 20~cm~$\times$~20~cm
in the hadronic sections. The calorimeter is devided into a forward, a barrel, and a
rear part with 7.5 and 4~ interaction lengths, respectively. The active area in the
forward direction (proton beam direction) starts at about 60~mrad. The solid angle 
coverage corresponds to 99.8~\% in the forward hemisphere and 99.5~\% in the backward
hemisphere.The expected energy resolutions are for electrons $\sigma(E)/E = 0.18/\
\sqrt{E}~\oplus~1\%$ ($E$ in GeV, $\oplus$ stands for addition in quadrature) and for 
hadrons $\sigma(E)/E=0.35/\sqrt{E}~\oplus~2\%$.
\section{SRTD}\index{ZEUS detector ! SRTD}
The {\bf S}mall {\bf R}ear {\bf T}agging {\bf D}evice covers an area of 68$\times 68$
cm$^2$, excluding the RCAL beam pipe hole of 20 cm $\times$ 20 cm. It uses 1 cm wide
scintillator strips in 2 orthogonal planes arranged in 4 quadrants. The SRTD 
improves the position determination of showers close to the beam pipe and allows a 
correction for energy loss in dead material in front of the calorimeter. Finally it 
also improves the rejection of beam gas events when used in the trigger. 
\section{BAC}\index{ZEUS detector ! BAC}
The high resolution calorimeter is surrounded by a backing calorimeter which measures
the energy of late showering particles. The backing calorimeter uses as absorber the
iron plates which form the magnetic yoke. Aluminium tubes operated in proportional mode
are used for read-out. The expected energy resolution is $\sigma(E)/E=1.1/\sqrt{E}$.
\section{HES}\index{ZEUS detector ! HES}
In order to identify electrons within dense jets provisions have been made to insert a 
silicon pad detector as a hadron electron separator in the calorimeter at a depth of 
3~radiation lengths~\cite{hesnote}.
% and at 3 and 6 radiation lengths in the forward calorimeter.
The pad size is 3~cm$\times$~3~cm increasing the calorimeter segmentation by an order
of magnitude. A hadron-electron rejection of $> 15$ can be obtained.
\section{BMUON and RMUON}\index{ZEUS detector ! MUON}
In the barrel and rear detector regions the position and angle of muons are are
measured with limited streamer tube chambers before and behind the magnetized iron
yoke. The momentum resolution is 20~\% for momenta of 20 GeV/$c$.
In the region of the bottom yoke muons are detected by three layers of the backing 
calorimeter chambers which have additional position read-out. The pion (kaon) 
rejection factors are expected to be
1000 (100) at 40~GeV/$c$ in the forward direction, and 700 (350)
at 10~GeV/$c$ in the barrel region.
\section{FMUON}\index{ZEUS detector ! FMUON}
Muons are detected in forward direction in a spectrometer using drift- and limited
streamer tube chambers interspersed between the magnetized iron yoke and magnetized
iron toroids. The momentum resolution for muons up to 100~GeV/$c$ is close to 25\%.
\section{LUMI}\index{ZEUS detector ! LUMI}
Electron and photon detectors are installed some 35 to 108~m downstream in electron
beam direction to measure the luminosity and tag small $Q^2$ and radiative processes.
The electron detector, situated behind a bending magnet which acts as beam 
spectrometer for off beam-momentum electrons, is build of an electromagnetic lead
scintillator sampling calorimeter surrounded by lead shielding. It tags electrons 
scattered under angles of less than 0.5 mrad. 
The photon detector consists of an adjustable carbon filter absorbing
synchroton radiation, an air-filled Cherenkov counter vetoing electrons mainly from 
photon conversions in the carbon filter, and a photon lead scintillator sampling
calorimeter.
\section{LPS}\index{ZEUS detector ! LPS}
A leading proton spectrometer detects very forward produced protons with $x_L > 0.3$,
$x_T < 0.002 ~ x_L$. The spectrometer uses proton beam line magnets and six miniature
high resolution silicon strip detectors installed very close to the beam in stations
at distances between 24~m and 90~m from the interaction point. The detectors have
silicon strips with  a 
readout pitch of 115 $\mu$m and 
each assembly contains detectors that are
 oriented parallel, orthogonal and at an angle of 
45$^\circ$ w.r.t. the magnetic deflection.
\section{FNC}\index{ZEUS detector ! FNC}
A {\bf F}orward {\bf N}eutron {\bf C}alorimeter prototype is installed 105 m away 
from the interaction point in proton direction.The calorimeter is an area of 
20 cm$\times$ 20 cm and has 16 layers of 10 cm thick iron plates interleaved with 
0.5 cm thick scintillator.
\section{VETO}\index{ZEUS detector ! VETO}
The veto wall, situated at the rear side of the detector, 
 is a large iron wall of $\approx 8$ m width and height and 0.9 m 
thickness, covered on both sides with scintillator. In the middle of the counter 
there is a 0.95 m$\times$ 0.95 m rectangular hole. The main purpose of the veto wall
is to shield the detector elements downstream against particles from the beam halo; 
a signal from the veto wall can be used to reject background events.

\section{C5 detector and beam line calorimeter}\index{ZEUS detector ! C5}
The C5 detector, made of four scintillator counters,
surrounds $3\over 4$ of the beampipe in the area of collimator ``C5'' magnet
at the rear side of the RCAL 
detector at a distance of roughly 315~cm from the interaction point.
The signals of this detector can be used to veto background events 
similar to the veto wall for beam halo particles travelling close to the beam line. 
It also serves as a background and timing monitor. 
The beam line calorimeter, installed in the quarter not covered by the C5 
counter, is a sandwich of 8 tungsten plates of 2 radiation length 
thickness and silicon diodes with 4 mm wide strips. The calorimeter is intended
to be used to measure elastic electon proton scattering at small angles, where the
electrons are detected in the beam line calorimeter and the corresponding protons
are detected in the LPS. The beam line calorimeter also monitors beam related 
background.
%========================================================================
%\chapter{Access to ZEUS data}
 
%A summary of the 1992 datataking is given below.
%========================================================================

\chapter{\label{sect:information}\ind{Information}}
 
There are several facilities providing information within ZEUS and beyond.
The UCO ({\bf U}ser {\bf C}onsulting {\bf O}ffice) at the DESY computer center
(open Monday-Thursday 14:00-16:30, Friday 9:30-12:30) can give help and assistance.
There you can get (if you are lucky) copies of manuals and advice.~\footnote{
Up to date CERN manuals (as postscript files) can be obtained via anonymous ftp
from CERN (this should work without registration from any HEP site).
Type {\tt ftp asis01.cern.ch} and login as user {\tt anonymous} and  take your
mail address as your password. Type 
{\tt cd doc/cernlib/ps.dir} and then {\tt dir} 
and you will get a listing of manuals available electronically
in compressed PostScript form. Type, e.g. {\tt binary} and then  
{\tt get hbook.ps.Z} and you will get a copy of the file. If the filename ends
with {\tt .Z} you have to use the command {\tt uncompress} to get the uncompressed
file, if the filename ends with {\tt .gz} you will have to use the command
{\tt unzip}).
Similarily you can get
electronic versions of preprints in the {\tt preprint} directory and
 programs maintained 
by CERN.}

The ZEUS secretariat keeps up-to-date files of the ZEUS directory (e.g. phone numbers 
of the ZEUS collaborators, coordinators etc.), electronic mail addresses,
meeting dates, ZEUS notes and other subjects (see section~\ref{sect:zeusrules}),
some of which are available 
in electronic form (see section~\ref{sect:generalinfo}). {\bf Please help the 
secretariat to keep these files up to date!}

\section{General information sources}
\label{sect:generalinfo}

General HELP facilities exist on IBM and VAX ( type {\tt HELP} ...) as well as on
UNIX (type {\tt man <command\_name>}) if 
you know the name of the command you are interested
in or - more generally - {\tt apropos  <item>}.

Additional ZEUS specific 
information is stored in files on the different computer platforms.
On the DESY IBM , type {\tt Z} and you will get a list of the available information 
on ZEUS. Of particular interest are the list of ZEUS notes ({\tt Z NOTES})
and the names, phones and addresses of ZEUS member ({\tt Z DIR}). As the DESY IBM
has been scaled down, this facility will be moved to a different platform. 

Literature searches can be done on the DESY IBM via SPIRES (or using the information
provided by SLAC in WWW).
Under NEWLIB, type {\tt HEP} and then {\tt sel HEP} if you want to look at high
energy physics preprints and papers. The command 
\begin{verbatim}
    find a G. Wolf and T Observ#
\end{verbatim}
will find a dozen papers of G. Wolf as author and containing the string {\tt Observ}
in the title. 

\section{World Wide Web}

WWW ({\bf W}orld {\bf W}ide {\bf W}eb) which gathers information
from a multitude of information sources. Its usage worldwide has enjoyed exponential 
growth is in fact considered a very successful ``spin-off'' of high energy physics.
WWW is installed on VXDESY, the DESY 
Unix clusters  
and on the ZOW
DEC cluster. In all cases type {\tt www} (or {\tt lynx} to obtain a line mode interface.
On the ZOW cluster and VXDESY,  
the fullscreen interface {\tt mosaic} is implemented. WWW, which started at CERN, 
allows to tap an ever increasing information network. You can get information
from different high energy institutes (e.g. telefone directories!) as well as 
general information about current movies in Hamburg or the 
the climate in Crescent City (CA).  Audiovisual information is also available (sound  
needs special hardware). Note, however, that files containing visual material are 
often large, making the transfer slow and potentially clogging the network.
WWW does not only
widen the access to information dramatically, it also 
reduce duplication of information and lessens the problem of outdated copies.

Some ZEUS specific information has been added to the WWW, such as the ZEUS 
directory listing, the ZEUS documentation folders, program descriptions etc.
Additional ZEUS internal information is only accessible under password 
control (your userid and password on the ZOW cluster). 
%==============================
\begin{figure}[h]
\epsfxsize=15cm
\centerline{\epsffile{zeus_mosaic.ps}}
\caption{\label{fig:mosaic}The ZEUS Mosaic home page}
\end{figure} 
%------------------------------------------------------------------------
 

%........................................................................
 
\section{The NEWS system}
 
Most information of short term interest ($<$~2 weeks) is made available
via the NEWS\index{News} system on VXDESY. News systems are also available
on IBM and UNIX, but they are not used extensively. 

Once logged into VXDESY type {\tt NEWS} to enter the NEWS system. Information
is stored in folders such as {\tt GENERAL}, {\tt ZEUS} or {\tt ZEUS\_LUMI}. You can 
list and select a folder (e.g. ZEUS.GENERAL) by typing:
\begin{verbatim}
        DIR/FOLDERS
        DIR ZEUS.GENERAL 
        SELECT/FOLDER=ZEUS.GENERAL
\end{verbatim}
By pressing return, one may browse through the NEWS items. End by typing
{\tt EXIT}. NEWS items usually expire after a few weeks, however, you can look at 
expires news items by typing {\tt SET ARCHIVE} ({\tt SET CURRENT} gets you back in 
the normal mode). If you want to be notified about news items in certain folders 
at login time, type {\tt SET NOTYFY folder\_name}, where {\tt folder\_name} is the name 
of the folder you are interested in. The news items are automatically put into 
NETNEWS, allowing to read (and add) news also on other systems (try e.g. the 
newreader {\tt dxrn} in the ZOW cluster) or look into the ZEUS news page on WWW. 

\section{\label{sect:mail}\ind{Mail systems}}

On IBM, VAX and ULTRIX(UNIX) the command to read, send or otherwise manipulate mail is
\begin{verbatim}
     mail
\end{verbatim}
There are several other mail programs. Under UNIX, the program {\tt pine}, which 
comes with its own editor {\tt pico} is recommended by DESY. {\tt pine} has been 
written primarily for administrative personal and is, consequently, well structured
and easy to be used. 

Having entered {\tt mail} type help under VMS or UNIX; the NEWLIB help facility
guides shows you all the available commands automatically. Tabel~\ref{tab:mailtab}
presents some of the
commands you have to type under VMS or UNIX to deal with mail.
\begin{table}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
What do you want to do? & VMS & UNIX \\
\hline
list incoming mail & {\tt Directory} & {\tt h} \\
display mail message & {\tt <message\_list>} or {\tt <return>} & {\tt <message\_list>}
 \\
store mail in file & {\tt extract <file\_name>}  & {\tt s <file\_name>} \\
remove mail  & {\tt delete <message\_list>} & {\tt d <message\_list>} \\
undelete mail &       & {\tt u <message\_list>} \\
reply to sender & {\tt reply <message\_number>} & {\tt R <message\_list>}\\
send mail  & {\tt mail } &  {\tt m <user\_list> }\\
leave mail environment & {\tt exit } & {\tt q} \\
\hline
\end{tabular}
\caption{\label{tab:mailtab} Comparison of commands made in mail}
\end{center}
\end{table}
A {\tt message\_list} consists e.g. of mail\_numbers (the integer numbers 
you see after typing the {\tt directory} comand (Vax) or they {\tt h} command under
Unix) or
ranges of mail identifiers (such as 3-5). If omited the 
last mail message is used. A {\tt user\_list}  consists of user names 
or distribution lists separated by spaces.
 Under Unix
distribution lists can be defined in {\tt .sendrc} in your home directory. Other 
mail programs use different files to store this information. 
The syntax for specifying the user at a certain location differs on the various 
computer platforms and depends on the kind of network you would like to use for 
transmitting mail messages (INTERNET, BITNET or DECNET). It is always recommended
to use INTERNET addresses for your mail (BITNET will not be in place much longer).
In the case of INTERNET 
(see also table~\ref{tab:telnet}) you would
choose something like
{\tt lutz\mbox{@}cernvm.cern.ch} if you are sending mail from IBM MVS or UNIX,
{\tt lutz at CERNVM} if you are working on IBM VM and
under VMS you should write {\tt IN\%"lutz\mbox{@}cernvm"}.

On the Vax, mail can be stored in several folders. Normally you have a folder 
coined {\tt MAIL} (which shows all mail you received) and a folder {\tt NEWMAIL}
which exists if you have unread mail.

If you want to send mail, you can do that without having to write a file first.
Type the appropriate command (see table~\ref{tab:mailtab}), answer the questions and
send the mail 
to the destination by typing {\tt control z} on the Vax or {\tt control d} under
UNIX.

You can print mail on VMS directly after setting the print queue to your favorite
printer. Type {\tt SET QUEUE APOLLO\$printer\_name}  once you are in the  mail 
environment ({\tt printer\_name} is the name of your favorite printer). 
If this doesn't work on your system, first create a file 
{\tt mail\_file} from your last read mail message by typing {\tt extract mail\_file}
and print the file afterwards with the {\tt lprint} command.  

%........................................................................
\section{Electronic storage of ZEUS documents}
An increasing number of ZEUS documents is stored 
electronically in directories on 
the ZEUS DEC cluster. At the moment, documents are stored in the following folders:
\begin{indentlist}{4cm}{4.5cm}
\indenttt{/zeus/doc/manuals} manuals, writeups and primers
\indenttt{/zeus/doc/notes} ZEUS notes 
\indenttt{/zeus/doc/papers} ZEUS papers
\indenttt{/zeus/doc/minutes} Minutes of ZEUS physics working groups
\indenttt{/zeus/doc/pictures} Graphics
\indenttt{/zeus/doc/html} Hypertext files (used for WWW)
\end{indentlist}
Each directory contains a file {\tt README} that lists the currently stored documents
in the folder.
Documents can either be stored as ASCII files (just plain typed text), \TeX files
or PostScript files. It is recommended to store manuals 
or ZEUS notes in postscript form 
which allows viewing the files with a PostScript previewer (see
section~\ref{sect:PostScript}) including figures and also allows convient
 printing of the 
file
on PostScript printers.
Papers ideally should be stored as \TeX files {\em and}
PostScript files: this allows the user to print and preview the files but also to 
speed up writing a paper by copying segments 
such as the detector description. Minutes may well be written in plain ASCII so that
one can e.g. search for strings (``keywords'') in all files.

A simple interface script 
\begin{verbatim}
       zeusdoc [-vtsp]
\end{verbatim}
has been written with which one can {\em view} ({\tt -v}), {\em store}({\tt -s}),
{\em print}({\tt -p}) and ``{\em type''}({\tt -t}) documents in the various folders.
The script is installed on the ZOW cluster and VXDESY (no PostScript previewing yet).
If you want to store a document you will be asked to give
a one-line description of the 
document which will be automatically included in the {\tt README} file.
On the DEC cluster, option {\tt -v} invokes the ghostview PostScript
 previewer; press the {\tt file} 
button and choose {\tt open} to select a PostScript file to display. It may take a 
while to open a larger document (the first page is displayed automatically).
You can select a page by pointing to the page number
and pressing the middle mouse. You can selectively print pages by first marking pages
(press page button) and then printing. Much better than wasting paper!

 
 
\subsection{ZEUS notes}
 
ZEUS Notes\index{ZEUS Notes}
are notes which provide background to ZEUS papers,
status reports on detectors and analyses and any other material that 
should be made public. Primers and manuals should be kept up-to-date with software
releases and thus fit better in the ``manuals'' folder. 
The naming
convention for electronically stored ZEUS Note is {\tt ZEUS-yy-nnn.type} with 
{\tt type = tex } or {\tt ps}. 
 
%........................................................................
 

 
\subsection{ZEUS papers}
 
ZEUS Papers\index{Papers}
are all papers which have DESY preprint numbers and which
have the whole collaboration as authors.
The naming
convention for electronically stored ZEUS papers is {\tt DESY-yy-nnn.type} with 
{\tt type = tex } and {\tt ps}. Ideally, papers should be stored both as \TeX\
and PostScript files including figures. Alternatively the figures can be stored
separately as {\tt DESY-yy-nnn\_m.ps}, where {\tt m} denotes the figure number.
 
\noindent
 
%........................................................................
 

 
%........................................................................
 
\subsection{ZEUS minutes}
 
It has been decided to gather all minutes of ZEUS Analysis working groups\index{Minutes}.
The naming
convention for electronically stored ZEUS Minutes is {\tt MMMM-yy-nnn.type} with 
{\tt type = txt } preferentially. {\tt MMMM} is a 4-letter abreviation for the 
working group (e.g. {\tt OFFL}). 
 
%........................................................................
 
\subsection{Writeups, manuals and primers}
 
These are documents on software used by ZEUS that should be
updated with each release of the
software (labeled by version number).

\subsection{\ind{Pictures}}

Graphics such as ``typical'' event displays or detector views can be stored
in form of PostScript files. 

\subsection{\ind{Hypertext}}

World Wide Web works with so called hypertext documents. Hypertext is text that is 
marked up with tags that allow references to other documents.  
 
\section{\ind{Run information}}
\label{sect:runinfo}
Information on runs (quality, luminosity, tapes etc.) can be obtained 
on VXDESY, DESY IBM, zow cluster and WWW. 

On the DESY IBM a run-information file is automatically 
created during data-taking which 
lists the tapes associated with given runs and some additional information.
Type
\begin{verbatim}
    RUNINFO
\end{verbatim}
and choose the information you want~\cite{copydat} .

A comprehensive online database is under 
preparation.
 
 
%------------------------------------------------------------------------
 
%========================================================================
 
\chapter{\ind{Computers} used for ZEUS analysis}
 
Several computer systems are used for ZEUS analysis. A brief
description of the ZEUS environment and code organization on
each system is given below. The computers can be accessed via TCP/IP; some addresses
are given in table~\ref{tab:telnet}. A much more complete list for TCP/IP addresses
can be obtained by typing {\tt Z INTERNET} on the DESY IBM.

\begin{table}
\begin{center}              
\begin{tabular}{|l|r|r|r|} 
\hline                       
Name & operating system & TCP/IP address &  Bitnet address (obsolete) \\  
\hline
DESY-IBM  & MVS/NEWLIB & dsyibm.desy.de (mvs)  & DHHDESY3.BITNET \\
DESY-VAX  & VMS & vxdesy.desy.de & DESYVAX.BITNET \\
ONLINE VAX-cluster & VMS & uxzeus.desy.de &  \\
ZEUS DEC cluster & ULTRIX & zow01.desy.de (.. zow09)  & zow01 (.. zow09) \\
\hline
\end{tabular}
\caption{\label{tab:telnet}TCPIP and Bitnet addresses of DESY Computers}
\end{center}
\end{table}


 
%------------------------------------------------------------------------
 
\section{DESY IBM}\index{Computers ! DESY IBM}
The DESY computer center is equipped with an IBM ES 9000/720 VF with 120 Mips
computing power\cite{desy_center}. The system will scaled down and will not
be available for analysis beyond 1994.
 The operating system is MVS-ESA. NEWLIB has been developed
at DESY to facilitate interactive operations. While it is easy under NEWLIB 
to create, edit, compile, etc. data sets, 
the NEWLIB system is rarely used outside DESY 
(contrary to VM, VMS and UNIX). A DESY Computer Center Primer \cite{first_days}
and an 
introduction to NEWLIB\cite{NEWLIB_primer} 
can be obtained at the DESY computer center.
A disk capacity of 316 GB is available, as well as 4 {\bf A}utomatic {\bf C}artridge
{\bf S}ystems (ACS) for 24000 cartridges as well as other cartridge and tape
readers.

The ACS of the IBM is used by ZEUS to store data tapes as it is at present the most 
effective medium providing easy access to large amounts of data. Documentation stored
on the IBM (type {\tt Z} and examine list) is described in
section~\ref{sect:information}.
   

%........................................................................
 
\section{VXDESY and VAXstations}\index{Computers!VXDESY and VAXstations}
VXDESY is centrally maintained by the DESY computer center and has been converted
to a cluster containing alpha computers running the VMS operating system. 
While VXDESY is popular, computing resources
are limited, in particular disk space. It is typically used for
testing programs, generating Monte Carlo ``4-vectors'', serving news or mail. 
VAX stations are also used in the data acquisition and in the online Vax 
development cluster. Several good introductions to the VMS operating exist
(check out your library); a ``Getting Started on a VAX'' primer has been written 
by K. Gather~\cite{VAXprimer}.

\subsection{Choice of editor}\index{Editor!on VAX}
Many editors  exist on  the VAX such as {\tt EDIT/EDT} and {\tt EDIT/TPU}.
The editor {\tt \ind{EDFOR}} is a computer language sensitive editor developed by 
the D0 experiment and widely used by the LEP experiments. The editor can be 
customized to the computing environment of a high energy physics experiment. 
A manual~\cite{editor_eve} can be found in the ZEUS document source (see
section~\ref{sect:information}). Another language sensitive editor is {\tt LSE}, which
again is based on the {\tt TPU} editor. On VXDESY, the Unix EMACS editor is also 
available (insert the line {\tt  \@GNU\_ROOT:[000000]GNU\_LOGIN} in your {\tt
LOGIN.COM}). 

\subsection{Common VMS commands}\index{Commands!on VMS}
\begin{indentlist}{5.00cm}{5.25cm}
\indenttt{copy} makes a copy of a file
\indenttt{delete} deletes a file
\indenttt{differences} compares files, flagging any differences
\indenttt{dir}    list directory (option {\tt /full} gives most information)
\indenttt{help}   displays infomration about the commands on your system
\indenttt{logout} logs out of the system
\indenttt{mail}   access to mail utility
\indenttt{news}   access to VMS news
\indenttt{purge}  eliminates all but the most recent versions of each file in
your working directory
\indenttt{rename} changes the name of a file
\indenttt{set password} changes the users password
\indenttt{set default} changes the default directory to another directory
\indenttt{show default} displays the current default directory
\indenttt{show quota}  displays the disk quota currently authorized and currently used
\indenttt{show symbol/all/global} shows all defined symbols
\indenttt{show time} displays the current date and time
\indenttt{show users} displays information about the users currently logged into the 
system
\indenttt{type}   type contents of file on screen 

\end{indentlist}

\subsection{Running a FORTRAN program}
A fortran program (e.g. {\tt TEST.FOR}) is compiled by typing 
\begin{verbatim}
     FORTRAN TEST
\end{verbatim}
Object code will be produced ({\tt TEST.OBJ}). 
For a list of the available compiler options type {\tt help fortran}.
In order to run the program it has 
first to be linked by typing {\tt LINK TEST}. This will produce an executable file
({\tt TEST.EXE}) which you can execute by typing {\tt RUN TEST}.
If you want to link libraries, such as the CERN packlib and kernlib libraries to fill
some HBOOK histograms, you 
will have to include the libraries in the link step by typing something like
\footnotesize
\begin{verbatim}
     LINK test,cern_root:[lib]packlib/library,cern_root:[lib]kernlib/library
\end{verbatim}
\normalsize
Again, execute the program by typing {\tt RUN TEST}, if {\tt TEST} is the name of 
your fortran file.

\subsection{Code organization}\index{Code organization!on  VAX}

Type {\tt info} on VXDESY and you will obtain the current information on where to find 
offline code. 

% Examples for running e.g. EAZE can be found in 
% {\tt ZREXAM:[EAZE]}; documentation is stored in {\tt ZRDOCU:}.
%........................................................................

\section{UNIX}\index{Computers!UNIX}
Several UNIX clusters -- based on workstations from different vendors -- have been 
established. The newest software is always installed on the ZOW DEC station cluster;
other clusters have access to this information via
the {\bf N}etwork {\bf F}ile {\bf S}ystem  (NFS). Before describing the 
DEC station cluster in more detail, we give some information about UNIX 
systems in general. Hints on using X-terminals and UNIX at DESY can be found 
in the DESY Computing Newsletter No.4~\cite{DESYnews}. 

\subsection{Choice of editor}\index{Editor!on UNIX}

A variety of editors exist that can be used with UNIX workstations, none of which 
have the ease of use and ``look and feel'' of , say, a Macintosh. Some editors are 
vendor dependent and will not be discussed here because a different workstation
standard may be used in the future.

Most users have chosen 
\ind{GNU {\tt emacs}}, a standard -- non commercial -- full screen editor.
A two-page reference card can be obtained from the DESY 
computer center. The editor is driven by control sequences and not from
the keypad. The mouse may be used to place the cursor --  but not to select a region
-- by dragging. This is overcome by \ind{GNU {\tt epoch}}
 which is an X11 interface to emacs.
Start emacs (epoch) by typing {\tt emacs} ({\tt epoch}). Further control is given
by control sequences, which are obtained by pressing the control key + another key.
Other control sequences use the ``META'' key, which is implemented on VT100 like 
terminals as the ``compose character'' key. Some of the manipulations that can be
done using control sequences are listed below.

\begin{indentlist}{5.0cm}{5.25cm}
\indenttt{control h t} - tutorial
\indenttt{control x control f} - read in a file 
\indenttt{control x control s} - save file
\indenttt{control x control c} - exit emacs definitely
\indenttt{control x u } - undo a change
\indenttt{META <} - go to beginning of file
\indenttt{META >} - go to end of file 
\indenttt{control w} - deletes marked region (also valid in {\tt xedit} editor)
\indenttt{control d} - delete character at current cursor position (also valid 
in {\tt xedit} editor)
\indenttt{control s} - search forward (also valid in {\tt xedit} editor)
\indenttt{control r} - search backword (also valid in {\tt xedit} editor)
\indenttt{META \%} - interactively replace a text string
\indenttt{META \$} - check spelling of current word
\end{indentlist}
 
%Unfortunately the 
%editor makes lot of use of control and escape sequences and is not mouse driven.


{\tt XEDIT} is a simple  mouse and control character driven
editor which is part of the X-windows library; invoke it by typing \ind{{\tt xedit}}.
It has the advantage that it can be
used on any system running X-windows
and can be recommended for the casual user. 
The editor shows a text window and a scratch pad. 
Any text in a window can be
copied into the text editor by marking the text to be copied. This is done by
pressing the left-most mouse bottom and releasing it when the selection has been made
(selects words by clicking twice and lines by 
clicking three times). The selected text is automatically stored in the ``cut buffer''
and can be pasted by pressing the middle mouse button. The text will then appear
following the current cursor position.

Further manipulation of the text can be done by using control sequences, some of
which are listed above.
Note that -- for all of these operations -- the cursor has to be in the text window.

A more complete full screen editor is {\tt nedit} which has been recommended by 
DESY and CERN. It is fully graphics oriented, has a good search facility and 
supports e.g. spell checking.
 
\subsection{Useful UNIX commands}\index{UNIX commands!on DEC stations}
\index{UNIX!useful commands}
 
\begin{indentlist}{5.00cm}{5.25cm}
\indenttt{.}      synonymous to the current working directory
\indenttt{..}     synonymous to the parent of the current working directory
\indenttt{apropos string}      Finds help about string
                          (also  man -k)
\indenttt{$\sim $}      in C-shell: home directory 
\indenttt{cat}    Concatenates files to standard output. In the simplest case it
                  prints one file on the terminal.                 
\indenttt{cd directory-path}   Changes to given directory
                              (e.g. /zeus/pro/lib)
\indenttt{chmod}  Change protection of file/directory
\indenttt{cp file1 file2}      Copies file1 to file2
\indenttt{df}                Shows the disk usage of disks in Kbytes
                            (look mainly at /zow lines)
\indenttt{du}                Shows disk space occupied by user per directory (option 
                              {\tt -s} gives summary only)
\indenttt{finger user\mbox{@}location} information about user (also on other computers!)
                                      ; location is TCPIP address such as VXDESY
\indenttt{grep 'string' file}  Find string in file (case sensitive!) 
\indenttt{ls (-l) (file)}  List of files (-l = long listing, -a = all
                            files including hidden ones)
\indenttt{logout}                   Logout
\indenttt{lpstat}                   Shows status of printer
\indenttt{man command}              Full syntax of command
\indenttt{mkdir directory}          Creates a new directory
\indenttt{mv file1 file2}    Renames file1 into file2 (if file2 exists
                            it is overwritten)
\indenttt{pwd}                      Shows which directory you are in
\indenttt{rm file1}                 Removes (erases) file1
\indenttt{tail file}                Displays the tail (end) of file
\indenttt{w}                        Displays logged in users
\indenttt{yppasswd}   Changes the login password (interactively only)
\end{indentlist}

\section{DECstation cluster}\index{Computers!DECstation cluster}
The workstations connected to the cluster are used to 
\begin{itemize}
\item develop, test and administer offline or analysis programs,
\item to analyse data including histogramming and n-tuple evaluation (n-tuples can be
produced from data stored on local disks or transferred to the workstation from other
computers);
\item to run the event displays;
\item to produce MC events with spare CPU-time.
\end{itemize}
The workstations used are Digital Equipment DECstation 5000 types 120, 125, 200 and 
240; in addition to the workstations, Tektronix XC-terminals of type XP20 are used as
graphics displays (up to three can share a workstation). At present approximately 45
workstations and a similar number of X-stations take part in the cluster.
 
\subsection{Running a FORTRAN program}
The name, syntax, and options of fortran compilers vary from vendor to vendor.
On DEC machines the {\tt f77} compiler is used; for more information on the options
type {\tt man f77}. If you run {\tt zephyr\_setup} in your {\tt .login} file, the 
ZEUS standard compiler options will be set in the environmental variable 
{\tt \$f77flags}.
For the DEC fortran compiler, fortran files have to have filetype
{\tt .f}, {\tt .for} or {\tt .FOR}. If you have a fortran program {\tt test.f}, the 
command
\begin{verbatim}
         f77 testf.f
\end{verbatim}
will compile the program and produce an executable called {\tt a.out}, which you can
run by simply typing {\tt a.out}.

If you want to include routines from libraries, in order, e.g., to run the hbook
example program in section~\ref{sect:hbook}, you will have to issue the command 
\begin{verbatim}
         f77 -o run_test testf.f /cern/pro/lib/libpacklib.a
\end{verbatim}
(the location of the appropriate CERN library may change).
In the above case the {\tt -o} option was used to specify the name of the executable
(in this case {\tt run\_test}). 
\subsection{Code organization}\index{Code organization!on  DECstation}
ZEUS code is stored in the
{\tt /zeus/pro} directory.  Files without a version number are links to the 
current program versions.
%The {\tt pro} subdirectory
%contains the standard setup with full version history; obsolete or experimental 
%versions of code can be found in the subdirectories
% {\tt old} and {\tt new}, but may not 
%always be there.
 All documentation goes into the {\tt /zeus/doc} directory, pointers 
to data held on the system are located in {\tt /zeus/data}. Geometry, calibration etc.
can be found in {\tt /zeus/gaf}.

In the program directories 
all files are kept 
under control of \ind{CMZ}. 
Some of the files or directories may be links. Here is a
picture of most of the subdirectories in the  /{\tt /zeus/pro} tree:

\footnotesize
\begin{verbatim}
                        /zeus/pro
                               |
---------------------------------------------------------------------
 |    |      |     |     |     |    |      |      |     |    |      |     
car  doc  export  gaf  field  lib  exe  source  kuip  util  vsn  "program" 
                                                                    |    
                                                                   exam    
\end{verbatim}\normalsize
The directories contain:
\begin{indentlist}{5cm}{5.25cm}
\indenttt{/zeus/pro/car} - PATCHY compatible CARD image file of latest versions
\indenttt{/zeus/pro/doc} - documentation
\indenttt{/zeus/pro/export} - full CARD image files need for CMZ installation
\indenttt{/zeus/pro/gaf} - geometry description, calibration and other
constants
\indenttt{/zeus/pro/field} - magnetic field maps
\indenttt{/zeus/pro/lib} - object module libraries (compiled program)
\indenttt{/zeus/pro/exe} - executable program (compiled and linked programs)
\indenttt{/zeus/pro/source} - source code in CMZ libraries
\indenttt{/zeus/pro/kuip} - macros (e.g. startup.kumac)
\indenttt{/zeus/pro/util} - general utility programs
\indenttt{/zeus/pro/"program"} - scripts to build the programs 
MOZART (Monte Carlo program),
ZEPHYR (reconstruction program), EAZE (ZEUS analysis shell), ZEV (LAZE) etc.
\indenttt{/zeus/pro/"program"/exam} - example steering cards / command files
\indenttt{/zeus/pro/vsn} - lists of programs belonging to same version 
\end{indentlist}

\ind{Version numbers} have been introduced for the files stored in the directory above.
The version numbers appear in the name of the file or script (e.g.
{\tt mozart\_control\_30302.cards}).
Files without version numbers in their names point
(link) to the current production versions. More details can be found
in {\tt /zeus/pro/doc/RELEASE\_NOTE}
where also the preparation of the environment for running ZEUS software is
discussed.
\subsection{Data analyses with EAZE}\index{Analysis with EASE!on DEC cluster}
You may  use code under
PATCHY as described in~\cite{RELEASEold}
or you may work under CMZ 
as described in~\cite{RELEASEnew}.
A summary of the latter procedure is repeated below.

To prepare your environment for running the ZEUS offline software you should 
(done only once):
\begin{itemize}
\item install a {\tt .cmzlogon.kumac} file in your top directory
\begin{verbatim}
           cp /zeus/pro/kuip/.cmzlogon.kumac ~/.cmzlogon.kumac
\end{verbatim} 
\item create a root directory that will contain your software; e.g.
\begin{verbatim}
           mkdir -p ~/analysis 
\end{verbatim}
\item and create the {\tt ~/analysis/data} and {\tt ~/analysis/tmp} 
directories (in ``real'' or by link).
Until disk space is available on ZARAH, data files are kept on the disks of several
DECstations (pool). 
On the DECstation
cluster the (output)
datasets and temporary files should be kept on the local disk of the station 
you are working on to minimize ``traffic'' on the network. 
Therefore one should decide which DECstation to run on and arrange with the system
manager for a suitable directory to be created on the local disk
of that station. A suitable disk
directory e.g. for DECstation zow23  at DESY would be
\begin{verbatim}
    /data23a/username/data
    /data23a/username/tmp
\end{verbatim}
A link should then be created between your dummy directory and the real one 
(to do this one has to be logged in whatever machine you choose, in this case zow23)
\begin{verbatim}
    ln -s /data23a/username/data ~/analysis/data
    ln -s /data23a/username/tmp  ~/analysis/tmp
\end{verbatim}
In this way the {\tt tmp}
 files do not clog up the users directory and the network traffic
due to data transfer is kept to a minimum.
\end{itemize}
In your {\tt .login} file the following statements should be implemented (if you have 
chosen {\tt ~/analysis} as the directory to contain your software):
\begin{verbatim}
    setenv ZOF_ROOT /zeus/pro
    setenv MY_ROOT ~/analysis
    source $ZOF_ROOT/util/zephyr_setup  
\end{verbatim}
This will guarantee an uniform `environment' in which to use and develop ZEUS code.

The necessary directories and example files to run EAZE 
can be created by running the following script in directory {\tt  \$MY\_ROOT} 
\begin{verbatim}
    cd ~/$MY_ROOT 
    $ZOF_ROOT/util/user_setup eaze
\end{verbatim}
(The same shell can also be used for
setting up  mozart, zgana, zephyr, zdis, laze, gaze, maze or
`all'). 

If you already have created an eaze program (such as {\tt physics.car})
you should copy it into the {\tt \$MY\_ROOT} directory and enter CMZ 
(the prompts are generated by CMZ, don't type them !):
\begin{verbatim}
CMZ

zeus [1] make physics
physics [2] ytoc physics.car
\end{verbatim}
(Later, when you want to change 
your {\tt physics.cmz} file, type {\tt file physics} and 
the file {\tt physics.cmz} will be loaded in CMZ).
You can e.g. edit the file  {\tt zuanal} by typing:
\begin{verbatim}
physics [3] cd ezuser
physics/ezuser [4] edit zuanal
\end{verbatim}

CMZ starts the local editor (default emacs) and you can modify the zuanal file.
In general you will also have to modify the file {\tt eazelib.kumac} to include 
other sequences or - as in this case - to change the program name to 
{\tt physics}.~\footnote{the {\tt eazelib.kumac} does what a {\tt cradle}
in PATCHY plus the compilation of the user subroutines.}
To compile your job and update the eaze library you then run {\tt easelib.kumac}: 
\begin{verbatim}
physics/ezuser [5]  cd $kumacs
physics/ezuser [6]  exec eazelib
\end{verbatim}
Now you can leave the CMZ environment.
There are currently 
three other files which you will -- in general -- have to edit before
running your job; examples are generated by the {\tt user\_setup} utility (see
above) and are called 
\begin{indentlist}{4.00cm}{4.25cm}
\indenttt{eaze\_lnk}   Links the eaze program from the users library and the ZEUS
offline library, employing makefile utility (least likely to change)
\indenttt{eaze\_run}  Runs the standard installations of eaze (points to the input,
output, and run\_control file)
\indenttt{eaze\_control.cards} ZRIO control cards
\end{indentlist}
 
With the example given above your analysis program is then linked and run by typing
\begin{verbatim}
    eaze_lnk
    eaze_run
\end{verbatim}
You don't have to exit CMZ before the linking step; instead you can issue the commands
from the 
CMZ  command line by typing {\tt shell} before the command.

To run eaze interactively type
\begin{verbatim}
    nice +n executable_name >& MY_ROOT/tmp/progname_run.log
\end{verbatim}
(Type an additional {\tt \&} at 
the end of the statement to run the job in the background).
Here {\tt n} is a priority which may vary from 0 (highest) to 20 (lowest).
Use `{\tt  renice}' to lower
 priorities of programs already running, `{\tt at}' to delay execution 
to a set time.

\section{ZARAH}\index{Computers!ZARAH batch server}
 ZARAH is the central facility to analyse the
DST and to produce micro-DSTs or n-tuples for individual physics
analyses. Most analyses are now sucessfully down on this system.
While interactive physics analysis, 
histogramming,
event display, and program development is based on distributed
workstations and X-terminals, there is little, if any, need for interactive 
work on ZARAH.  Jobs are prepared on the workstations, submitted to
ZARAH and scheduled for running using a batch facility. The job output
together with the micro-DSTs 
or n-tuple produced are sent back to the local disk of the
workstation.

The most important commands to communicate with ZARAH, 
implemented on the ZOW cluster, are:
\begin{indentlist}{7.00cm}{7.25cm}
\indenttt{jobinfo [{\it options}]}    displays information about queues  on ZARAH
\indenttt{jobq [{\it options}]} displays information on jobs running on ZARAH
\indenttt{jobls [{\it options}] [{\it jobid}]} lists spool area on ZARAH
\indenttt{jobget [{\it options}] {\it jobid} -f {\it files}} 
copies files from spool area on ZARAH
\indenttt{jobkill [{\it options}] {\it jobid}} terminates job running on ZARAH
\indenttt{jobpurge [{\it options}] {\it jobid}} remove job output from spool area
on ZARAH
\indenttt{jobsub [{\it options}] {\it script} -f {\it files}}
submits job TO ZARAH
\end{indentlist}
The exact syntax and the available option can be found out by using the man 
facility (e.g. type 
{\tt man jobsub}. Additional information can be found in directory 
{\tt /zeus/doc/zarah}.

Suppose you have  customized the following script called {\tt myscript}:
\footnotesize\begin{verbatim}
#!/bin/sh
################################################################
############ Sample job script #################################
################################################################
# {show date:}
date
################################################################
# {Set up some variables:}
################################################################
# {zeus root directory:}
ZOF_ROOT="/zeus/pro"
# {name of the executable program you want to build on zarah:}
PROGRAM="test"
# {any fortran files you want to have included in the loading:}
# FFILES="fortran_files.f"
# {any cards files you would like to process (can be one or more):}
CARFILES="anything.car $PROGRAM.car"
# {event types you want to process:}
EVENT_TYPE="lox dis"
# {names of input files you want to read in}
INPUT_DATA="/zeus/zed.rep/rdst.run4064.z
           /zeus/zed.rep/rdst/run4066.z
           /zeus/zed.rep/rdst.run4073.z"
# {name of output file}
OUTPUT_DATA "secret_discovery.fz"
###############################################################
# {Concatenate CAR files (not necessary if only one CAR file)}
# (The +PATCH statement is necessary! For +USE you have to}
# take the name of the PATCH file containing the user routines}
# {zuinit etc. in in $PROGRAM.car}
###############################################################
cat - $CARFILES > temp.car << [EOF]
+PATCH, *TEMP.
+USE,P=EZCMN.
+USE,P=PHANCMD.
+USE,P=EZUSER,T=EXE.
[EOF]
###############################################################
# {build makefile and run make to build executables}
###############################################################
/zeus/bin/zmkmf
make PROGRAM=$PROGRAM FFILES=$FFILES CARFILES=temp.car
###############################################################
# {now include the zrio control cards}
cat >> fort.7 << [EOF]
C
C {Time limit}                        Default = 20 sec
ZRLIMIT-TLFT 120.
C
C ======================O/P File Specification=========================
C {for FZ files use the following input options:}
C ZeusIO-IOPT      DRIVER=FZ,FILFOR=EXCH
C {for event list files use:}
ZeusIO-IOPT    DRIVER=IE,ZED
C {you can then define classes of events you want to read in}
ZeusIO-ZCLASS  $EVENT_TYPE
C {and you can define the tables that are in the input (e.g. RDST)}
ZeusIO-DEFDFL  TrgDFL  = LMEB O1SETU O1SUBT O1RCDT O1EVNT O2DEC TLTEVT
               RecDFL  = PHASE1 PHASE2
               McDFL   = FMCEvent CcGHit
               RDSTDFL = TrgDFL RecDFL McDFL
ZeusIO-IDFL    HEAD,MCTRUTH,RDSTDFL
C {then say which data file you want to read in} 
ZeusIO-INFI  $INPUT_DATA
C
C ======================O/P File Specification=========================
C {if you want to write an output file you have to define the structure:}
C ZeusIO-OUFI      $OUTPUT_DATA
C ZeusIO-ODFL      RDSTDFL
C ZeusIO-OOPT      MEDIUM=DISK,DRIVER=FZ,FILFOR=EXCH
C
C {then say which data file you want} 
ZeusIO-INFI  $INPUT_DATA
STOP
[EOF]
#######################################################################
# {Install symbolic links in current directory}
#######################################################################
rm -f gaf;           ln -s $ZOF_ROOT/gaf gaf
rm -f CABLES_A.GAF;  ln -s $ZOF_ROOT/gaf/cnd/CABLES_A.GAF CABLES_A.GAF
#######################################################################
# {run program now!}
#######################################################################
time $PROGRAM
#
# {print date and time at the end of job}
date
\end{verbatim}
\normalsize
You can submit the script {\tt myscript} to the queue X (shortest jobs)
by issuing the command 
\begin{verbatim}
         jobsub -q X myscript 
\end{verbatim}
You can then find out about the {\tt jobid}, job-state, CPU time etc. by
typing {\tt jobq}. If you have to kill a job you can then type {\tt jobkill jobid};
where {\tt jobid} is the job identification number returned by {\tt jobq}.
Is the job finished, {\tt jobls jobid} will list the files remaining in the spool area, 
which can then be transferred to your workstation by typing 
\begin{verbatim}
         jobget jobid -f output_file > LOG
\end{verbatim}
{\tt output\_file} may be an n-tuple or any file you have produced in the job
(listed by {\tt jobls}).


%------------------------------------------------------------------------
\section{\label{sect:print}\ind{Printing files}}
\label{print} 
A guide ``Printing at DESY''\cite{DESY-USG9001} is available at the DESY computer
center. It describes printing from central VAX, IBM, Macintosh and APOLLO.
The following table lists the print commands on various computers.
\begin{table}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
System & help for print command & current list of printers \\
\hline
IBM (NEWLIB) & HELP PRINT or PLOT & HELP DEST \\
VXDESY (on IBM) & HELP LPRINT & - \\
VXDSYA (Apple LW)  & HELP LWPRINT & - \\
MacII &  & see CHOOSER \\
UNIX (DEC) & man lpr & lpstat -p \\
\hline
\end{tabular}
\end{center}
\caption{\label{tab:printing} How to print on different systems}
\end{table}
When printing from the IBM try destination LI1, which prints
 double-sided with reasonable resolution. ZEUS has two high resolution
\ind{postscript printers} of type
 HP laser jet IIISi in room 1b 116 with names ZEUSPS0 and ZEUSPS4.
In order to print on this printers type: 
\begin{verbatim}
    IBM:      PRINT filename dest zeusps0  (for ASCII files)
    IBM:      PLOT  filename dest zeusps0  (for postscript files) 
    VAX:      LPRINT filename dest=zeusps0 [type=post]
   UNIX:      lpr -Pzeusps0    
\end{verbatim}
At DESY the UNIX {\tt lpr} command can also be used with option {\tt -d}
which allows to print {\tt dvi} files directly.
ZEUSPS0 is the default printer on the DECstation cluster (to change type
{\tt setenv PRINTER} {\tt your\_favorite\_printer} and the 
environmental variable {\tt \$PRINTER} will be changed).
 The options in brackets have to be typed in order 
to print postscript files. 

You can print the contents of an X-window screen under UNIX using the 
the following command sequence:
\begin{verbatim}
    xwd | xpr -device ps | lpr
\end{verbatim}
A cross hair symbol will
appear and you should click the left mouse button when the cross hair is over the 
window  you would like to print (the window should be popped up).

\section{Logging into other computers}

The {\tt telnet} command is implemented on the central IBM and Vax as well as on the
ZOW  Dec-cluster. Just type 
\begin{verbatim}
      telnet location
\end{verbatim}
where {\tt location} is the telnet address of the computer you want to connect 
to (see table~\ref{tab:telnet}). From a Unix  station you can also use {\tt rlogin},
which works by a different
method but with a similar result. In order to connect from a X-window capable 
station to an IBM it is best to type {\tt x3270 location} (e.g. {\tt x3270 cernvm});
this command will emulate an IBM 3270 terminal.

\section{Transferring files between computers}
\index{Transferring files}
Files can be transferred between computers using different protocols and media.
Plain text files (e.g. ASCII) can be easily transmitted using 
BITNET, DECNET or FTP. DECNET works only between DEC computers and BITNET --
which allows only 80 characters per line --
is slow, so FTP is the method of choice. FTP is an interactive program and you 
normally will have to have a userid and a password on the system you want to 
connect too. In generally you will just type
\begin{verbatim}
         ftp  destination
\end{verbatim}
where {\tt destination} is the TCPIP address of the computer you would like to 
connect to (see table~\ref{tab:telnet}). The program will then ask you to give your
userid and password.  

Transporting binary files is more complicated, in particular since the method 
varies from computer platform to computer platform. Again ftp can be used.
In the appendix details are given both for transmitting text and binary files.

Some more details on transfering files can be found in a note by M. Kasemann and 
T. Poser\cite{FTPzeus}. 

In most cases ZEUS data will have to be transfered from IBM to the UNIX cluster. 
This is best done as described in
ZEUS note 92-66 ``Copying Data to 
Workstations''~\cite{copydat} using ULTRANET. Users who want to store data files
should be aware that the user areas should not be used for data storage.
Instead ZEUS has introduced ``pools'' of disk space which are available for such 
a purpose. Pools may span several physical disks; temporary pools  will continously be 
purged so that the pool is never more than 80\% full.
You can obtain e.g. 20 MB of disk space in the public {\tt scratch1} pool by 
typing 
\begin{verbatim}
  sfget -s 20 filename.fz
\end{verbatim}
on your UNIX system. The ``pool manager'' will then return to you the name of 
the allocated file.

For transfering files you can use the {\tt fromcass} utility which will also 
allocate the necessary space in the disk pool.
Just type 
\begin{verbatim}
   fromcass
\end{verbatim}
and the program will ask about your userid and password on the IBM, the size
and name of  
the dataset you want to copy, and the destination directory on the Dec cluster.
 

%========================================================================
 
\chapter{Standard ZEUS programs}
 
%
%------------------------------------------------------------------------

ZEUS libraries are identified by characters describing their purpose.
\begin{indentlist}{2.0cm}{2.25cm}
\indenttt{mo} -  mozart (MC)~\cite{blue_book}
\indenttt{zr} -  zrecon (central services, e.g I/O)
\indenttt{cc} -  ccrecon (calorimeter)~\cite{ZCAL}
\indenttt{he} -  hesrecon (hadron-electron separator)~\cite{ZHES}
\indenttt{gl} -  gltrk (global tracking with external detectors)
\indenttt{lm} -  lmrecom  (luminosity reconstruction)
\indenttt{lp} -  lprecon  (leading proton spectrometer reconstruction)
\indenttt{mb} -  mbrecon (barrel muon chambers)~\cite{ZMB} 
\indenttt{mf} -  mfrecon (forward muon chambers)
\indenttt{o1} -  o1recon (first level trigger)
\indenttt{vc} -  vcrecon (central tracking)
\indenttt{vt} -  vtrecon (central tracking)~\cite{ZVXFIT}
\indenttt{tc} -  tcrecon (central tracking)
\indenttt{tf} -  tfrecon (forward tracking)
\indenttt{tg} -  tgrecon (global tracking among tracking chambers)
\indenttt{xx} -  xxrecon (backing calorimeter reconstruction)~\cite{bacrec}
\vskip 12pt
\indenttt{ge} -  geane (GEANT  extrapolation)
\indenttt{gg} -  geang (GEANT geometry)
\indenttt{gh} -  geanh (GEANT hadronic interactions)
\indenttt{gt} -  geant (tracking code)
\indenttt{gx} -  geanx  (graphics)
\vskip 12pt
\indenttt{wi} -  windows 
\indenttt{ze} -  zeusadam  
\indenttt{zg} -  zgftdrif (drift time relationships)
\indenttt{fl} -  fldmin (magnetic field routines)
\indenttt{ea} -  eaze (analysis shell)
\end{indentlist}
\begin{figure}[h]
\epsfxsize=10cm
\centerline{\epsffile{/users/koepke/texfiles/offline.eps}}
\caption{\label{fig:offl}ZEUS offline and MC programs}
\end{figure}  

\section{ZEPHYR} 
\ind{ZEPHYR} is a collection of modules designed to reconstruct
events from ``raw data''
produced by the ZEUS detector or by the ZEUS simulation program
\ind{MOZART}.
% Full details can be found in the ZEPHYR Primer\cite{zphyr_primer}.

The reconstruction of events will run through three {\it phases \/}:
\begin{enumerate}
\item[I] Reconstruction of individual components: tracking chambers 
(CTD, VXD),
compensating calorimeter (CAL)\cite{ZCAL}, 
backing calorimeter(BAC), FTD and RTD, FMUON, BMUON~\cite{ZMB}, RMUON, HES\cite{ZHES},
leading proton spectometer LPS
 and luminosity monitor LUMI.
\item[II] Global track matching, vertexfinding VXFIT\cite{ZVXFIT}, 
global calorimeter matching package GLCAL (BAC + CAL),
matching of tracks and clusters ?.
\item[III] Particle identification, e.g. by combining measurements from the CTD
(d$E$/d$x$), CAL and HES.
\end{enumerate}
These requirements are reflected not only in the modual structure of the event
reconstruction program ZEPHYR but also in the event format. Event data are coarsly
structured by grouping ADAMO tables into logical records called {\it dataflows\/}.
The dataflow structure of ZEUS evens is shown in the following table.
\begin{indentlist}{2.0cm}{2.25cm}

\indenttt{HEAD} -  
 Events summary information, e.g. derived physics quantities ($x_{Bjorken}$,
$Q^2$), Trigger bits, etc. 
\indenttt{MCTRUTH} - 
Monte Carlo four vectors and hits (output from Mozart).
\indenttt{RAWDATA} - 
Hits, digitisations, calibrated raw data ( input to ZEPHYR) 
\indenttt{PHASE1} - 
ZEPHYR output from reconstruction phase I 
\indenttt{PHASE2} -
ZEPHYR output from reconstruction phase II 
\indenttt{PHASE3} -
ZEPHYR output from reconstruction phase III 
\end{indentlist}

Some description of the various offline processors is given in the ZEUS blue book
\cite{blue_book}.
The phase II global track reconstruction aims to combine  all the track segments
reconstructed in the different ZEUS tracking detectors in order to obtain the optimal
track parameters. 

For program organisation and control as well as random access and sequential I/O
utility programs have been developed:
\begin{itemize}
\item The KWIN package (see section~\ref{sect:KWIN}) 
allows to steer program by means of control
cards
\item The MOMO package  (see section~\ref{sect:MOMO}) 
allows exception signalling and monitoring of program at 
execution time
\end{itemize}
The reading  and administration of geometry and calibration data is performed by means
of the ZD package. 
% (see section~\ref{sect:ZD}). 
The sequentiol I/O is managed by ZRIO (see section~\ref{sect:ZRIO}). 
These same tools are implemented in MOZART, EAZE, LAZE, and ZDIS.

The reconstruction program ZEPHYR is currently implemented on VAX/VMS, IBM/MVS and on 
several UNIX workstations including DEC 5000, IBM RS6000 and Silicon Graphics.

\section{EAZE}
EAZE ({\bf E}ffortless {\bf A}nalysis of {\bf Z}eus {\bf E}vents) is analysis sceleton
whose function is to read events produced in the Zeus offline chain and allow the user
to select events, perform physics analyses, and produce histograms.
 

EAZE calls the user subprograms {\tt ZUINIT}, {\tt ZUANAL} and {\tt ZUTERM} in the 
following way:
\begin{figure}[h]
\epsfxsize=11cm
\centerline{\epsffile{/users/koepke/texfiles/eaze.eps}}
\caption{\label{fig:eaze}EAZE routines}
\end{figure}  


The dummy user routines can be found in EAZE.CAR and contain the necessary calls and
sequences.

\begin{indentlist}{2cm}{2.25cm} 
\indentbf{ZUINIT} -   {\bf Z}eus {\bf U}ser {\bf INIT}ialisation.
In this routine (no arguments) the user is supposed to book histograms and perform any
required run initialization. Note that a call to HLIMIT with negative argument is 
mandatory as not to be in conflict with the ZEBRA initialization.
\indentbf{ZUANAL} - {\bf Z}eus {\bf U}ser {\bf ANAL}ysis. Here the user
performs the analysis and fills histograms. The routine is called by the statement
CALL ZUANAL(IWant), where IWant is an integer return argument from ZUANAL. if IWant
is set to 1 then the event is selected for output. If IWant is set to 0 the event is
not written out.

\indentbf{ZUTERM} -  {\bf Z}eus {\bf U}ser {\bf TERM}ination. In this subroutine 
(no arguments) the user is supposed to perform the run termination; note that HISTDO
is already called in EAZE so you don't have to do it.
\end{indentlist}
A simple program is listed below:

\footnotesize\begin{verbatim}
+DECK, ZUINIT.
*CMZ :          02/07/92  15.13.30  by  ZEUS Offline Group
*CMZ :  3.03/03 05/06/92  10.11.41  by  ZEUS Offline Group
*-- Author :
        Subroutine ZUINIT
*       *****************
        Implicit NONE
+CDE, EZHBOOK.
        Parameter(NITEMS=3,NPRIME=1000)
        Real XTUPLE(NITEMS)
        Character*8 CHTAGS(NITEMS)                  
        DATA CHTAGS /'Run_no  ','Event_no','Energy  '/   ! name the n-tuple entries 
        Call HLIMIT(-Nwds_HBOOK)                         ! initialize HBOOK
        Call HROPEN(11,'DATA',data.dat,'N',1024,ISTAT)   ! open data.dat on unit 11
*                                                        ! with symbolic name DATA 
        Call HBOOKN(10,'Cal',NITEMS,'DATA',NPRIME,CHTAGS)! book ntuple with name Cal 
        Return
        End
+DECK, ZUANAL.
*CMZ :  3.03/03 05/06/92  10.11.41  by  ZEUS Offline Group
-- Author :
        Subroutine ZUANAL(IWant)
*       ************************
+CDE, PARTAP.                                           ! Parameters for tap
+CDE, ZREVT.                                            ! Event header
+CDE, CALTRU.                                           ! calibrated cell energies in
                                                        ! calorimeter
        Implicit NONE                                   
        Integer iwant,iend,n
        Real energy                                    
        iwant  = 0                                      ! initialize: I want this event
        energy = 0                                      ! reset energy
        CALL FETTAB(ZREVT,id,1)                         ! fetch ZREVT common block 
        XTUPLE(1) = Float(ZREVT_RunNr)                  ! fill in run number 
        XTUPLE(2) = Float(ZREVT_EvtNr(1))               ! fill in event number
        iend=coutab(CALTRU)                             ! see how many rows ....
        if(iend.ne.0) then 
         do  1000 n=1,iend                              ! loop over rows
          CALL FETTAB(CALTRU,id,n)                      ! fetch CALTRU common block                         
          energy=energy+caltru_e                        ! add up the energy
 1000    continue
        endif
        XTUPLE(3) = energy                              ! fill in total energy      
        Return
        End

+DECK, ZUTERM.
*CMZ :  3.03/03 05/06/92  10.11.41  by  ZEUS Offline Group
*-- Author :
        Subroutine ZUTERM
*       *****************
*       Implicit NONE
        Call HROUT(0,ICYCLE,' ')                        ! write out all histograms 
        Call HREND('DATA')                              ! close file 
        Return
        End

\end{verbatim}\normalsize
\section{MOZART}

The {\bf MO}nte Carlo for {\bf Z}eus {\bf A}nalysis, {\bf R}econstruction and 
{\bf T}rigger (MOZART) makes use of the CERN GEANT program package\cite{geant}
to track the particles through the whole detector taking due account of 
physics processes such as particle decay, energy loss and multiple scattering.
To describe the development of hadronic showers, the program package
GEISHA is implemented. Information on the detector simulation can be 
found in the blue
 book\cite{blue_book}; the simulation performance is discussed
in\cite{ZTRIG}.


% Some of the often used commands are listed below:

\section{ZDIS}

The ZDIS program package~\cite{ZZDIS} contains the shell steer a variety of 
physics generator programs and to store the  information about the events in 
ADAMO tables. This tables can be direct input for EAZE to perform generator level 
studies. The installation routines, run procedure, and control card examples 
can be found on VXDESY under
{\tt ZRINST:[GENERATOR]ZDIS\_xxx\_EXE.COM}, {\tt
ZREXAM:[GENERATOR]ZDIS\_xxx\_RUN.COM},
and {\tt ZREXAM:[GENERATOR]ZDIS\_xxx.CARDS},respectively. The three
letter abbreviation {\tt xxx} is given in the list of available generators
below. On the ZOW cluster the equivalent files can be found under 
{\tt /zeus/pro/zdis}, {\tt /zeus/pro/zdis/exam}, and
{\tt /zeus/pro/zdis/source}.
Refer to~\cite{ZZDIS} for full details. In most cases a writeup is included in the 
pam file. Check the directories for additional or updated generators.
\begin{indentlist}{4cm}{4.25cm}
\indenttt{LEPTO (LEP)} LEPTO 5.2 with JETSET 6.3
\indenttt{ARIADNE (ARI)} LEPTO 5.2 with ARIADNE 3.1
\indenttt{AROMA (ARO)} AROMA 1.2 with LEPTO 5.2 and JETSET 6.3 (writeup included in
{\tt RADIATE.pam}
\indenttt{PYTHIA(PYT)} PYTHIA 5.6 with JETSET 7.3~\cite{lund_mc}
\indenttt{LQUARK(LPQ)} lepto-quark generator 2.1 
\indenttt{HERWIG (HRW)} HERWIG 5.3 
\indenttt{HERACLES (HCL)} HERACLES 4.1 with LEPTO 5.2 
\indenttt{HERARIA (HAR)} HERACLES 4.1 with ARIADNE 3.1 
\indenttt{SUSANA (SUS)} super symmetric process generator 1.4
\indenttt{GAMTOT (GMT)} photo production generator 3.1
\indenttt{LEP60 (L60)} LEPTO 6.1 with JETSET 7.3
\indenttt{EMPTY (EMP)} EMPTY shell program for users wishing to test own generators  
\end{indentlist}

%------------------------------------------------------------------------
 
\section{Physics analysis utility routines}
 
Many utility subroutines exist for utility tasks such as track and
vertex manipulations, error matrix gymnastics, kinematic juggling
etc. Rather than write your own routine and get the sign wrong first
check if such a thing already exists either in one of the ZEUS utility
libraries or in other libraries.
 
%........................................................................
 
\subsection{The \ind{PHANTOM} collection of routines}
The PHANTOM ({\bf PH}ysics {\bf AN}alysis {\bf T}echniques, {\bf O}perations and
{\bf M}ethods) package is a collection of subroutines/functions (and packages of 
routines) for data analysis. It is meant to be used on output of the MOZART, ZEPHYR
or ZDIS programs.
PHANTOM contains a rapidly growing set of routines: it is meant to be a platform
to share analysis software with the ZEUS collaboration and to avoid unneccessary 
duplication. PHANTOM is installed on the IBM, VXDESY and DECcluster; the list of 
available routines -- which is automatically updated for each release -- can be 
found in the file {\tt ZRPAM:PHANTOM.DOCU} on VXDESY.
The installation routine and the routine that extracts the documentation file 
are stored in {\tt ZREXAM:[GENERATOR]} as {\tt PHANTOM\_OLB.COM} and 
{\tt PHANTOM\_DOCU.COM}, respectively.
%the ZEUS collaboration; 
% Full details are given in the documentation which is available 
%in {\tt /zeus/pro/doc/phantom.docu}.
%The PX library is a physics utility library, containing
%routines for rotations of vectors, Lorentz boosts, calculations
%of invariant mass, sphericity, thrust and jet$-$finding, plus more
%mundane but common tasks such as cross products and resolution
%of 3$-$vectors into parallel and perpendicular components, print$-$out
%of arrays etc. Full details are given in\cite{px_primer}.
 
\noindent
%The Main Physics Analysis Routines
%\small
%\begin{indentlist}{2.50cm}{ 2.75cm}
%\end{indentlist}
%\normalsize
%Other Physics Analysis Routines
%\small
%\begin{indentlist}{ 2.50cm}{ 2.75cm}
%\end{indentlist}
\normalsize

\section{Event display}

Two different stand-alone display programs, GAZE\cite{ZGAZE} and 
LAZE\cite{ZLAZE}
have been developed in parallel, but there is no more support for GAZE.
\begin{indentlist}{1.5cm}{1.75cm}
\indentbf{GAZE} - ({\bf G}raphical {\bf A}nalysis of {\bf Z}eus {\bf E}vents)
allows a representation of data in three dimensions (3D). Continuous real-time
transformations, like rotations, are possible.
\indentbf{LAZE} - ({\bf L}ook {\bf A}t {\bf Z}eus {\bf E}vent) specializes on 
two dimensional projections, most of which one cannot get by a simple geometrical
projection from the three-dimensional representation. LAZE is being augmented 
to three-dimensional viewing.
\end{indentlist}
\subsection{LAZE}
LAZE  
does not require special graphics hardware and runs on color as well as 
black and white workstations or X-terminals. An earlier version of 
LAZE is documented in\cite{ZLAZE}.
It can be used with a graphical 
interface that makes it easy to interactively analyze raw and reconstructed data
(the LAZE menus will guide you).
On the ZOW cluster the LAZE program is easily started by pressing the left 
mouse button when the cursor does not point to a window; LAZE can then be selected
from the root menu. 
 
Use the {\tt EVENT} button to choose the datafile you want to examine.


 
%------------------------------------------------------------------------
 

%........................................................................
 
 
%-----------------------------------------------------------------------
 
% \section{Coding conventions}\index{Coding conventions}\index{Standards}
 
%All public ZEUS code (and preferably private as well) should be
%written in standard ANSI Fortran~77. This is not completely possible
%and some violations (such as IMPLICIT NONE) are allowed or even
%demanded. The ZEUS coding conventions
%are described fully in\cite{code_conv} and\cite{code_conv2}.
%Basic checks can be performed by using
%\begin{verbatim}
%  $ FORT/STANDARD=ALL
%\end{verbatim}
%on the VAX.
 
%========================================================================
 
\chapter{Utility program packages}
 
%------------------------------------------------------------------------
 
\section{\label{sect:hbook}\ind{HBOOK}}

HBOOK is a package for defining, filling, manipulating and printing
one, two or multi dimensional histograms (called \ind{Ntuples}).
Full details can be found
in the HBOOK User Guide\cite{hbook_guide}.
Most of the manipulative
functionality of HBOOK is more easily performed inside \ind{PAW} and
the main use of HBOOK is to create direct access \ind{ZEBRA} \ind{RZ}
files for later input to PAW.
 
\noindent
An example of a standalone job to create such a file is given below:
\index{HBOOK!example job}\index{Example jobs!HBOOK}

\footnotesize
\begin{verbatim}
*
      IMPLICIT NONE
      INTEGER LIMH,LVECT,NPRIME,I
      PARAMETER (LIMH=100000,LVECT=4,NPRIME=1000)
      REAL H,VECT(LVECT),X,X2,X3,X4,RNDM
      COMMON/PAWC/H(LIMH)
      CHARACTER*2 TAGS(LVECT)
      EXTERNAL RNDM
      DATA TAGS/'x ','x2','x3','x4'/
*
      CALL HLIMIT (LIMH)
*
      CALL HBOOK1 (10,'One dimensional',100,0.0,1.0,0)
      CALL HBOOK2 (20,'Two dimensional',100,0.0,1.0,50,0.0,1.0,0)
      CALL HBOOKN (30,'N dimensional',LVECT,' ',NPRIME,TAGS)
*
      DO 10 I=1,1000
        X = RNDM(0)
        X2 = X**2
        X3 = X**3
        X4 = X**4
        CALL HFILL (10,X,0.0,1.0)
        CALL HFILL (20,X,X2,1.0)
        VECT(1) = X
        VECT(2) = X2
        VECT(3) = X3
        VECT(4) = X4
        CALL HFN (30,VECT)
   10 CONTINUE
*
      CALL HRPUT (0,'HTEST.RZHIST','N')
*
      END
\end{verbatim}\normalsize
 

%.......................................................................
 
\subsection{Reading ntuples in batch jobs}
\index{Ntuples!reading in batch jobs}
 
Although Ntuples stored in RZ files are usually analysed with PAW
as described in Section~\ref{sect:lab_paw} it is sometimes useful to
read them in batch Fortran jobs. The following prescription,
although not documented in the HBOOK manual, seems to work.

\footnotesize\begin{verbatim}
*
*-- Open the RZ file.
*
      CALL HROPEN (2,'Data','mydata.rzhist',0,1024,ISTAT)
*
*-- Select Ntuple number 3
*
      IDN = 3
      CALL HGNPAR (IDN,'MYBAT')
      CALL HNOENT (IDN,IMAX)
*
*-- Loop over entries loading into VECT
*-- (HGNF is the opposite of HFN)
*
      DO 30 I=1,IMAX
        CALL HGNF (IDN,I,VECT,IERR)
   30 CONTINUE
*
*-- Close the RZ file.
*
      CALL HREND ('DATA')
      CLOSE (2)
      DO 80 I=1,NTUPLES
        IF (HEXIST(I)) CALL HDELET (I)
   80 CONTINUE
\end{verbatim}\normalsize
 
%........................................................................

 
%------------------------------------------------------------------------
 
\section{\label{sect:hplot}\ind{HPLOT}}

HPLOT is a set of programs for producing \ind{HBOOK} output on graphics
devices other than a line printer. Full details can be found in the
HPLOT User Guide\cite{hplot_guide}. Since all of the functionality
of HPLOT is available much more conveniently inside \ind{PAW}, there
is little need to use HPLOT directly outside PAW.
 
%------------------------------------------------------------------------
 
\section{\ind{PAW}\label{sect:lab_paw}}
 
PAW (Physics Analysis Workstation) is one of the main tools available
for analysis of ZEUS data. It is essential to have a copy of the
PAW manual\cite{paw_manual} which contains a more complete reference
to all the available commands.
 
\noindent
The normal method of using PAW is to create an \ind{RZ} file of
histograms or ntuples in a batch \ind{EAZE} or
standalone job (such as that shown in Section~\ref{sect:hbook}) and to
analyses and plot the data using PAW.
 
\noindent
%To run PAW on a Vaxstation type \tp{PAW} and give {8601}, for a huge
%window, or {8604}, for a more sensible one, as the workstation type.
A few basic commands to get started are given below.
\begin{indentlist}{6.00cm}{6.25cm}
\indenttt{h/file 1 htest.rzhist} To connect the file htest.rzhist to
                                   unit 1.
\indenttt{h/list} To see what's on it.
\indenttt{n/print 30} To see what's in ntuple 30.
\indenttt{h/plot 10} To plot histogram 10
\indenttt{h/plot 10 e} To plot histogram 10 with error bars.
\indenttt{h/plot 20 s} To superimpose histogram 20 on the current
                         plot.
\indenttt{n/plot 30.x2} To plot variable x2 of ntuple 30.
\indenttt{n/plot 30.x2\%x} To plot variable x2 of ntuple 30 against
                             variable x.
\indenttt{1d 51 'title' 100 0.0 1.0} Define a one-dimensional
             histogram 51 with 100 bins between 0.0 and 1.0.
\indenttt{2d 52 'title' 100 0.0 1.0 50 0.0 0.5} Define a
             two-dimensional
             histogram 52 with 100 x bins between 0.0 and 1.0 and
                                50 y bins between 0.0 and 0.5.
\indenttt{n/plot 30.x2 x<0 -51} To plot variable x2 of ntuple 30 in histogram 51
under the condition that {\tt x<0}
\indenttt{n/proj 51 30.x2} Project variable x2 of ntuple 30
                             into histogram 51.
\indenttt{n/proj 52 30.x2\%x} Project variable x2 against x
                 of ntuple 30 into histogram 51.
\indenttt{exit} To leave PAW.
\end{indentlist}
 
%........................................................................
 
\subsection{Useful commands}\index{PAW!useful commands}
 
\subsubsection{Making cuts}\index{PAW!making cuts}
 
For both \tp{n/plot} and \tp{n/proj} one can apply cuts or with
\tp{n/cuts} define cuts to be applied e.g.
\begin{verbatim}
n/plot 30.x2 x>0.5
n/plot 30.x2 x.gt.0.5
n/cuts 1 x>0.5
n/plot 30.x2 1
n/plot 30.x2 1.and.x<0.75
\end{verbatim}
 
\noindent
When using \tp{n/plot} the scaling is automatic. Thus if you are
plotting track momenta and one track is mis-measured to have
2000~GeV/c momentum, then the command \tp{n/plot 100.p} would
produce a plot with all the data except that track in one bin
at one end of the plot. This could be overcome by instead typing
\tp{n/plot 100.p p<100}.
 
\subsubsection{Reading many files}\index{PAW!reading many files}
 
You can open several files at one time by attaching them to
different unit numbers. You can use any unit numbers except
5, 6, 7, 10 and 92. Type \tp{units} to see what is attached to what
unit. All commands take effect in the current directory. If you
have been looking at what was on unit 21 and you want to look at
what is on 22 instead type \tp{cd //lun22} to change the current
directory. Any histograms you make with \tp{1d} or \tp{2d}
commands are created in the  directory {\tt //pawc} as is a copy
of any accessed histograms from the currently accessed file.
If you are looking at the same plots from different units you
might have to delete the version in {\tt //pawc} via \tp{h/del 10} say.
 
\subsubsection{Comparing data and Monte Carlo}
\index{PAW!comparing Monte Carlo and data}
\index{Monte Carlo!comparing with data}
If you have two RZ files one for Monte Carlo and one for data
you can compare histograms 10 say with the following:
\begin{verbatim}
h/file 25 data.rzhist
h/file 26 mc.rzhist
h/plot //lun25/10 e
h/plot //lun26/10 s
\end{verbatim}
 
\noindent
However unless they contain exactly the same number of events
the normalization will be wrong. One way to overcome this is
\begin{verbatim}
cd //lun25
norm 10
h/plot 10 e
cd //lun26
norm 10
h/plot 10 s
\end{verbatim}
 
\noindent
The plots will each be normalized to unit area. This is not
always satisfactory since one usually wants the data as it comes
with the Monte Carlo normalized to it. Assuming you have 4 times
as much Monte Carlo as data you can do the following:
\begin{verbatim}
cd //lun25
h/plot 10 e
cd //lun26
add 10 10 11 0.25 0.0
h/plot 11 s
\end{verbatim}
 
\subsubsection{Getting hardcopy under PAW}
\index{PAW!printing the picture}\index{Printing!from PAW}
In order to print conveniently from PAW one has to do two things.
\begin{itemize}
\item First include in your file {\tt pawlogon.kumac} the line
\begin{verbatim}
       option ZFL1
\end{verbatim}
This will automatically store the {\tt last}
 plotted object as a ``HIGZ'' picture in memory.
({\tt option ZFL} would store {\em all} plotted objects).
\item Create something like the following file {\tt postit.kumac}
if you are working on the UNIX cluster:

\footnotesize
\begin{verbatim}
macro postit kind=-111 unit=66 file='plotpaw.ps' printer='zeusps0' ! defaults  
fortran/file [unit] [file]      ! open file on unit       
metafile -[unit] [kind]         ! open metafile of your choice (no display)    
picture/plot ' '                ! plot current picture
close [unit]                    ! close file                      
shell lpr -P[printer] [file]    ! print file on printer
return                          
\end{verbatim}\normalsize

The actual print command has to be chosen differently if you are working on
another system (see table~\ref{tab:printing}).
\end{itemize}
In PAW you will have to type {\tt exec postit} tp print the histogram you have
just plotted (if you don't want to use defaults type e.g.
{\tt exec postit file='my.ps' kind=-112}; this would plot in landscape mode
and write on file {\tt my.ps}).
 


% -----------------------------------------------------------------------

%\section{\label{sect:AIDA}\ind{AIDA}}

%AIDA, the {\bf A}damo {\bf I}nteractive {\bf D}ata {\bf A}nalyzer\cite{ZAIDA},
%%%o FORTRAN. It provides -- as is the case in PAW -- access to histogramming,%
%fitting and plotting features by calls to HBOOK and HPLOT.

%IDA has less features than PAW, but it has the advantage that ADAMO files can
%directly be read in and that structures like nested loops can easily be constructed.
%Another advantage is that analysis programs e.g. from the PHANTOM library can be 
%loaded with AIDA so that their funtionality is available.
%AIDA is implemeted under UNIX, VAX/VMS and IBM/VM .
%\subsection{IDA example} 
%------------------------------------------------------------------------
 
\section{\label{sect:KWIN}\ind{KWIN}}

KWIN\cite{ZKWIN} is a set of routines that allows one to input
variables into a program in free-format. The KWIN package provides a
ZEUS specific layer on top of the CERN package
FFREAD\cite{ffread_guide}. It allows variables to be changed at run
time without having to recompile and link the program. KWIN collects
control cards in an ADAMO data structure out of which they are
presented to the FFREAD package.

The data card identification consists of two parts, a prefix 
separated from a keyword by a hyphen. Both parts may have up to 8 characters.
The keyword is terminated by a blank.
The rest of the card is read in as a character string, the content of which is
under the control of the user. An example is given below:

\footnotesize\begin{verbatim}
C
C a card starting with C 'blank' is ignored
Prefix-KeyW   1 2. 3 4.
ZeusIO_RUNR 1 10
ZeusIO-OOPT MEDIUM=disk DRIVER=FZ
            FILFOR=NATI

\end{verbatim}\normalsize
Note that a card starting with a blank is considered  to be a continuation card.

The data cards are read in using a call to KWIN in the ZUINIT. An example is given
below:

\footnotesize\begin{verbatim}
         Subroutine ZUINIT
         INTEGER RUNRGE(2,100)
         REAL SPACE
         COMMON /CFREAD/ SPACE(1000)
          .
         Call KWIN(ISucc)
*
* if Isucc .ne. 1 there was a problem ....
* now reinitialize FFREAD so that previous calls to FFKEY are forgotten by FFREAD
*
         Call KWFFRD(IErr0) 
*
* if all went well IErr0 = 0 ....
* now the user must make calls to FFKEY to define the key words and the structure
* of the data FFREAD is to expect
*                      
         Call FFKEY('RUNR',RUNRGE,4,'INTE')
*
* this starts the key card reading; 'list' is a list of prefix names
* (like Zeus-IO), separated by commas
*
         Call KWFFGO('list',Ierr1)
* if all went well IErr1 = 0 ....

\end{verbatim}\normalsize    
  
\section{\label{sect:MOMO}\ind{MOMO}}

MOMO
 is a set of program monitoring routines. The number of calls and the time
spent are accumulated automatically by MOMO.
An example is given below.

\footnotesize\begin{verbatim}
*   
        Parameter(weight=1.,severity=3)
*   
        Call ModIn('XXINIT',IDum)                    ! wake up Momo in modul XXINIT  
*
        Call XXX(IErr)
        If(IErr.ne.0) Then
           Call MoSetC('XXX fails',weight,severity)  ! store message 
           Goto 8900
        Endif   
\end{verbatim}\normalsize
On the call to MoSetC 
the condition identified by the message string 'XXX fails' is 
recorded, related to the current modul,  with weight=1.0
and severity=3. The meaning of the severity codes is 
\begin{indentlist}{1.0cm}{1.25cm}
\indentbf{-1} - utterly harmless
\indentbf{0}  - harmless warning
\indentbf{1} - fatal for completion of module
\indentbf{2} - fatal for processing of event
\indentbf{3} - fatal for continuation of execution
\end{indentlist}
The query routine MoGetC(modulname,message\_string,weight,severity) returns the total
accumulated weight and the severity condition for given modulname and message\_string.

\section{\label{sect:ZRIO}\ind{ZRIO}}

ZRIO\cite{ZZRIO} is a sequential I/O package for the ZEUS offline software.
It provides extensive selection criteria on the basis of run and event numbers
and supports selective reading of event dataflows and writing to parallel output 
streams. Some ZRIO card steering options, with examples for the VAX, are listed below:

\footnotesize\begin{verbatim}
C ========= event/time limits =============================
C total number of events to process ( default = unlimited )
ZRLIMIT-NEVT   5
C time limit in seconds             ( default = 20 sec )
ZRLIMIT-TLFT 120.
C 
C========== input specification ===========================
C files to be read in
ZeusIO-INFI    WORKU:JUNK1.DATA
               WORKU:JUNK2.DATA
C input options
ZeusIO-IOPT    MEDIUM=DISK,DRIVER=FZ,FILFOR=NATI
               MEDIUM=DISK,DRIVER=FZ,FILFOR=EXCH
C 
ZeusIO-IRCD    ALL
C
ZeusIO-IDFL    ALL
C
C you can also specify which tables you want to read in or write out by defining, 
C for example, a dataflow like RDSTDFL in the following way:
C ZeusIO-DEFDFL  TrgDFL  = LMEB O1SETU O1SUBT O1RCDT O1EVNT O2DEC TLTEVT
C                RecDFL ZeusIO-IDFL     HEAD,MCTRUTH,RDSTDFL
C                RDSTDFL = TrgDFL RecDFL
C ZeusIO-IDFL    HEAD,MCTRUTH,RDSTDFL
C========== output specifications =========================
C files to be written out
ZeusIO-OUFI    WORKU:JUNKOUT1.DATA
               WORKU:JUNKOUT2.DATA
C output options
ZeusIO-OOPT    MEDIUM=DISK,DRIVER=FZ,FILFOR=NATI
               MEDIUM=DISK,DRIVER=FZ,FILFOR=EXCH
C
ZeusIO-ORCD    HDR
               HDR,EVT
C
ZeusIO-ODFL    HEAD
               HEAD,MCTRUTH,RAWDATA,PHASE1,PHASE2
C
C========== run/event selections ==========================
C select a range of runs between RUNMIN and RUNMAX
ZeusIO-RUNR                      1          10
C select a range of events in    RUN  from EVENTMIN to EVENTMAX
ZeusIO-EVTR                      12        4           406
                                 13        100         101
C select a list of events in     RUN      EVENT 
ZeusIO-EVTL                      20        1
                                 21        8
\end{verbatim}\normalsize
In addition there are the cards ZeusIO-VRUN, ZeusIO-VEVR and ZeusIO-VEVL
which veto runs and events for the selected ranges.

The above example is given for VAX/VMS; the file specification will of course
be different on UNIX machines.

On the IBM, which allows direct access to the data tapes, one can select tapes 
without specifying the actual data set names~\cite{ibmtapeeaze}. In addition 
one can specify whether a tape should be staged (i.e. temporarily put on disk),
which is helpful if a tape is to be read more than once. The following example 
shows how to read in the DST for run 1938 using the staging option. 
In this case no JCL card
should be specified for defining 
the data set.
\begin{verbatim}
ZeusIO-RUNR  1938 1938
ZeusIO-INFI  DSTTAPE
ZeusIO-STAGE YES
\end{verbatim}

%------------------------------------------------------------------------
 
\section{\label{sect:PATCHY}\ind{PATCHY}}
\label{PATCHY}
 
PATCHY is a system designed to allow editing and updating of large
programs stored on physical punched cards.
Thankfully the use of
PATCHY in ZEUS is restricted to a few fairly basic and reasonably
useful features. Only these basic features are described here.
See\cite{patchy_primer} for a fuller introduction.
 
\noindent
PATCHY is a pre-processor which one runs on a deck of `cards' to
produce FORTRAN which can then be compiled and linked etc. The
deck of `cards' is basically fortran with a few extra lines which
PATCHY interprets. The `cards' can be stored in two forms, a
CARDS file, which is a normal alphanumeric version of the file
which you can print, edit etc, and a PAM file which is a binary
version which is in principle more compact. However, PAM files have
recently fallen out of fashion. In addition to the
\ind{CARDS} or \ind{PAM} file there is a list of PATCHY directives which
contains the commands to change the PAM into FORTRAN including
any edits that may be applied at that time. This file is called
a \ind{CRADLE}. If you look at a subroutine inside a PAM or CARDS
file ALWAYS CHECK THE CRADLE to see if there have been modifications
made later.
 
\noindent
A CARDS file consists of several large sections called \ind{PATCH}es
each of which is split into several smaller \ind{DECK}s.
Inside each patch, each subroutine, bank, common block etc is
contained in its own DECK.
 
\noindent
The most useful cards are
\begin{indentlist}{5.0cm}{5.25cm}
\indenttt{+TITLE.} Gives the whole CARDS file a title.
\indenttt{+PATCH,name.} Defines the start of a new PATCH.
\indenttt{+DECK,name.} Defines the start of a new DECK.
\indenttt{+KEEP,name.} Defines a common block or piece of frequently
                      used code.
\indenttt{+SEQ,name.} Says that the piece of code previously defined
                    by a KEEP statement should be included at this
                    point.
\indenttt{+CDE,name.} Equivalent to {\tt +SEQ}.
\indenttt{+SELF,IF=switch.} Says that the following code should only
                   be included if the switch is set.
\indenttt{+SELF.} End an optional piece of code.
\end{indentlist}
 
\noindent
An example might be

\footnotesize\begin{verbatim}
+PATCH,MYCDES.
+KEEP,MYCOM.
      INTEGER N1,N2
      COMMON /MYCOM/ N1,N2
+PATCH,MYPROG.
+DECK,MAIN
      PROGRAM MYPROG
+SEQ,MYCOM.
      N1 = 1
      N2 = 2
      CALL MYSUB
      END
+DECK,MYSUB
      SUBROUTINE MYSUB
+SEQ,MYCOM.
      INTEGER N3,NOW
      N3 = N1 + N2
+SELF,IF=VAX.
      CALL LIB$TIME (NOW)
+SELF,IF=IBM.
      CALL IBMTIME (NOW)
+SELF.
      WRITE (6,*) 'At ',NOW, 'the answer was ',N3)
      END
\end{verbatim}\normalsize
If this were run through PATCHY with the switch VAX set then the
result would be

\footnotesize\begin{verbatim}
      PROGRAM MYPROG
      INTEGER N1,N2
      COMMON /MYCOM/ N1,N2
      N1 = 1
      N2 = 2
      CALL MYSUB
      END
      SUBROUTINE MYSUB
      INTEGER N1,N2
      COMMON /MYCOM/ N1,N2
      INTEGER N3,NOW
      N3 = N1 + N2
      CALL LIB$TIME (NOW)
      WRITE (6,*) 'At ',NOW, 'the answer was ',N3)
      END
\end{verbatim}\normalsize
 
\noindent
In the cradle the most useful commands are
\begin{indentlist}{5.0cm}{5.25cm}
\indenttt{+USE,options.} Defines which PATCHes, DECKs, KEEPs
                       and switches you want to use.
\indenttt{+EXE,options.} Defines which PATCHes and DECKS you want
                       to write out as FORTRAN.
\indenttt{+REP,P=pname,D=dname,C=n} Replace line n of deck dname
               in patch pname by whatever follows.
\indenttt{+ADD,P=pname,D=dname,C=n} Add whatever follows after
                line n of deck dname in patch pname.
\indenttt{+DEL,P=pname,D=dname,C=n} Delete line n of deck dname
               in patch pname.
\indenttt{+PAM,11,T=ATTACH. filename} Define the PAM file to be
                  filename. There can be many such cards. Optional
      parameters such as \tp{R=XXCDES} will stop the reading of
      the pam once the PATCH XXCDES has been read or \tp{T=CARDS}
      tell it that the file is a CARDS file not a PAM file.
\indenttt{+QUIT} Defines the end of the commands.
\end{indentlist}

 
%........................................................................
 
\subsection{PATCHY utility programs}
 
\subsubsection{\ind{YPATCHY}}
 
YPATCHY is the program that takes a CRADLE plus a CARDS (or PAM) file
and turns it into FORTRAN. It exists on IBM, VAX and UNIX.
 
\noindent
On the VAX type
\type{YPATCHY pamfile fortfile cradle listing .GO}
where the default file types are .PAM, .FOR, .CRA and .LIS.
Normally YPATCHY is run inside a command file and the
PAM files are defined inside the cradle so a minus
sign is substituted for \tp{pamfile}, for example
\begin{verbatim}
$ YPATCHY - NAME TTY TTY .GO
followed by the cradle
\end{verbatim}
would read the cradle from the default input stream (unit 5)
create the fortran file NAME.FOR and write the output to
the default output stream (unit 6).
 
\subsubsection{\ind{YLIST}/\ind{YINDEX}}
 
YLIST produces a listing of a CARDS or PAM file. You need this to
get the line numbers with DECKs if you are to do any editing in
your cradle. YINDEX produces an index which is essential for
a large file. Both programs are available on IBM, VAX and UNIX.
 
\noindent
On the VAX type
\begin{verbatim}
     YINDEX pamfile option output .GO
     YLIST pamfile option output .GO
\end{verbatim}
where the default file types are .PAM and .LIS. For YLIST the option
can be an integer 0 for 56 lines per page, 1 for 62, 2 for 84 and
3 for 110. For example to make a listing of the file NAME.PAM
\begin{verbatim}
$ YINDEX NAME - NAME.INDEX .GO
$ YLIST NAME 3 NAME.BODY .GO
$ append name.body name.index
$ rename name.index name.listing
\end{verbatim}
 

%------------------------------------------------------------------------
 
\section{\ind{CMZ}}
 
CMZ ({\bf C}ode {\bf M}anagement system using {\bf Z}ebra)~\cite{cmz_guide} 
is described
by their authors as an advanced, interactive, fast, self-documenting,
customizable, machine-independent, PATCHY compatible source code
management system with special emphasis on FORTRAN and C source code.
CMZ uses the same source code directives as PATCHY (with a few
differences mainly in the support of options). A PAM file is equivalent
to a CMZ-library and a PATCH corresponds to a directory in which the
DECKS appear as members. CMZ provides a Unix-like shell in which you
give commands. The      user interface package KUIP provides the
framework for the help facility and allowes to redefine or combine
commands using the MACRO facility in KUIP. CMZ stores the source code
in a RZ direct access file making access fast (PATCHY reads files
in sequentially).
To invoke CMZ just type {\tt cmz} (the format for the allowed
options differs between different machines).
A sample session is shown below:
\footnotesize
\begin{verbatim}
  $ CMZ                           | enter CMZ environment
 CMZ [0] HELP MAKE                | Help for MAKE
 CMZ [1] HELP YTOC                | HELP for YTOC
 CMZ [2] MAKE GEANT               | create CMZ library file
 geant [3] YTOC GEANT.CAR         | import a cards file into a CMZ file
 geant [4] SHELL                  | suspend CMZ; use local command
                                  | processor
 $                                | prompt of local system
\end{verbatim}
\normalsize
Some of the more often used CMZ commands are listed below; they
usually carry several options which are not described here
(see interactive help).
\begin{indentlist}{4.0cm}{4.25cm}
\indenttt{MAKE fname } create CMZ library file and set current
              directory to the top directory of this file
\indenttt{FILE fname [-option] } attach an existing CMZ file; default
option is     {\tp -U} (update mode)
\indenttt{YTOC fname  } convert a CMZ card image file to a
              CMZ file
\indenttt{CTOY fname  } convert a CMZ file to a card image file
\indenttt{FTOC fname  } import a FORTRAN file into a CMZ file
\indenttt{CTOF decklist    } write one or more decks onto the default
   FORTRAN file
\indenttt{EDIT decklist      } edit one or more decks using local editor
\indenttt{READ decklist      } read one or more decks with local browser
\indenttt{CLIST lfile        } write a listing of a CMZ file or
    directory on file {\tp LFILE}
\indenttt{CLIST lfile        } write a listing of a CMZ file or
\indenttt{CDIR  [path]       } change current working directory to
      {\tp path}; if no path given print pathname
\indenttt{DIRECTORY}           list the content of a directory
\indenttt{FORTRAN  fname   }   compile fname generated by CTOF
\indenttt{LIBRARY          }   add or replace the object module
\indenttt{CFORTRAN decklist}   same as CTOF + FORTRAN
\indenttt{CFLIB    decklist}   same as CTOF + FORTRAN + LIBRARY
\end{indentlist}
To run a CMZ session it is advisable to install  a {\tt cmzlogon.kumac} file.
On the DEC cluster you should copy the standard ZEUS kumac in your top
directory
\begin{verbatim}
    cp /zeus/pro/kuip/.cmzlogon.kumac   ~/.cmzlogon.kumac
\end{verbatim}
At the end of this file you can specify your favorite editor for CMZ sessions,
 alias
definitions, the author name etc.
%------------------------------------------------------------------------
 
\section{\label{sect:KUIP}\ind{KUIP}}
{\bf K}it 
for a {\bf U}ser {\bf I}nterface {\bf P}ackage)~\cite{kuip_guide}
is a user interface system developed at CERN in the context of
PAW; it is also used in other interactive packages such as CMZ.
It features several dialog styles ( command line mode, menu mode
including a X-windows interface), contains a MACRO language and
provides on-line help and documentation. The commands are given
in a UNIX line syntax and can be abbreviated as long as they do not
become ambiguous.
%
%------------------------------------------------------------------------
 
\section{\label{sect:ZEBRA}\ind{ZEBRA}}

ZEBRA is a memory management system designed to overcome the main
limitation of FORTRAN~77 namely the lack of dynamic data structuring
facilities. Full details of ZEBRA can be found in\cite{zebra_guide}.
The are several separate parts to the ZEBRA package. The main
memory management part is called \ind{MZ}\cite{mz_guide}.
There is a sequential
input-output package called \ind{FZ}~\cite{zebra_fz} and a direct access package
called \ind{RZ}~\cite{zebra_rz}. There is also a debugging package called
\ind{DZ}~\cite{dzdisp_guide} .
 
%........................................................................
 
\subsection{ZEBRA bank structures}
 
ZEBRA uses a huge array in common which is divided
logically into smaller units called `banks'. These banks can be
created, removed or moved around inside the common block dynamically
during the running of the program. They can be self-contained units
or be related to one another via so called `links'.
 

The main words of a bank at address L are:
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
LQ(L-NS-NL) &         &  Last reference link NL \\
....        &         &  ....  \\
LQ(L-NS-1)  &         &  First reference link NS+1 \\
\hline
LQ(L-NS)    &         &  Last structural ({\em down}) link NS \\
....        &         &  .... \\
LQ(L-1)     &         &  First structural ({\em down}) link \\
\hline
LQ(L)       &         &  Address of {\em next} bank in a linear structure
\\
LQ(L+1)     &         &  Address of supporting bank ({\em up} link) \\
LQ(L+2)     &         &  Address of supporting link ({\em origin} link)
\\
IQ(L-5)     & = IQIDN(L) & Numeric bank identifier IDN \\
IQ(L-4)     & = IQIDH(L) & Hollerith bank identifier IDH \\
IQ(L-3)     & = IQNL(L) & Total number of links NL \\
IQ(L-2)     & = IQNS(L) & Number of structural links NS \\
IQ(L-1)     & = IQND(L) & Number of data words ND \\
IQ(L)       &           & Address of this bank \\
\hline
IQ(L+1)     &           & First data word \\
....        &           & .... \\
IQ(L+ND)    &           & Last data word ND \\
\hline
\end{tabular}
\end{center}
 
\noindent
{\em Structural links} allow complex bank structures to be built
up. These are of 2 kinds {\em tree/fanout} or {\em linear}. These
are shown schematically below.
\begin{figure}[h]
\epsfxsize=10cm
\centerline{\epsffile{/users/koepke/texfiles/zebra.eps}}
\caption{\label{fig:zebra}ZEBRA structures}
\end{figure}  

\noindent
{\em Reference links} are not part of the bank structure but are
a convenient way of referencing one bank from another.
 
\noindent
Because ZEBRA moves banks around in the common to maximize the
available space ({\em garbage collection}) one has to be careful
that all links are `protected'. When a bank is moved, all
structural and reference links are automatically updated to
point to the new position of the bank. Any local variables will
not be updated unless they have previously been declared to be
in a {\em link area} which is a special (usually common) area
which ZEBRA can maintain.
 

%........................................................................
 
\subsection{ZEBRA file types}
 
\ind{FZ}~\cite{zebra_fz}
 provides two input/output modes, {\em native} and {\em exchange}.
\index{Native mode}\index{Exchange mode} Files written in native
mode can only be read on the same machine that it was written on
since the data is recorded using the internal representation of
that machine. Files written in exchange mode can however be
transported across different machines and read on a different
computer to the one it was written on. It is faster to read
native mode files than exchange mode files. 

Sequential FZ files have a header in front of the main body of
data for each event and the contents of this header can be
inspected before deciding
whether or not to read the event into memory.

ZEBRA also incorporates a random access package \ind{RZ}~\cite{zebra_rz}
which e.g. forms the 
basis of PAW or CMZ.
 
\section{\label{sect:ADAMO}\ind{ADAMO}}
\label{ADAMO}

All datastructures in the ZEUS event reconstruction 
and analysis are defined using the
ADAMO ({\bf A}leph {\bf DA}ta {\bf MO}dule) data management 
system~\cite{adamo_guide} and described in the {\bf D}ata {\bf D}efinition
{\bf L}anguage (DDL). ADAMO is used for the design of data structures, for their
storage in memory and on external media such as disk or tape, and for their
documentation.
ADAMO is based on the {\bf E}ntity {\bf R}elationship {\bf M}odel (ERM) of
data\cite{ert_chen} and provides:
\begin{itemize}
\item a description of the data in terms of {\it entities\/} (e.g. hits of 
tracks), their {\it attributes\/} (e.g. position or momentum) and their 
{\it relationships\/} (e.g. hit lies on track)
\item a mapping of the entity relationship model to FORTRAN in which entities
are represented as tables using ZEBRA as the underlying memory manager, though
this is largely hidden from the user
\item the {\bf TA}ble {\bf P}ackage (TAP) which allows for manipulation of tables
from FORTRAN programs e.g. the access of data in common blocks.
\end{itemize}
\subsection{Design of data structures}

At the design stage, data structures are represented graphically by 
{\bf E}ntity {\bf R}elationship {\bf D}iagrams (ERD) which show entities and 
their attributes as boxes and the relationships between them as arrows.
These are then described by the ADAMO data definition language DDL
for input to the ADAMO ``MAD'' ({\bf M}ake {\bf A}DAMO {\bf D}ictionary) processor.
ZEUS DDL files constitute the master source for all ZEUS data structures and contain 
a number of additional explanatory comments.

\subsection{\ind{ADAMO tables}}

In FORTRAN programs, entites and their attributes are represented as tables with one
or more four-byte columns for each attribute which may be of type integer, real,
logical, character or bit-pattern. The column structure of tables is defined by 
{\it window column blocks\/} which are automatically created by the MAD processor.
Tables are stored row-wise (each row is of fixed length) in ZEBRA banks but are
normally accessed via the TAP so the ZEBRA structure is hidden from the user. 
The interface to each table is provided in the FORTRAN program by ``window common
block'' belonging to the table.

\subsection{\ind{The TAP}}

The full list of subroutines provided by the table package TAP can be found in the
ADAMO Programmer's Manual\cite{adamo_guide}. 
The user of EAZE can get a long 
way with only two TAP routines which allow to fetch information
from the window common blocks. Typically in an EAZE program one needs the following
elements:

\footnotesize
\begin{verbatim}
* first you have to include the window common block (in this case
* the calibrated signals from the DU calorimeter in the table Caltru:
*
+CDE, Caltru.
*
* definintion of parameters for ADAMO such as minc, maxc ....
*
+CDE, PARTAP.
     .  
     .
     .
* in order to find out how many rows there are in table Caltru ( in this case
* how many cells with energy) one uses the TAP function COUTAP
*
        iend=COUTAP(Caltru)
*  
        if(iend.ne.0) then
*
* loop over all table rows 
*
          do 1000 n=1,iend
*
* with the routine FETTAB you fetch the information for row n into the window 
* common block 
*
            call FETTAP(Caltru,id,n)    
*
* the energy of the cell is i.e. stored in caltru_e
* 
            energy = caltru_e
*
\end{verbatim}
\normalsize

The initialization of the TAP is already done for you if you run
an EAZE job. (Otherwise you have to initialize 
the TAP by {\tt CALL INITAP } and close
by {\tt CALL CLOTAP}).

One valuable feature of  the TAP, particularly for debugging, is the ability to print
out tables in a convenient format with appropriately labelled columns. The following
call   
%\footnotesize
\begin{verbatim}
         call PRITAP(Caltru,id,minc,maxc,allcol)
\end{verbatim}
%\normalsize
will print table {\tt Caltru}.
If  {\tt minc}, {\tt maxc}, {\tt allcol} are not specified their values are taken from 
the {\tt PARTAP} sequence which determine the defaults. In this case all rows and 
all columns of the table ({\tt allcol}) will be printed.  

The ADAMO package offers more functionality that can greatly improve the speed
of accessing data; for details contact the ADAMO manual~\cite{adamo_guide}. 

\subsection{ADAMO I/O}

The ADAMO I/O subsystem was re-written for ZEUS, partly to satify the requirements
that it should be possible to read old and new data tapes with the same program even
if table definitions have been modified by the addition or deletion of columns since
the old tapes were written. This is achieved by comparing the copies of the data 
dictionary metatables stored in tape and in memory and assigning {\it null\/} values
to attributes not recorded on tape.

The data to be transferred in an ADAMO I/O operation is specified as a 
{\it dataflow\/}, where a dataflow is defined as a set of tables of other dataflows.
The standard ZEUS dataflows are defined in the ZEUS DDL (see section on ZEPHYR).

Another important concept is that of I/O drivers for ADAMO. Standard I/O drivers are:
\begin{itemize}
\item ZEBRA FZ native format (sequential access)
\item ZEBRA FZ exchange format (sequential access)
\item ZEBRA RZ native format (random access)
\item IE, a readable and editable ASCII format.
\end{itemize}
 
The IE format is valuable as an alternative to the  RZ format for the exchange of 
small files between different computers an as a way of checking program output in the
course of development. Once the correct output is obtained, only minimal changes are
required to switch to the binary FZ format.

%------------------------------------------------------------------------
 
\section{\label{sect:MINUIT}\ind{MINUIT}}

MINUIT is a package to find the minimum value of a multi-parameter
function and to analyse the shape of the function around the
minimum. The principal application is for statistical analysis,
working on chi square or log-likelihood functions, to compare the
best fit parameter values and uncertainties, including correlations
between the parameters. It is especially suited to difficult
problems, including those which may require guidance in order to
find the correct solution. MINUIT is NOT intended for the
repeated solution of identically parameterized problems (such as
track fitting in a detector) where a specialized program will in
general be much more efficient. Full details can be found
in\cite{minuit_guide}.
 
\noindent
Although most of the functionality of MINUIT is available inside
\ind{PAW}, for complicated fits it is usually better to use MINUIT
outside PAW where it is easier to control (and won't keep crashing
PAW!).
 
\noindent
One should always check carefully that the fit has converged i.e.
that it has printed out STATUS=CONVERGED, otherwise the parameter
values and errors are probably garbage.
 
\noindent
A stand-alone example job is shown below\index{MINUIT!example job}
\index{Example jobs!MINUIT}

\footnotesize
\begin{verbatim}
      IMPLICIT NONE
      INTEGER I,IERR,IVAR
      DOUBLE PRECISION VAL,ERROR,BND1,BND2
      CHARACTER*10 CHNAM
      EXTERNAL MYFCN
*
*-- Initialize.
*
      CALL MNINIT (5,6,7)
*
*-- Set up title.
*
      CALL MNSETI ('Straight Line fit')
*
*-- Set up parameters.
*
      CALL MNPARM (1,'Intercept',0.0,0.1,0.0,0.0,IERR)
      CALL MNPARM (2,'Slope    ',1.0,0.1,0.0,0.0,IERR)
*
*-- Do the fit.
*
      CALL MNEXCM (MYFCN,'MIGRAD',0.0,0,IERR)
*
*-- Extract parameters with (rough) errors.
*
      DO 10 I=1,2
        CALL MNPOUT (I,CHNAM,VAL,ERROR,BND1,BND2,IVAR)
        WRITE (6,*) CHNAM,REAL(VAL),' +- ',REAL(ERROR)
   10 CONTINUE
*
      END
      SUBROUTINE MYFCN (NPAR,GRAD,FVAL,XVAL,IFLAG)
*
*-- This gets called every iteration of the fit.
*
      IMPLICIT NONE
      DOUBLE PRECISION GRAD(*),FVAL,XVAL(*),YC
      INTEGER NPAR,NPT,IFLAG,N
      PARAMETER (NPT=5)
      REAL X(NPT),Y(NPT),DY(NPT)
      DATA  X/1.0,2.0,3.0,4.0,5.0/
      DATA  Y/1.1,2.0,2.8,4.1,4.9/
      DATA DY/0.2,0.2,0.3,0.3,0.2/
*
*- Calculate chi squared.
*
      FVAL = 0.0D1
      DO 10 N=1,NPT
        YC = XVAL(1) + XVAL(2)*DBLE(X(N))
        FVAL = FVAL + ((DBLE(Y(N))-YC)/DBLE(DY(N)))**2
   10 CONTINUE
*
      END
\end{verbatim}\normalsize
 
%------------------------------------------------------------------------
 
%========================================================================
 

%========================================================================
 
\chapter{Word processing systems}
 
%------------------------------------------------------------------------
 
\section{\TeX\ and \LaTeX}
 
\TeX\ (pronounced Teck)\index{TeX}
is a text processing system developed by Donald
E.Knuth of Stanford University to compose by computer high quality
documents, especially those containing many mathematical formulae.
\LaTeX\index{LaTeX} adds
to \TeX\ a collection of commands that simplify typesetting
by imposing a more uniform style on the documents.
Full details can be found in the \TeX\cite{tex}
and \LaTeX\cite{latex} manuals. An excellent introduction to \TeX\ has been 
written at CERN~\cite{texatcern} which contains useful information also for users
at DESY. A very padagogical guide\cite{fussweg} 
to using \LaTeX\ under NEWLIB (in german)
can be obtained from the DESY computer center.
 
\noindent
The following is a piece of \LaTeX\ to get you started:
\footnotesize
\begin{verbatim}
\documentstyle[dina4h,11pt]{article}   % 
% anything after a % is treated as a comment
\begin{document}
\renewcommand{\Huge}{\huge}         % Otherwise the title is huge
\title{ZEUS note 99-202 \\
A Search for D$^0\rightarrow \ell_1\overline{\ell_2}$} %Greek and maths stuff has to be
\author{A ZEUS member}              % inside $...$
\date {1st April 1999}              % Just \date will give today's date
\maketitle
 
\section{Introduction}
A search was made for the flavour changing neutral current processes 
D$^0\rightarrow\mu^+\mu^-$ and D$^0\rightarrow $e$^+$e$^-$ and the lepton family
violating decay D$^0\rightarrow\mu^{\pm}\mu^{\mp}$.
 
\section{Results}
The following numbers of events were observed :
%
\begin{center}               % Center the table
\begin{tabular}{|l|r|}       % Two columns one left one right adjusted
\hline                       % A horizontal line
Channel & Events \\          % & separates columns \\ ends rows
\hline
D$^0\rightarrow\mu^+\mu^-$         & 3 \\
D$^0\rightarrow $e$^+$e$^+$        & 14\\
D$^0\rightarrow \mu^{\pm}$e$^{\mp}$& 7 \\
\hline
\end{tabular}
\end{center}
 
\subsection{Fitting}
The invariant mass distribution of the di-lepton system was fitted to the form:
%
% This is a so called display formula inside \[ .....\]
%
\[
f(x)=\frac{1}{\sigma\sqrt{2\pi}}e^{-(x-\mu)^2/2\sigma^2}
\]
%
\end{verbatim}
\normalsize
which should come out something like:
\bigskip 
\hrule
\bigskip \begin{center}{\Huge ZEUS Note 99-202}\end{center}
\begin{center}{\Huge A Search for
D$^0\rightarrow \ell_1\overline{\ell_2}$}\end{center} 
\begin{center}{A ZEUS member}\end{center}
\begin{center}{1st April 1999}\end{center}
\begin{flushleft}{\Huge\bf 1 Introduction}\end{flushleft}
A search was made for the flavour changing neutral current processes 
D$^0\rightarrow\mu^+\mu^-$ and D$^0\rightarrow $e$^+$e$^-$ and the lepton family
violating decay D$^0\rightarrow\mu^{\pm}$e$^{\mp}$.
\begin{flushleft}{\Huge\bf 2 Results}\end{flushleft} 
The following numbers of events were observed :
%
\begin{center}               % Center the table
\begin{tabular}{|l|r|}       % Two columns one left one right adjusted
\hline                       % A horizontal line
Channel & Events \\          % & separates columns \\ ends rows
\hline
D$^0\rightarrow\mu^+\mu^-$         & 3 \\
D$^0\rightarrow $e$^+$e$^+$        & 14\\
D$^0\rightarrow \mu^{\pm}$e$^{\mp}$& 7 \\
\hline
\end{tabular}
\end{center}
\begin{flushleft}{\Huge\bf 2.1 Fitting}\end{flushleft} 
The invariant mass distribution of the di-lepton system was fitted to the form:
%
% This is a so called display formula inside \[ .....\]
%
\[
f(x)=\frac{1}{\sigma\sqrt{2\pi}}e^{-(x-\mu)^2/2\sigma^2}
\]
%
\bigskip 
\hrule
\bigskip 
 
%........................................................................

\subsection{Printing \TeX\ files}
\index{Printing!TeX files}\index{TeX!printing}
 
\subsubsection{On IBM/MVS}
 
Once you have written your \TeX\ file type
\begin{description}
\item {\tt GTEX filename} 
\end{description}
to produce a (Device Independent) \ind{DVI file}. A panel will guide you through
the procedure\cite{fussweg}. When first using GTEX overwrite the word {\tt UNDEFINE}
next to PF10 with the numbers 4 and 5 (separated with a blank). Pressing PF10 will
then start conversion of the member whose name is written in the {\tt MASTER MBR}
field. 
(You may have
to repeat this a few times to get the page numbering and internal
cross referencing correct). Press PF17 to print out the text on a laser printer.


\subsubsection{On VXDESY and UNIX}
\noindent
Once you have written your \TeX\ file type
\begin{description}
\item {\tt latex filename} or {\tt tex filename}
\end{description}
to produce a (Device Independent) \ind{DVI file}. You may have
to repeat this a few times to get the page numbering and internal
cross referencing correct. For german hyphenation use the commands 
{\tt glatex} and {\tt gtex} instead. 
 
\noindent
To create a PostScript file type~\cite{dvips}
\begin{description}
\item {\tt \ind{dvips} filename}
\end{description}
and then print the PostScript file as described in
Section~\ref{sect:print}. 
If you want to create only a subset of pages in postscript
and want to specify the output name  use the options
\begin{description}
\item {\tt /OUTPUT=Filename /NUMBER=Maximal\_number\_of\_pages /START=First\_page} (VAX)
\item {\tt -oFilename -nMaximal\_number\_of\_pages -pFirst\_page} (UNIX)
\end{description}
There are many more options available. 

\subsubsection{Writing \ind{DRAFT} over each page}
 
\index{PostScript!writing DRAFT on each page}
\index{TeX!writing DRAFT on each page}
If you are creating a PostScript file you can make it print with
DRAFT diagonally over each page by including the following near the
front of your \TeX\ file.
\begin{verbatim}
\special{!userdict begin /bop-hook{gsave 200 30 translate
65 rotate /Times-Roman findfont 216 scalefont setfont
0 0 moveto 0.93 setgray (DRAFT) show grestore}def end}
\end{verbatim}

\subsection{\ind{Viewing \TeX\ files}}
DVI files (those files that are created  after running the \TeX\ or \LaTeX\ programs)
can be viewed under Dec-windows (VAX) and X-windows using the 
mouse driven previewer {\tt xdvi}.
Type in the command:
\begin{verbatim}
     xdvi file
\end{verbatim}
where {\tt file.dvi} is the dvi file you want to preview.
It has the capability of showing the file shrunken by various factors and also has
a magnifying glass which allows one to see a small part of the unshrunk image.
 
%------------------------------------------------------------------------
 
\section{\label{sect:PostScript}PostScript}

PostScript\index{PostScript}
is a `page description language'. It provides a description of
a complete page at a time rather than one line at a time like a
lineprinter. PostScript is a complete, device and resolution independent,
programming language. PostScript is the ZEUS standard for the transfer
and storage of figures and pictures.
 
\noindent
The following is an example of a piece of PostScript (don't try and
print it because it's not complete!):
\footnotesize
\begin{verbatim}
%! HIGZ/PostScript Metafile
/l {lineto} def /m {moveto} def /t {translate} def
/sw {stringwidth} def /r {rotate} def /rl {roll} def
/d {rlineto} def /rm {rmoveto} def /gr {grestore} def /f {eofill} def
/bl {m dup 0 exch d exch 0 d 0 exch neg d cl s} def
/bf {m dup 0 exch d exch 0 d 0 exch neg d cl f} def
/lw {setlinewidth} def /sd {setdash} def
/s {stroke} def /c {setrgbcolor} def
/cl {closepath} def /sf {scalefont setfont} def
/oshow {gsave [] 0 sd true charpath stroke gr} def
\end{verbatim}
\normalsize
 
%........................................................................
 
\subsection{Generating PostScript files}\index{PostScript!generating
files}
You can generate a PostScript file many ways. Most output files
of word processors and graphics programs can be transformed into PostScript.
In order to turn an ASCII file into PostScript under UNIX, type
\begin{verbatim}
      a2ps ascii_filename > PostScript_filename
\end{verbatim}
This will produce a double page output with an informative border.
\begin{enumerate}
\item In PAW type:
\begin{description}
\item {\tt fortran/file 66 filename.ps}
\item {\tt metafile 66 -111}
\item {\tt h/plot 23}
\item {\tt close 66}
\end{description}
which will put plot number 23 into filename filename.ps.\footnote{If you write
{\tt metafile 66 -113} instead, you will get a so-called \ind{encapsuled PostScript}
file {\tt filename.eps} which can be easily included in documents~\ref{sect:merging}.}
 
\item If you have pictures on a
Macintosh\index{PostScript!converting from a Macintosh} you
first have to get the picture off the Mac.
In system 7 you can choose 
in your print menu (postscript printer has to be selected in the chooser) 
that you would like to have the 
print file stored in a file.
%  You should be able to
%print it as normal (with print spooling off) but just after clicking on
%the PRINT button, hit command-F (command is the funny squiggle character
%on the key board).  The Mac will then say ``writing postscript file
%POSTSCRIPTn''.  This usually ends up in the folder where the program is
%though you may have to use the FIND FILE DA to find it. 
 You can then
transfer the file to other computers by using KERMIT\index{KERMIT} or other
means.
The file is not in normal PostScript but in some strange apple dialect
(it still needs the Appledict dictionary, and the lines are more than 72 
characters long).
It can be printed on Applewriters\index{PostScript!printing on a
Applewriter}.
%  To convert the file to normal PostScript it needs a so called Appledict
%dictionary at the front.  Such a dictionary can be found in the file
%MACTOPS\index{MACTOPS}~PS on the G disk on CERNVM.
%This file has been modified by Al Lee
%to remove some commands that are protected on LN03 printers and to wrap
%the lines at 72 characters to avoid mailer problems.
%  On CERNVM the command :
%  {\tt MACTOPS~myfile~ps}
%will do this conversion for you leaving myfile ps now in standard
%PostScript with a copy of the original as myfile macps.
\end{enumerate}
 
%........................................................................
\subsection{Producing graphics}
\index{postscript!producing graphics}
It is possible to produce graphics in the \TeX\ environment; there exist
e.g. special utilities to produce Feynman diagrams. It is more convenient,
however, to use a graphics program (such as CANVAS on a Mac) and then export
the file in the form of PostScript. Under X-windows a nice utility exists
called {\tt xfig}~\cite{xfig},
which is installed on the ZOW DEC cluster (e.g. in {\tt /usr/local/X11R5/bin}).
The picture
can be exported in many different ways, e.g. as PostScript or \LaTeX\ file.
 

 
%........................................................................
 
\subsection{Displaying PostScript files on a terminal}
\index{PostScript!displaying on a terminal}
 
On a DECwindows VAXstation you can use the `\ind{CDA viewer}', which
can be found in the `applications' menu, to display a PostScript
file on the screen. Another tool you could try is {\tt dxpsview}. Depending on
the setup, you may not be able to view PostScript files.
On UNIX there is a tool called  `ghostview', which is also available on VXDESY
under the command name {\tt gv}. You will find {\tt ghostview} and other 
X11 and gnu utilities
in the directory {\tt /usr/local/X11R5/bin}; its best to include this directory
in your {\tt PATH} variable  (set in {\tt .login} if you are using the c-shell). 
% which can be found in /desy/X11R4/usr/bin/X11/ghostview. 
It provides a 
menu/mouse interface to the {\tt gs} ``ghostscript'' previewer.
%As of now you have to include /usr/local/gnu/bin in your path (or
%create a link  ln -s /usr/local/gnu/bin/gs ~/bin/gs ).
To invoke this interface
give the command:
\begin{verbatim}
     ghostview -a4 filename
\end{verbatim}
Ghostview allows you to browse throught the document and print the document
as a whole or between marked pages. clicking with the middle mouse on one of the 
page numbers will display that page; you can also use the page menu. (Refrain
from playing with the  magstep, orientation and media menus because this may crash the 
program ..)

% maybe you have to select in .Xdefaults Ghostview.useBackingPIxmap:false

 
%........................................................................
 
\subsection{\label{sect:merging}Merging PostScript figures with \TeX}
 
Merging graphics\index{PostScript!merging with \TeX}
\index{TeX!merging with PostScript}
with \TeX\index{TeX}
output is possible by importing
an {\sl encapsulated} postscript file into the final postscript file.
An encapsulated postscript\index{PostScript!encapsulated} file (EPS)
differs from a regular postscript file (PS)
in that it contains the following lines at the beginning of the
file,
$$
\vbox{\halign{\tt#\hfil\cr
\%!PS-Adobe-2.0 EPSF-2.0\cr
\%\%BoundingBox: 0 185 595 516\cr}}
$$
where the parameters to the {\tt \ind{Boundingbox}} specify
the coordinates
of the bottom left and upper right corners of a box that would
encompass the figure.
The units in the bounding box are points (2.835~points/mm) and are measured from the
bottom left hand corner of the page.
You can make an EPS file by adding these two lines
to an existing PS file.
 In addition, EPS files miss a {\tt showpage} command
towards the end of the file. 

 Encapsuled postscript files produced by drawing 
programs contain the BoundingBox information already. In order to get the
dimensions of the BoundingBox, print the PostScript file, and draw a rectangle 
around the picture. More information can be found in~\cite{texatcern} which also 
includes a translation table between ``big points'' and mm. 

The file type {\tt eps} should be used to distinguish it from
a regular postscript file.
Note that most printers will not print encapsulated PostScript files since the showpage
command is missing (some older printers will also have problems with {\tt eps} files
imbedded in documents).
 
% \noindent
% Because encapsulated PostScript files are harder to print everywhere
% it is recommended to do the following. Work on VXDESY and put the
% following into your LOGIN.COM
% \begin{description}
% \item {\tt {\$} @DISK{\$}ET:[TEX]CERNTEX}
% \end{description}
 
\noindent
To include pictures in your document add ``epsf'' to the
\verb+\documentstyle+ line e.g.
\begin{verbatim}
\documentstyle[12pt,epsf]{article}
\end{verbatim}
and then include the picture something like
\footnotesize
\begin{verbatim}
\begin{figure}[h]
\epsfysize=20cm
\epsffile[120 210 500 600]{mypicture.ps}
\caption{\label{fig:myfig}Gosh am I proud I can put pictures into \TeX\ !}
\end{figure}
\end{verbatim}
\normalsize
The arguments of the \verb+\epsffile+ command are the boundingbox
parameters, which you don't have to give if the file is of type {\tt eps}.
However, as you can see, the file itself doesn't have to be in encapsulated
PostScript. It will be scaled to fit in the space specified by
the \verb+\epsfysize+ (or \verb+\epsfxsize+) command.

There are other ways to include postscript figures, eg. using the {\tt psfig}
macros~\cite{psfig}. In this case your code would look somewhat like this:
\footnotesize
\begin{verbatim}
\documentstyle[12pt,psfig]{article}
..
\psfig{figure=mypicture1.eps}
\centerline{\psfig{figure=mypicture2.eps,height=1.5in}}
\\psfig{figure=mypicture2.ps,bbllx=120,bblly=210,bburx=500,bbury=600}
\end{verbatim}
\normalsize
Here the first two pictures are encapsuled PostScript files; in the second case the
picture is put in the center and shrunk so that its height is 1.5 inches. In the 
third case, a plain PostScript file is used and the BoundingBox information is given
in the {\tt psfig} command. Note that there should not be any blanks in the 
psfig command line!
%-----------------------------------------------------------------------
\chapter{Physics analysis in ZEUS}
\section{Rules for physics analysis in ZEUS}
\label{sect:zeusrules}
\index{Analysis!rules}
This set of rules are copied from ZEUS Note 93-129.
\subsection{Physics coordinators}
For each physics topic there should be a {\it Physics Coordinator\/} and a deputy.
The physics coordinators (and the deputies) are appointed for one year. The physics
coordinator needs to be resident at DESY during that time. She/he is responsible for
ZEUS being able to perform the complete physics analysis for her/his topic. The
physics coordinators are member of COOR. The group of physics coordinators is chaired
by the {\it Physics Chairperson\/}.

Exofficio members of the group of physics coordinators are the coordinators for
\begin{itemize}
\item event processing
\item standard ZEUS off-line code
\item analysis environment
\item Monte Carlo
\item trigger
\end{itemize}
and possibly others.

Furthermore the Physics Chairperson makes sure that necessary analysis tools such as
lepton recognition, cluster algorithms, track following through several components
etc. are available in time.

The Physics Coordinator should strive to have in her/his subgroup a widespread
participation from the institutions and detector components of ZEUS. 

The Physics Coordinator and the deputy will make an effort to engage everyone who
wants to contribute to a given topic and to maintain the dialogue within the subgroup
on a scientific level.

Two independent analyses should be performed for each topic. 

All analyses must be documented by an internal note prior to publication so everyone
can see what was actually done.
\subsection{Physics groups}
Participation in any of the physics groups is open to all members of the
collaboration. 

Members of the collaboration are free to start their own analysis and analysis group.
The Physics Chairman should be informed of such activities at an appropriate time.


\subsection{Openess / secrecy}

Everyone in the collaboration has free and full access to the data. Code developed
within ZEUS for analysis of ZEUS data should be accessible to all members of the
collaboration. Before using the code, the author of the code must be asked for
permission. 

Physics analyses in progress, which is everything that has not yet been published or
presented at a conference, must not be disclosed to non-members of the collaboration.

\subsection{Publications}


Steps to be taken towards publication of a paper:
\begin{itemize}
\item The authors are encouraged to present their analysis first to the appropriate
working group. The authors present the content and thrust of the paper together with 
the figures at the ZEUS Weekly. They also document the analysis including technical
details in a ZEUS note and have it distributed.
\item A predraft of the paper is given to the Editorial Board. At this point 
the analysis as well as the predraft should be considered final by the authors.
\item The Editorial Board meets within a week to discuss the predraft. Several
iterations may be necessary to arrive at the final draft, where final means that in
the view of the Editorial Board it is ready for publication. If necessary, other 
members of the collaboration with particular expertise should be consulted by the
Editorial Board.
\item The draft is distributed within the collaboration.
\item Comments are given in writing to the authors, and a copy to the Editorial 
Board. These comments have to be answered by the authors in written form. Again, 
copies of the answers are given to the Editorial Board.
\item The Physics Chairperson should, if necessary, ensure a timely completion of the
process.
\item Each paper will have at least one public reading in the collaboration. The 
{\t on-site representatives \/} of the groups are responsible for informing their group 
members at home about the paper. Several readings may be necessary before agreement for 
publishing the paper is reached. A deadline will be set for raising objections. After the 
objections have been satisfied and the paper has been accepted by the collaboration, the paper
will be sent off for publication. In case of urgency, the Spokesperson is entitled to 
speed up the procedure in a suitable way.
\end{itemize}
\subsection{Editorial Board}
The Editorial Board consists of the following members:
\begin{itemize}
\item ex officio:
\subitem Physics Chairperson (chairperson of the Editorial Board)
\subitem the authors
\subitem the corresponding physics coordinator and deputy
\item plus:
\subitem two members of the collaboration with expert knowledge on parts of the 
analysis
\subitem two other members of the collaboration
\end{itemize}
The latter four persons are chosen by the physics chairman in consultation with
the spokesperson.



A directory of authors for ZEUS publications is kept at the ZEUS secretariat. The ZEUS
contact persons are responsible for keeping the author list and the list of persons to
be acknowledged up to date as far as their institute(s) is (are) concerned.

As a guideline, newcomers should be on the author list beginning 6 months after
joining the collaboration and no longer than 12 months after leaving the
collaboration.
However, authors who have contributed in a major way to the development of the
experiment, are kept on the author list for an appropriate lenght of time, as decided
by the corresponding ZEUS contact person.

A new group should be included in the author list beginning 6 months after joining the
collaboration.
For publications of the collaboration, the authors are listed under their institutes.
The list of institutes and authors is in alphabetic order.

\subsection{Talks on the ZEUS experiment}

All international conference talks solely on the ZEUS experiment must be cleared with
the Spokesperson. Speakers for ZEUS talks at international conferences or workshops
are chosen by the collaboration except where a
member has received a personal invitation. In the latter case the speaker should inform
the ZEUS Spokesman right away.
 Talks at large accelerator centers
must be cleared with the Spokesperson.

Presentations of unpublished material must have been previously approved by the
collaboration at the Weekly Meeting or at a similar meeting.

For talks with speakers chosen by the collaboration, the speaker will ensure that a
copy of the transparencies is distributed as a ZEUS note. A written version of a talk
to be published, e.g. in conference procedings, needs to be approved by the
Physics Chairperson or the Spokesperson 
prior to submission for publication and circulated as a ZEUS note.

A directory of talks with the speakers chosen by the collaboration is kept by the ZEUS
secretariat and is freely available to the collaboration.

\subsection{Files kept by the ZEUS secretariat}

The ZEUS secretariat keeps files with 
%\hline
\begin{indentlist}{9cm}{9.25cm}
\indentbf{ZEUS author list} contact persons of the institutes
\indentbf{List of speakers/talks} Spokesperson
\indentbf{Copy of transparencies of ZEUS talk} Physics Chairperson
\indentbf{Copy of written version of ZEUS talk} Physics Chairperson
\indentbf{List and a file of copies of ZEUS thesis} contact persons of the institutes
\indentbf{List of job openings in the collaboration} contact persons of the institutes
\end{indentlist} 
The people responsible for keeping the lists up-to-date are listed at the right. 
\section{Guidelines for writing ZEUS papers}
\index{Papers!guidelines for writing}
 
In writing an analysis
paper, all rules of good technical writing apply.
Papers should be complete, accurate, must be written in
correct language and edited for clarity and readability.
Use familiar words that are equally effective as uncommon ones;
don't use too many words if a few can do, avoid difficult
art work that does little more than ``show off".
Eliminate
repetitions. Write in complete sentences (aha!).
Think twice if you want to emphasize text by
italicizing; it is an effective way to get attention but
can be distracting if used too often.
Remember that sentences become more readable if the part that the
author would like to have ``underscored" is at the end. Some people advice 
to think twice if one is to use verbs stemming from `to have' or `to be'; they 
suggest to use 
more precise verbs instead.
 
\noindent
Since ZEUS is a large collaboration of people with different
backgrounds and style preferences,
we avoid giving firm rules but stress the necessity
of consistency and clarity.
\begin{itemize}
\item
Be consistent in the spelling (British or American English) and
in the
choice of tense.
\item
Also be consistent
in the choice of units (ZEUS publications use $c=1$ throughout),
in the use of symbols and
in capitalizing
words (Fig., Standard Model etc.) or titles.
\item
Do not introduce unnecessary symbols just as shorthand. If a
symbol is only used once or a few times in the text then substitute
words instead [e.g. HES (hadron-electron separator), c.m.
(centre-of-mass), d.o.f (degrees of freedom)].
Also do not use the same symbol for different meanings in the same
paper or even in two closely related papers. Avoid over-complicated
symbols with multiple superscript, subscripts and arguments where
a simpler symbol would suffice.
\item
Do not use jargon words or phrases which are in common use within
ZEUS or among specialists but which are likely to be confusing
for the wider high energy physics community.
Do not assume that the reader is familiar with HERA physics and has
knowledge of previous related papers.
\item
Check that the references are correct. Often
copying somebody else's reference only propagates errors. Reference
journal papers, if available, rather than a preprint. Do not use
references which are unlikely to be available to the average reader,
such as internal notes.
\item
Use
a spell checker program, if available.
\end{itemize}
If you really long for recommendations, here they are:
following the practice of Physics Letters and Zeitschrift
f\"ur Physik we recommend British English spelling and
refraining from capitalizing all nouns, verbs and adjectives in titles.
To be consistent with Physics
Letters we recommend the use of lower case for
references to figures (fig.) and tables (table).
 
\section*{Technical rules}
 
ZEUS physics papers that fit in the form of a Letter are submitted to
Physics Letters B. Zeitschrift
f\"ur Physik C could serve as a journal for longer papers.
Both journals provide instructions for authors, which can be found in
the last issue of a volume. However, 
the publishers have recently shown considerable
flexibility. This is in particular true for Physics Letters
whose publishers
nominally accept only papers
with less than four journal pages
and less than 60 words in the abstract.
Concerning figures, both journals accept good original laser printer
copies. After reduction, the smallest letter size should be around
1.8 - 2.0 mm. Figure captions should be collected on a separate sheet
and information in the captions should not be repeated in the text.
The two journals have different rules for citation of literature
references (see below).
 
\noindent
Both journals require one original single sided
typescript
and two copies for the referees. The submission
of the paper to the journal is done by the ZEUS secretariat.
Physics Letters asks for the TeX file of the paper once
the comments of the referees have been included.
 
\noindent
ZEUS has not yet establish 
technical rules concerning the text part and the figures of a 
ZEUS paper. Nethertheless I suggest the following rules, part of which are 
based on CERN recommendations, for the text of the document.

\begin{itemize}
\item
Papers and physics notes are recommended to be written in \LaTeX\ (\TeX\ ).
\item
The paper should contain the latest author list and acknowledgements
section
(ask ZEUS secretariat for details).
\item
I suggest to follow the rules on the use of roman and italics fonts
for symbols, established by CERN
(CNL 202-5.2).
The roman font should be used for the following
families of symbols:
\subitem 
Names of units, such as MeV, cm etc.
\subitem 
Particle names such as ``Z$^0$'' or ``e$^+$''
and  names of chemical elements.
\subitem 
Numbers and abbreviations.
\subitem 
Mathematical functions such as ``$\sin$'' or ``$\ln $''
(use  \verb+\sin+ and \verb+\ln+).
\subitem 
The ``d" symbol for the derivative.
\item
On the other hand, an italics font should be used for
constants and variables such as $\hbar$ and $ y_{cut} $.
\item
The degree symbol $^\circ $ is best approximated by \verb+$^\circ$+ and
the symbol for leptons is ``$\ell$'' (\verb+$\ell$+).
\end{itemize}
 
\noindent
Examples that follow the rules given above are
$m$(Z$^0$) = $91.165\pm 0.009 $ GeV/$c^2$ or $p$($\bar{\rm p}) >
2 $ GeV/$c$.
 
\noindent
Note that these rules
happen to be the same as the ones followed by
Physics Letters. However, they differ from those
used by Zeitschrift f\"ur Physik.
 
\noindent
Additional suggestions can be made
for figures and pictures.
\begin{itemize}
\item
It is highly recommended to figures 
available in form of PostScript files so that the figures can be electronically stored
and sent to the ZEUS institutes.

\item
Do not use too small a font for the numbering
or labeling.
For better recognition, mark ``ZEUS'' on the figure
if ZEUS data are shown. Both axis should be labeled and
units given.
\item
Use a solid dot for ZEUS data points if possible.
\item
Check consistency of labeling between figures and text.
\item
Physics Letters and Zeitschrift f\"ur Physik do not require
glossy prints for figures; make sure that the figures
sent to the publishers are good quality laser printer originals
or excellent photocopies.
\end{itemize}
 
\noindent
Physics Letters and Zeitschrift f\"ur Physik have different rules
for citing literature references.
Examples for Physics Letters are:
\begin{itemize}
\item
     ZEUS Collab., A.A. Anton et al., Phys. Lett. B 999 (1998) 497.
\item
    G. Altarelli in: Physics at  HERA, eds. W. Buchm\"uller and G. Ingelmann,
    Vol 2 (DESY, 1992)  p. 379.
\end{itemize}
 The corresponding examples for Zeitschrift f\"ur Physik are:
\begin{itemize}
\item
     ZEUS Coll., A.A. Anton et al.: Phys. Lett. B999 (1998) 497
\item
    G. Altarelli  In: Physics at HERA, W. Buchm\"uller and G. Ingelmann (eds.),
    Vol.2, DESY,  (1992) p. 379
\end{itemize}
Note that neither journal requires using italics for
``et al.'' or bold face for
the volume numbers. If the paper is signed by less
than five authors all names and initials should be given.
 
\noindent
In most cases, Physics Letters and Zeitschrift f\"ur Physik
use the same abbreviations for journals. Abbreviations for common
journals, as used by Physics Letters, are listed below.
\begin{itemize}
\item
  Phys. Lett. 57 B
\item
  Phys. Rev. Lett 52
\item
  Phys. Rev. D 15
\item
  Nucl. Phys. B 294
\item
  Nucl. Instrum. Methods A 180
\item
  Z. Phys. C 37
\item
  Comput. Phys. Commun 39
\item
  Phys. Rep. 97
\end{itemize}
Zeitschrift f\"ur Physik likes itself to be cited as
``Z. Phys. C - Particles and Fields ''  and they do not
use blanks between the volume number and the journal
series letter (e.g. Phys. Lett. 57B).
 
\noindent
Both journals do not capitalize titles and use British
English
spelling. Physics Letters use lower case for references to
figures (e.g. fig. 8a) while Z. Phys. C uses
upper case. The latter journal also drops periods at the
end of figure and table captions and reference citations.
 
\appendix
 
%========================================================================
 
\chapter{ZEUS coordinate system}
 
%------------------------------------------------------------------------
 
\index{ZEUS!coordinate system}
\index{Coordinate system}
 
The ZEUS \ind{Master Reference System} is a 3D Cartesian Coordinate
System whose origin is at the center of the CTD and has
z-axis along the nominal proton beam direction (this is anticlockwise
around HERA when viewed from above), has x-axis horizontal and directed
towards the centre of HERA and y-axis normal to the z-x plane (pointing in the sky).
Since the z-axis is inclined by roughly 5.8 mrad with respect to the horizontal
(the protons are ``falling down''), it follows that the y-axis will be similarly
inclined with respect to the vertical.

There is also a set of accepted geographic labels as follows:
\begin{indentlist}{5cm}{5.5cm}
\indenttt{FORWARD, EAST} z-direction (proton direction)
\indenttt{BACKWARD,WEST} -z-direction (electron direction)
\indenttt{NORTH} inside of ring (larger part of ZEUS hall)
\indenttt{SOUTH} outside of ring (smaller part of ZEUS hall)
\end{indentlist}
Note that the geometers often use a different coordinate system which does not 
follow the inclination of the beamline and has different orientation.

ZEUS is installed in the south Hall (Halle S\"ud). HERA has their own jargon 
when talking about locations in the HERA tunnel. Their coordinate system  lies in the 
center of the ring so when they say `SOUTH LEFT' they mean, looking from above,
a tunnel section extending to the east of the ZEUS hall.
   
\noindent
\begin{figure}[h]
\epsfxsize=14cm
\centerline{\epsffile{/users/koepke/texfiles/coordinates.eps}}
\caption{\label{fig:coor}The ZEUS coordinate system}
\end{figure} 
%........................................................................
\chapter{Details on transferring files}
\index{Details on transferring files} 

\section{Nomenclature}
\begin{indentlist}{2.5cm}{2.75cm}
\indentitem{Hostnames} Varies depending upon transport system used,
             remote\_host and local\_host:
\begin{itemize}
\item  for DECNET use names such as {\tt VXDESY} or {\tt DSYIBM}
\item  for TCP/IP use Internet ``dotted'' form such as 131.169.42.64
               or mnemonic equivalent such as zow01.desy.de
\item  for BITNET use mnemonic names such as 
{\tt DHHDESY3}, {\tt DESYVAX}, {\tt CERNVM}, {\tt UVVM}, {\tt DFRRUF1}.
% \item  for CBS(NIFTP) use JANET dotted address, such as UK.AC.BHAM.PH.V   
\end{itemize}
          Notes:
\begin{enumerate}
\item For TCP/IP the dotted form starts with the country while the mnemonic form 
ends with the country!
\item BITNET is a queue based systems, which will retry in
   the event of failure and the transfers are performed for you by some
   server. DECNET and TCP/IP are normally point-to-point transfers,
            which are run by the user that issues the command.
% \item CBS(NIFTP) is soon to be obsoleted.
\end{enumerate}
\indentitem{Filenames}
     File specified in appropriate syntax for given operating system,
             remote\_file and local\_file:
\begin{itemize}
\item   VAX/VMS   use  {\tt fn.ft;n} (where {\tt fn} is the file name, {\tt ft} is
the file type and {\tt n} is the version number
\item   Unix  use any character string, (including unprintable chars!)
\item   VM/CMS   use  {\tt fn ft} if transfer is from IBM to IBM via BITNET or
              CBS(NIFTP), or for the local\_file specification when
              initiating file transfers from an IBM via
              DECnet/Interlink. In all other cases, use form {\tt fn.ft} 
\item   VM/MVS use '{\tt userid.fn.ft}' in quotes if the file is not yours.
\item VMS does not allow more than one ``.'' in a file name. So the file 
\footnotesize
\begin{verbatim}
       F1XYZT.DATA.MOZART.NC.FZ
\end{verbatim}
\normalsize
 on the DESY IBM will get the INTERNET
filename 
\footnotesize
\begin{verbatim}
       DSIBM::[F1XYZT.DATA.MOZART]NC.FZ
\end{verbatim}
\normalsize
\end{itemize}
\indentitem{Devices}   VAX/VMS only.
       Logical name for disk normally, eg. DISK{\$}ANY
 
\noindent
Notes:
\begin{enumerate}
\item  For vaxes, local file specification can also include
        device/host but for brevity these are omitted below.
\end{enumerate}
\indentitem{Userids}
Restrictions vary between different operating systems,
 
             passwords:
\begin{itemize}
\item  VAX/VMS up to 31 alphanumeric chars, plus \$ and \_,
       case insensitive.
\item  VM/CMS and VM/MVS? up to 8 alphanumeric characters, case insensitive.
\item  Unix few restrictions, often require a numeric or special
                          character, case sensitive.
\end{itemize}
             user:
               Again, varies with system and preference of system manager.
                          CMS always allowes maximum of 8 characters.
 
          Notes:
\begin{enumerate}
\item  `user' and `pass' will always be used to refer to an account on a
         remote\_host.
\item   When using Interlink/DECNET to IBM, all passwords (including VAX
        ones) have to obey the IBM password restriction of 8 characters
        maximum.
\end{enumerate}
\end{indentlist}
 
%........................................................................
 
\section{Working on a VAX}
 
The various transfer methods are available in `command line' and dialog
forms in all cases.  Command line forms are given below, but typing any
of FTP, TRANSFER or COPY should prompt you for the required information.
Multinet is the
normal flavour of TCP/IP in use on VAXes at DESY. 
 
\subsection{Sending from VAX to VAX}
\index{Transferring files!from VAX to VAX}
      [via DECNET]
\footnotesize
\begin{verbatim}
           COPY  local_file remote_host'user pass'::dev:[user]remote_file
               (any file format)
\end{verbatim}
\normalsize
      [via TCP/IP]
\footnotesize
\begin{verbatim}
           FTP/USER=user/PASS=pass remote_host PUT local_file remote_file
               (default is ASCII. Need /TYPE=IMAGE for binary.)
\end{verbatim}
\normalsize

\subsection{Sending from VAX to Unix}
\index{Transferring files!from VAX to Unix}
      [via TCP/IP]
\footnotesize
\begin{verbatim}
           FTP/USER=user/PASS=pass remote_host PUT local_file remote_file
               (Default type is ASCII; need /TYPE=IMAGE for binary.)
\end{verbatim}
\normalsize
\subsection{Sending from VAX to IBM/VM}
\index{Transferring files!from VAX to IBM/VM}
      [via DECNET/Interlink]
\footnotesize
\begin{verbatim}
               Transfer to minidisk user cuu.
           COPY local_file remote_host"user pass"::CMS:[user.cuu]remote_file
               (default is ASCII.)
\end{verbatim}
\normalsize
To transfer non-ASCII files, or to preserve record formats,
qualifiers are required as below (e.g. to transfer binary exchange
format (FZ) file),
\footnotesize
\begin{verbatim}
           COPY local_file -
           remote_host"user pass"::"CMS:[user.cuu]remote_file/IMAGE/FIXED:3600"
               (IMAGE specifies binary and FIXED the record length in bytes.)
\end{verbatim}
\normalsize




%To transfer to a user's RDR, use the format,
%\begin{verbatim}
%           COPY local_file remote_host"user pass"::RDR:[user]remote_file
%\end{verbatim}
%(Qualifiers may be appended to remote\_file as above.)

 
\noindent
%Note:
%\begin{enumerate}
%\item Access control restrictions vary with Interlink configuration
%      of the remote host so sending files to remote use disks may
%      not be possible. 
%\item The parameter "CMS" may be omitted as it is the default.
%\end{enumerate}
      [via TCP/IP]
\footnotesize
\begin{verbatim}
           FTP/USER=user/PASS=pass remote_host PUT local_file remote_file
               (default is ASCII; need /TYPE=IMAGE for binary; /STRUCTURE=?)
\end{verbatim}
\normalsize
 
\subsection{Receiving to VAX from VAX}
\index{Transferring files!from VAX to VAX}
      [via DECNET]
\footnotesize
\begin{verbatim}
           COPY remote_host'user pass'::dev:[user]remote_file local_file
               (any file format)
\end{verbatim}
\normalsize
      [via TCP/IP]
\footnotesize
\begin{verbatim}
           FTP/USER=user/PASS=pass remote_host GET remote_file local_file
               (default is ASCII. Need /TYPE=IMAGE for binary.)
\end{verbatim}
\normalsize
\subsection{Receiving to VAX from Unix}
\index{Transferring files!from Unix to VAX}
      [via TCP/IP]
\footnotesize
\begin{verbatim}
           FTP/USER=user/PASS=pass remote_host GET remote_file local_file
               (default is ASCII; need /TYPE=IMAGE for binary)
\end{verbatim}
\normalsize
\subsection{Receiving to VAX from IBM/VM}
\index{Transferring files!from IBM/VM to VAX}
      [via DECNET/Interlink]
\begin{verbatim}
           COPY remote_host::[user.cuu]remote_file local_file
\end{verbatim}

 
\noindent
Transfer of non-ASCII or structured files is similar to copying from
IBM as given above, e.g. for FZ file,
\footnotesize
\begin{verbatim}
           COPY remote_host::"[user.cuu]remote_file/IMAGE/FIXED:3600"
                                                           local_file
\end{verbatim}
\normalsize
      [via TCP/IP]
\footnotesize
\begin{verbatim}
           FTP/USER=user/PASS=pass remote_host GET local_file remote_file
               (default is ASCII; need /TYPE=IMAGE for binary; /STRUCTURE=?)
\end{verbatim}
\normalsize

%In order to copy files from a disk that is not remote\_user 191, you
%specify user as \verb!"user//cuu"!, where cuu might be  e.g. 192 (the
%quotes are required).
 subsection{Receiving to VAX from IBM/MVS}
\index{Transferring files!from IBM/MVS to VAX}

This is an example of tranfering and FZ file via ftp. From VXDESY type:
\footnotesize
\begin{verbatim}
    ftp mvs
    user username password
    binary
    get remote_file_name local_file_name
    bye
    file/recl=3600 local_file_name
\end{verbatim}
\normalsize
Note that the {\tt file} command has to be invoked  to change the file format.
You can tranfer files from your own account on MVS using the comannd
\footnotesize
\begin{verbatim}
    dataFromIBM (@dir$util:dataFromIBM.com)
\end{verbatim}
\normalsize
Internet can also be used to transfer files from the IBM to VMS
if you have an account on the IBM and the necessary permission. It is highly 
recommended to to first look at the VMS help ({\tt HELP INTERNET}).
To list a directory on the DESY IBM type:
\footnotesize
\begin{verbatim}
   DIR DSYIBM::
\end{verbatim}
\normalsize
(the double colon is necessary). To copy, e.g. an FZ binary file from IBM/MVS to 
the user scratch area on the VAX, type:
\footnotesize
\begin{verbatim}
 COPY DSYIBM::"[ F1XYT.DATA.MOZART]NC.FZ/IMAGE/FIXED:3600" WEEKU:
\end{verbatim}
\normalsize .

\subsection{Receiving to IBM/MVS  from VAX}
\index{Transferring files!from VAX to IBM/MVS}

The file space used on IBM/MVS has to be allocated before the transfer starts.
The space needed can be calculated by the following formula:
\[
    N_{tracks} = {\rm file size [bytes]} / 21600 / 2
\]
where 21600 for the blocklength on the DESY IBM is used and  there 
are 2 blocks per track. The total number of tracks needed should be split between 
a primary allocation and up to 15 times a secondary allocation.
Use the command 
\begin{verbatim}
    data2ibm (@dur$util:data2ibm.com)
\end{verbatim}
to do transfers ZEBRA exchange format filetransfers to your own account on IBM/MVS.

When using  INTERNET to IBM/MVS, one first has to know the size of the file to be
transferred. INTERNET uses the qualifier {\tt /ALLOC:nnnnn} to transfer this 
information, which can be extracted from the directory listing. Then following 
file will copy the FZ binary  
file {\tt MC\_NC\_X01\_Y02.FZ;1} from the user scratch area on the 
VAX to the IBM file {\tt F1XYZT.MC.NC.X01.Y02.FZ}:
\footnotesize
\begin{verbatim}
 COPY WEEKU:MC_NC_X01_Y02.FZ;1 -
 DSYIBM::"[F1XYZT.MC.NC.X01]Y02.FZ/IMAGE/FIXED:3600/ALLOC:nnnnn"
\end{verbatim}
\normalsize
where {\tt nnnnn} has to be chosen to be as least as large as the VAX filesize.

%........................................................................
 
\section{Working on a Unix machine}
 
The ftp program, which is normally running TCP/IP, is run in a dialog
form which is very similar to that for TCP/IP running under VMS and CMS.
There is a useful online help available within ftp on most systems, which
you can access by typing `help' (lowercase) or `?'.  Once connected to a
remote host, lists of files in a given directory can be obtained,
multiple transfers (including the use of wildcards) can be made and so
on.  Default login accounts for commonly used remote hosts can be stored
in a file .netrc on the user's home directory. The
following notes apply to use of TCP/IP in dialogue form under Unix,
VM/CMS and VAX/VMS.  A few simple commands that are useful when running
the ftp program are given below.
\index{UNIX!useful commands}
\begin{indentlist}{3.0cm}{3.25cm}
\indenttt{cd dir} - change directory, where `dir' is a normal VMS or
                 Unix directory
                 or just remote\_user (in general remote\_user.cuu) on an IBM.
\indenttt{ls}     - list files (briefly),
\indenttt{dir}    - list files (details of file size, creation dates, etc.),
\indenttt{mget list} - get all files in list (eg *.cards),
\indenttt{mput list} - send all files in list (eg *.cards),
\end{indentlist}
 On some systems, you are given the option of having
 remote\_user = local\_user
 prompted by a carriage return rather than having to specify
 `user remote\_user'.
The IBM/MVS filename has to be given in single quotes if it is not belonging to 
your own account and you have to specify the IBM account name as the first 
directory name (separated by dots).

If you want to send a binary file specify {\tt binary} befor issuing the `{\tt get}'
or `{\tt put}' commands.
 
\subsection{Sending from Unix to VAX, Unix and IBM}
\index{Transferring files!from Unix to VAX}
\index{Transferring files!from Unix to Unix}
\index{Transferring files!from Unix to IBM}
      [via TCP/IP]
\begin{verbatim}
           ftp remote_host
           user remote_user
           (prompted for password, input concealed)
           put local_file remote_file
           quit
\end{verbatim}

 
\subsection{Receiving to Unix from VAX, Unix and IBM}
\index{Transferring files!from VAX to Unix}
\index{Transferring files!from Unix to Unix}
\index{Transferring files!from IBM to Unix}
      [via TCP/IP]
\begin{verbatim}
           ftp remote_host
           user remote_user
           (prompted for password, input concealed)
           get remote_file local_file
           quit
\end{verbatim}

\section{Transferring (PAW) Random Access files}
\index{Transferring files!Random Access files (PAW}
The exchange of random access files such as histogram files is described in detail
in the HBOOK manual~\cite{hbook_guide}.
Random Access files can be copied from one machine to another by explicit
conversion in a sequential file or by an automatical conversion using 
``remote tools'' (\ind{zftp}).

The commands {\tt rtoa} and {\tt rtox} allow you to transform a RZ file into 
an alphanumeric or exchange format file, respectively. Accordingly there exist 
commands {\tt rfra} and {\tt rfrx} to revert the transformation. 

The authors of HBOOK, instead recommend to use the ZFTP environment to 
transfer or convert files. Type
\begin{verbatim}
   zftp
\end{verbatim}
and you enter the ZFTP environment (managed via 
{\tt KUIP}). Type {\tt help} and you will
eventually get a list of all available commands. 
{\tt PUTRZ} will transfer a local RZ to a remote R file; {\tt GETRZ} will do the 
reverse (You will first have to {\tt OPEN} the connection to the remote computer).
With {\tt RFRF} you can convert an RZ file into an FZ exchange format 
file, and again the reverse can be done with {\tt RTOF}. ZFTP used to be rather 
unstable when  tranferring large RZ files; if that problem persists, a file 
conversion should be made first.

%------------------------------------------------------------------------
\chapter{Particle codes}
%------------------------------------------------------------------------
\index{Particle Codes}
The Particle Data Group particle codes are given in the
1988 Review of Particle Properties\cite{pdg}.
Briefly mesons are represented by the form
NML and baryons by NMKL where N, M and K are the quark numbers
(1=d, 2=u, 3=s, 4=c, 5=b, 6=t) and L=2J+1 where J is the spin. K short
and K long are exceptions being 310 and 130. The quarks are in
decreasing mass order from left to right except that Lambda (3122)
has the order switched to distinguish it from Sigma (3212). The fifth
digit is used to distinguish particles with the same spin and
quark content.
Particles have positive numbers, antiparticles have the negative of
their counterparts. The positive kaon and positive B meson are
particles.  The electron, electron neutrino, negative muon etc are
11, 12, 13 etc.  The gluon, photon, Z, and W are 21, 22, 23 and 24.
In hadronic interactions
GEANT is liable to produce light nuclei which do not have standard
PDG codes.  They are therefore arbitrarily assigned the values
95 (deuteron) 96 (triton) and 97 ($\alpha$-particle).
 
\noindent
Internally
GEANT uses different codes as shown below.
 
\begin{center}
\begin{tabular}{|c|c|c||c|c|c|}
\hline
GEANT Code & PDG Code & Particle &
GEANT Code & PDG Code & Particle \\
\hline
1     & 22       & $\gamma$      &
25    & -2112    & $\overline{\rm n}$    \\
2     & -11      & e$^+$         &
26    & -3122    & $\overline{\Lambda}$  \\
3     & 11       & e$^-$         &
27    & -3112    & $\overline{\Sigma}^-$ \\
4     & 12,14,16 & $\nu$         &
28    & -3212    & $\overline{\Sigma}^0$ \\
5     & -13      & $\mu^+$       &
29    & -3112    & $\overline{\Sigma}^+$ \\
6     & 13       & $\mu^-$       &
30    & -3322    & $\overline{\Xi}^0$    \\
7     & 111      & $\pi^0$       &
31    & -3312    & $\overline{\Xi}^+$    \\
8     & 211      & $\pi^+$       &
32    & -3332    & $\overline{\Omega}^+$ \\
9     & -211     & $\pi^-$       &
33    & -15      & $\tau^+$              \\
10    & 130      & K$^0_{\rm L}$ &
34    & 15       & $\tau^-$              \\
11    & 321      & K$^+$         &
35    & 411      &  D$^+$                 \\
12    & -321     & K$^-$         &
36    & -411     & D$^-$                 \\
13    & 2112     & n                  &
37    & 421      & D$^0$           \\
14    & 2212     & p                  &
38    & -421     & $\overline{\rm D}^0$ \\
15    & -2212    & $\overline{\rm p}$ &
39    & 431      & D$_{\rm s}^+$          \\
16    & 310      & K$^0_{\rm S}$      &
40    & -431     & $\overline{\rm D}_{\rm s}^-$ \\
17    & 221      & $\eta$             &
41    & 4122     & $\Lambda_{\rm c}^+$   \\
18    & 3122     & $\Lambda$          &
42    & 24       & W$^+$             \\
19    & 3222     & $\Sigma^+$         &
43    & -24      & W$^-$              \\
20    & 3212     & $\Sigma^0$         &
44    & 23       & Z$^0$            \\
21    & 3112     & $\Sigma^-$         &
45    &          & d                       \\
22    & 3322     & $\Xi^0$            &
46    &          & t                       \\
23    & 3312     & $\Xi^-$            &
47    &          & $\alpha$                \\
24    & 3332     & $\Omega^-$         &
48    &          & G$\nu$                  \\
\hline
\end{tabular}
\end{center}
 
%========================================================================
\chapter{Glossary}
\index{Glossary}

\begin{indentlist}{4.0cm}{4.25cm}
\indentbf{Access permission} Permission to {\em read} from, {\em write} to, or
{\em execute} a file (UNIX).
\indentbf{ADA} Realtime programming language.
\indentbf{ADAMO} {\bf A}leph {\bf DA}ta {\bf MO}del; a software tool to handle data
according to the entity-relationship model.
\indentbf{Alphanumeric character} A-Z lower and uppercase + 0-9 inclusive.
\indentbf{AIDA} Alternative to PAW based on access to ADAMO tables.
\indentbf{ARE} {\bf A}nalyse, {\bf R}eset, {\bf E}rror-board; a module inside the CSB.
\indentbf{ASCII} {\bf A}merican {\bf S}tandard {\bf C}ode for {\bf I}nformation 
{\bf I}nterchange using 7 bits for letters, numbers, punctuation and control characters.
\indentbf{ASIC} {\bf A}plication {\bf S}pecific {\bf I}ntegrated {\bf C}ircuit.
\indentbf{BAC} {\bf BA}cking {\bf C}alorimeter.
\indentbf{BCAL} {\bf B}arrel {\bf CAL}orimeter.
\indentbf{BEAM} Beam line calorimeter + C5 counter.
\indentbf{BOR} {\bf B}egin {\bf O}f {\bf R}un.
\indentbf{Bourne shell} UNIX: standard UNIX system V command processor by Steve Bourne.
\indentbf{BSD}{\bf B}erkeley {\bf S}oftware {\bf D}istribution; second major UNIX variant.
\indentbf{C5} {\bf C5} detector close to the C5 collimator.
\indentbf{C} A programming language suitable for system programming (e.g. UNIX
is written in C)
\indentbf{C shell} UNIX: Unix command processor by Bill Joy (Berkeley); contains similar
program constructs as the C language.
\indentbf{CAL} High resolution uranium scintillator {\bf CAL}orimeter.
\indentbf{CARDS} Expression used in PATCHY and CMZ for collection of 
PATCHES with DECKS.
\indentbf{Control character} non-graphic character; represented in ASCII by decimal codes
less than 32.
\indentbf{CMZ} Code management system based on random access files.
\indentbf{CDAQ} {\bf C}entral {\bf D}ata {\bf AQ}uisition system in ZEUS.
\indentbf{CRADLE} Used in PATCHY to denote code changes in form of replacement,
deletion, or insertion statements.
\indentbf{CREOBJ} A subroutine to initialize data structures, automatically produced
by MAD in ADAMO
\indentbf{CSB} {\bf C}ontrol and {\bf S}witch {\bf B}ox in ZEUS data aquisition.
\indentbf{CTD} {\bf C}entral {\bf T}racking {\bf D}etector.
\indentbf{DataFlow} In ADAMO: a set of tables.
\indentbf{DDL} In ADAMO: {\bf D}ata {\bf D}efinition {\bf L}anguage.
\indentbf{DEC}{\bf D}igital {\bf E}quipment {\bf C}orporation.
\indentbf{DECWindows} DEC's windowing software; will be phased out in favor of MOTIF.
\indentbf{DECK} In PATCHY and CMZ: routine with some code management steering cards.
\indentbf{DESY} {\bf D}eutsches  {\bf E}lektronen {\bf SY}nchroton.
\indentbf{Daemon} UNIX: process running in background and performing a function. E.g. 
print daemon, performing job queuing for printer.
\indentbf{DFD} {\bf D}ata {\bf F}low {\bf D}iagram used in {\bf SASD} techniques.
\indentbf{DMA} {\bf D}irect {\bf M}emory {\bf A}ccess.
\indentbf{DVI} A {\bf D}e{\bf V}ice {\bf I}ndependent file, output by \TeX\ .
It uses the ASCII 255 character set and can be copied between computers as binary
(image) files. They contain the description of the formatted document.
\indentbf{EMU} {\tt MODEL} {\bf E}rror and {\bf M}essage {\bf U}tility.
\indentbf{Entity} An object which can be distinctly identified (e.g. a car, an event
..)
\indentbf{EOR} {\bf E}nd {\bf O}f {\bf R}un.
\indentbf{ER} {\bf E}ntity {\bf R}elationship model of reality in terms of entities
with attributes and relationships between those entities.
\indentbf{EVB} {\bf EV}ent {\bf B}uilder.
\indentbf{Exchange Format} Special format of sequential file that allows binary transport 
across computer platforms (ZEBRA, ADAMO).
\indentbf{Fork} UNIX: create a process; same as {\tt spawn}.
\indentbf{FC} {\bf F}ast {\bf C}lear.
\indentbf{FCAL}  {\bf F}orward {\bf CAL}orimeter.
\indentbf{FIC} {\bf F}ast {\bf I}ntelligent {\bf C}ontroler, a 68nnnn based VME
processor.
\indentbf{FLT} {\bf F}irst {\bf L}evel {\bf T}rigger.
\indentbf{FMUON} {\bf F}orward {\bf MUON} detector.
\indentbf{FORTRAN} Favorite programming language of high energy physicists;
often ridiculed but alive due to regular improvements.
\indentbf{FTD} {\bf F}orward {\bf T}racking {\bf D}etector.
\indentbf{GFLT} {\bf G}lobal {\bf F}irst {\bf L}evel {\bf T}rigger
\indentbf{GFLTB} Electronics box of the GFLT.
\indentbf{GNU} UNIX products of free software foundation such as EMACS.
\indentbf{GSLT} {\bf G}lobal {\bf S}econd {\bf L}evel {\bf T}rigger.
\indentbf{GSLTB} Electronics box of the GSLT.
\indentbf{HBOOK} CERN {\bf H}istogram {\bf BOOK}ing routines.
\indentbf{HEP} {\bf H}igh {\bf E}nergy {\bf P}hysics.
\indentbf{HERA} {\bf H}adron {\bf E}lectron {\bf R}ing {\bf A}nlage.
\indentbf{HES} {\bf H}adron {\bf E}lecton {\bf S}eparator.
\indentbf{HPLOT} CERN {\bf H}istogram {\bf PLOT}ting package.
\indentbf{ID} In ADAMO: a small non-negative integer identifying a row of a table.
\indentbf{Hypertext} Marked up text; allows to attach additional information 
(text, graphics, sound) to words in a text.
\indentbf{INDEX} In ADAMO: a permutation of the rows of a table.
\indentbf{INITAB} In ADAMO: an initialization subroutine produced automatically by MAD.
\indentbf{Korn shell} UNIX: comand processor by David Korn incorporating goodies of Bourne and
C shell.
\indentbf{KUIP} {\bf K}it for a {\bf U}ser {\bf I}nterface {\bf P}ackage (CERN package).
\indentbf{KUMAC} A {\bf KU}ip {\bf MAC}ro using the KUIP macro language (used e.g. in 
PAW)
\indentbf{KWIN} ZEUS package for format free input output cards.
\indentbf{\LaTeX\ } \TeX\ augmented by Leslie Lamport's set of macros.
\indentbf{\LaTeX\ style} A file that contains the description or changes to a document
layout style.
\indentbf{Link} UNIX: A pointer to a file (hard links to place on disk or symbolic link
to pathname).
\indentbf{LPS} {\bf L}eading {\bf P}roton {\bf S}pectrometer.
\indentbf{LSE} {\bf L}anguage {\bf S}ensitive {\bf E}ditor, a text editor supplied by
DEC.
\indentbf{LUN} {\bf L}ogical {\bf U}nit {\bf N}umber, a small positive integer to
refere to a file from a FORTRAN program.
\indentbf{LUMI} {\bf LUMI}nosity Monitor.
\indentbf{MACRO} In PAW, a text file containing PAW commands and logical constructs.
\indentbf{MAD} A tool to manage the ADAMO dictionary.
\indentbf{Memory Manager} Packages of subroutined for dynamic allocation in FORTRAN
(e.g. HYDRA,BOS,ZEBRA ...).
\indentbf{MBM} {\bf M}odel {\bf B}uffer {\bf M}anager package.
\indentbf{MINUIT} Function minimization and error analysis, CERN routine.
\indentbf{Model} VMS based package for data-acquisition in HEP (supplied by CERN/ECP).
\indentbf{MOMO} ZEUS set of program monitoring routines.
\indentbf{Motif} OSF multi-vendor windowing environment.
\indentbf{MOZART} {\bf M}onte Carlo for {\bf Z}EUS {\bf A}nalysis, {\bf
R}econstruction, and {\bf T}rigger.
\indentbf{MVS} IBM operating system ...
\indentbf{MZ} Memory management of ZEBRA.
\indentbf{Navigation} In ADAMO: going from one or more entities in one set to related
entities in another.
\indentbf{Native format} Sequential file format that is the default in the respective system.
\indentbf{NEWLIB} DESY package to make interactive use of IBM under MVS more user
friendly.
\indentbf{NFS} {\bf N}etwork {\bf F}ile {\bf S}ystem by SUN microsystems allows to "see"
remote files in same way as files attachted to local computer.
\indentbf{NTUPLE} Sequence of tree structured data; in PAW usually table of rows 
corresponding to different ``events'' and columns corresponding to different variables.
\indentbf{OSF} {\bf O}pen {\bf S}oftware {\bf C}orporation (``anti AT\&T UNIX''). 
\indentbf{PAM} In PATCHY: CARDS file in binary (only machine readable) format.
\indentbf{PATCH} Collection of DECKS in PATCHY.
\indentbf{PATCHY} CERN code management system from the times people still used punch cards.
\indentbf{Pathname}UNIX: a list of directories, separated by slashes and ending with a 
directory or file.
\indentbf{PAW} Interactive program for statistical analysis and data presentation.
\indentbf{PHANTOM} ZEUS collection of utility and physics analysis routines.
\indentbf{PID} Acronym for process identification; in UNIX a unique PID number is assigned 
to each process.
\indentbf{Pipe}UNIX: A connection between programs to connect standard output of one with 
standard input of next.
\indentbf{Plain \TeX\ } Donald Knuth's \TeX\ augmented by his own set of macros.
\indentbf{PostScript} Page description language by ADOBE corporation or imitators;
de facto standard for printing on laser printers.
\indentbf{PROLOG} A language to {\bf PRO}gram in {\bf LOG}ic.
\indentbf{ORACLE} Relational database marketed by ORACLE Corp.
\indentbf{QS10} A quadrupol magnet near the ZEUS detector at $z$ between -39 m and 26
m.
\indentbf{RC} {\bf R}un {\bf C}ontrol.
\indentbf{RCAL} {\bf R}ear {\bf CAL}orimeter.
\indentbf{RCC} {\bf R}un {\bf C}ontrol {\bf C}ontroller.
\indentbf{Relationship}  A relationship between two entities, each in a set.
\indentbf{Relative pathname} UNIX: pathname starting from the current working directory.
\indentbf{RSet} A set of relationships. 
\indentbf{RMUON} {\bf R}ear {\bf MUON} detector.
\indentbf{Root directory} UNIX: Ancestor of all directories and start of absolute pathnames
with name {\tt /.}.
\indentbf{RTD} {\bf R}ear {\bf T}racking {\bf D}etector.
\indentbf{RZ} CERN package for random access to files based on ZEBRA.
\indentbf{SASD} {\bf S}tructured {\bf A}analysis, {\bf S}tructures {\bf D}esign.
\indentbf{Selector} In ADAMO: an ordered subset of the rows of a table.
\indentbf{Spool}To place item in queue, each waiting its turn for some action.
\indentbf{SLT} {\bf S}econd {\bf L}evel {\bf T}rigger.
\indentbf{TAP} In ADAMO: a subroutine package to manipulate tabular or ER data.
\indentbf{Superuser} Privileged user with access to any action (system administrator);
login name usually {\tt root}.
\indentbf{Standard input} UNIX: A file from which a program can receive input; if not 
instructed otherwise input is from terminal.
\indentbf{TIP} In ADAMO: interactive tool to manipulate ADAMO data and produce 
histograms in combination with PAW.
\indentbf{TLT} {\bf T}hird {\bf L}evel {\bf T}rigger.
\indentbf{TP} {\bf T}rans{\bf P}uter.
\indentbf{TRD} {\bf T}ransition {\bf R}adiation {\bf D}etector.
\indentbf{UNIX} An operating system originally developed at AT\&T in 1969; 
(almost) non-propriortory. 
\indentbf{VECTOR} In PAW the equivalent of a FORTRAN array.
\indentbf{VETO} {\bf VETO} wall detector.
\indentbf{VM/CMS} IBM operating system using concept of mini-disks, dating from the 60'ties.
\indentbf{VMS} DEC/VAX operating system.
\indentbf{VXD} {\bf V}erte{\bf X} {\bf D}etector.
\indentbf{WIN} In ADAMO: Fortran common block related to an ADAMO table.
\indentbf{Working directory}UNIX: the directory you are associated with at a given time.
\indentbf{WYSIGYG} {\bf W}hat {\bf Y}ou {\bf S}ee {\bf I}s {\bf W}hat {\bf Y}ou {\bf
G}et (text editing system that shows the layout of the document when typing).
\indentbf{ZEBRA} Unloved memory management system designed to overcome FORTRAN
lack of dynamic data structuring.
\indentbf{ZEPHYR} {\bf ZE}us {\bf PHY}sics {\bf R}econstruction program. 
\indentbf{ZDIS} ZEUS steering package for physics generator programs; output ADAMO tables
form input for MOZART.
\indentbf{ZGANA} ZEUS trigger simulation routines for MC events 
\indentbf{ZRIO} Sequential input/output package for ZEUS.
\end{indentlist}

\begin{thebibliography}{99}
 
\bibitem{zeus_detector} ZEUS, A Detector for HERA, ZEUS Collaboration, PRC 87-02
September 1987.

\bibitem{blue_book}``The blue book''
(or ``green book'') on ZEUS contains information about the ZEUS
detector and its performance in terms of hardware, safety, online and offline 
software. The latest edition is the Status Report of 1993. Check if the
secretariat still has copies. 

\bibitem{heartofzeus} ``The Uranium Scintillator Calorimeter ...'', J. Kr\"uger
(habilitation) DESY F35-92-02, January 1992. 

\bibitem{hesnote} ZEUS note 91-044, 1991.

\bibitem{desy_center} Few page description of the DESY Computer Center (in german).
Available at the DESY Computer Center.

\bibitem{first_days} The First Three Days, DESY Computer Center Primer. Available at
the DESY Computer Center. Describes mainly work on the central IBM under NEWLIB.

\bibitem{NEWLIB_primer} A detailed introduction into NEWLIB. Available at the DESY
Computer Center.

\bibitem{ibmtapeeaze} "EAZE input option on IBM". Available in ZEUS documentation
folder ``manuals'' ({\tt ibmeazeinput.txt}).

\bibitem{editor_eve} EDFOR
Version 5.4, User Guide and Reference Manual. ALEPH Note 90-96. Available in ZEUS
documentation folder ``manuals'' ({\tt edfor\_reference.ps}).

\bibitem{VAXprimer}``How to Get Started on a VAX'' by K. Gather. DESY F1-90-01 (1990).

\bibitem{DESYnews} DESY Computing Newsletter No. 4 (Feb. 1993).

\bibitem{DESY-USG9001} Printing at DESY. Short guide available at the DESY Computer
Center.
 
\bibitem{lund_mc} The Lund Monte Carlo Programs, CERN Pool
programs W5035/W5045/W5046/W5047/W5048 long writeup. Verson for Jetset 7.3 is 
written up in CERN-TH.6488/92 (W5035/W5044).
Available
from CERN Computer Center and in ZEUS documentation folder ``manuals''
({\tt pythia.ps}).

\bibitem{RELEASEold} A description of the method 
can be found on the DECstation cluster under
{\tt /zeus/pro/doc/RELEASE\_NOTE\_29Apr\_1992}.

\bibitem{RELEASEnew} ZEUS note 92-99, 1992. Available in ZEUS documentation folder
``ZEUS\_notes''  {\tt /zeus/doc/ZEUS\_notes/ZEUS-92-099.ps}.

\bibitem{FTPzeus} M. Kasemann, T. Poser, ``How to transfer ZEUS data via FTP''.
Unclassified note. Available in ZEUS documentation folder ``manuals'' 
({\tt /zeus/doc/manuals/ftp\_zeus.ps}).

\bibitem{copydat} ZEUS Note 92-66. T. Haas:``Copying Data to Workstations''.
Available in ZEUS documentation folder ``manuals'' 
{\tt /zeus/doc/manuals/copy\_data.ps}.

\bibitem{ZCAL} ZEUS Note 92-19. Status of the Uranium Calorimeter Reconstruction
Software.

\bibitem{ZHES} ZEUS Note 92-78. The HES Reconstruction Program.

\bibitem{bacrec} Description of backing calorimeter reconstruction package. Available 
in ZEUS documentation folder ``manuals'' ({\tt /zeus/doc/manuals/bac-rec.txt}).

\bibitem{ZVXFIT} ZEUS Note 91-20. ZVXFIT. A Vertex Reconstruction Package for
ZEPHYR.

\bibitem{ZMB} ZEUS Note 92-27. Muon Barrel Reconstruction.

\bibitem{geant} GEANT 3, R. Brun et al., report DD/EE/83-1, CERN (1989).

\bibitem{ZTRIG} ZEUS Note 90-84. ZEUS Trigger MC status.

\bibitem{ZGAZE} ZEUS Note 92-06. GAZE manual. 

\bibitem{ZLAZE} ZEUS Note 91-69. LAZE introduction.

\bibitem{gaze_delphi} Event Viewing Software, Delphi-Note 30-8-1988. 

\bibitem{ZZDIS} ZEUS Note 92-40. Release of the ZDIS Program Package.

\bibitem{ZAIDA} ZEUS Note 92-31. AIDA the ADAMO Interactive Data Analyzer. Available in 
ZEUS documentation folder ``manuals'' ({\tt aida.ps}). 

\bibitem{ZZRIO} ZEUS Note 91-103.
ZRIO vs. 2.0 - The Sequential I/O Program for ZEUS Offline
Software.

\bibitem{ZKWIN} ZEUS Note 92-102. The ZEUS Program Control Card Package KWIN.
 
\bibitem{hbook_guide} The HBOOK User Guide. Available from
CERN Computer Center and in ZEUS documentation folder ``manuals''
({\tt hbook.ps}).
 
\bibitem{hplot_guide} The HPLOT User Guide. Available from
CERN Computer Center.

\bibitem{kuip_guide} The KUIP User Guide. Available from
CERN Computer Center and in ZEUS documentation folder ``manuals''
({\tt kuip.ps}).
 
\bibitem{paw_manual} PAW Physics Analysis Workstation.
Available from CERN Computer Center.
 
\bibitem{patchy_primer} PATCHY for Beginners, DD/US/60.
Available from CERN Computer Center.

\bibitem{cmz_guide} CMZ, a Source Code Management System. User's Guide \& Reference
Manual. Available from CERN Computer Center or CodeME S.A.R.L. (CODEME\mbox{@}CERNVM).
 
\bibitem{zebra_guide} ZEBRA User Guide. Available from CERN
Computer Center.

\bibitem{zebra_rz} ZEBRA Reference Manual for the Random Access Package.
Available from CERN Computer Center and in ZEUS documentation folder
``manuals'' ({\tt zebrarz.ps}).

\bibitem{zebra_fz} ZEBRA Reference Manual for the FZ package. Available from CERN
Computer Center and in ZEUS documentation folder ``manuals'' ({\tt zebrafz.ps}).
 
\bibitem{mz_guide} ZEBRA Reference Manual MZ Memory Management.
Available from CERN Computer Center.
 
\bibitem{dzdisp_guide} A ZEBRA Bank Documentation and Display
System. Available from CERN Computer Center.

\bibitem{adamo_guide} The ADAMO Data System. An Introduction for Particle Physicists
by M.G. Green (RHBNC 89-01) . The ADAMO Data System Programmers Manual.
 
\bibitem{ert_chen} P.P. Chen ``The Entity-Relationship Model -Towards a Unified View
of Data''; ACM Trans. on Database Systems 1 (1976).
 
\bibitem{minuit_guide} MINUIT Function Minimization and Error
Analysis. Available from CERN Computer Center and in ZEUS documentation folder
``manuals'' ({\tt minuit.ps}).
 
\bibitem{ffread_guide} FFREAD User Guide and Reference Manual,
DD/US/71. Available from CERN Computer Center.
 
\bibitem{cernlib_writeup} CERN Program Library. Available from
CERN Computer Center.
 
\bibitem{tex}  The TeXbook, Donald E.Knuth,
Addison-Wesley Publishing Company. Available from
bookshops.
 
\bibitem{latex} \LaTeX - A Document Preparation System, Leslie
Lamport, Addison-Wesley Publishing Company. Available from
bookshops.

\bibitem{texatcern} Local guide for \TeX at CERN. Available from the CERN
Computer Center and in ZEUS documentation folder ``manuals'' ({\tt texacern.ps}).

\bibitem{dvips} Guide to using the {\tt dvips} dvi to PostScript translater.
Available from the CERN Computer Center and in the ZEUS documentation folder
``manuals'' ({\tt dvips.ps})..

\bibitem{xfig} Description of {\tt xfig} utility to create graphics. Available in 
ZEUS documentation folder ``manuals'' ({\tt xfig.ps}).

\bibitem{psfig} Psfig/\TeX\ 1.6 Users Guide by Trevor Darrel. Available in ZEUS 
documentation folder ``manuals'' ({\tt psfig.ps}).

\bibitem{fussweg} Introduction to the use of \TeX\ at the DESY Computer Centre
(in German). Easy to follow instruction but restricted to the local IBM under NEWLIB.
Available at the DESY Computer Center.
 
\bibitem{pdg} Review of Particle Properties, Particle Data
Group, Phys.Lett.{\bf B204},(1988),113-114.
Available in most Scientific Libraries.
 
\end{thebibliography}
 
%========================================================================
 
\small
\printindex
\normalsize
 
%========================================================================
 
\end{document}
