Users' Guide to the KHFSVC Event Server
<![CDATA[
This document summarizes the features of the E871 online event server,
named with the mneumonic KHFSVC (Kaon cHeetah Fortran SerViCe). The
original version was upgraded to a multi-threaded version by Simon
Rochester in 1993. The number of threads has since been doubled twice to
the current forty. This limit is arbitrary, but imposed for bookkeeping
reasons. Typically, around five threads are active at any given time.
Each detector group is assigned four "thread numbers" to choose from.
A thread can be initialized to read events from a particular source and
with a particular Level 1 trigger mask. The events are read serially and
a given event is sent to the next client to request one. The server
makes no attempt to keep track of who is asking for events. If several
users are reading events simultaneously from the same thread, no one
user will see all the events. Although any number of client offline JOBs
can read events from a given thread, most detector groups will want to
assign their four threads to individuals within their group so that they
don't steal events from each other.
Detector group thread assignments are:
thread no.(X) detector-group
10, 20, 30 detector monitor programs
1, 11, 21, 31 CER
2, 12, 22, 32 MHO
3, 13, 23, 33 MRG
4, 14, 24, 34 PBG
5, 15, 25, 35 TSC
6, 16, 26, 36 SDC - UTA
7, 17, 27, 37 SDC - Stanford
8, 18, 28, 38 DCH - UCI
9, 19, 29, 39 offline testing
Thread 0 is now restricted to starting up other threads.
The analyzer is now fed from thread 30.
Thread 10 is reserved for the online event display program.
Thread 20 is reserved for the anatest program running in BATCH.
Thread 30 is reserved for the online analyzer program which
feeds the online copyplots.
Individual threads need to be initialized before they can be used.
All threads but 0 will self-destruct after one hour of inactivity.
One normally uses an offline JOB to read events from a server thread,
as though the events were coming from a local file. To initialize and
query the server thread, there are three stand-alone shell commands.
The commands can be typed at a terminal or placed in a JOB script.
These commands have a syntax which one is unlikely to type accidentally:
1) ckhfsvc_query [-n]X , returns parameters of thread X, where X={0-39}
2) ckhfsvc_rdevt [-n]X , reads a stream of events from thread X={0-39}
and dumps it to the screen as text. This can
be used to check that the event file is OK.
Use <cntrl>-c to terminate the dump output.
3) ckhfsvc_init -nX [-f file] [-b L1_trigger_mask] [-k keepup_mode]
An example:
ckhfsvc_init -n6 -f/data/run.0524 -b0xffff0001 , send a UTA SDC
client the parallel
muL-eR triggers and
calibration events
from run 524, which
must be on disk.
The ckhfsvc_init command has these four options:
-nX , X is the thread number. The "-n" can be omitted if this
is the only option specified.
-f full_filename_with_path , Default is "-fKHFDAQ" which tells
the server to send events from the most recent run. The
following two commands both (re-)initialize thread X :
ckhfsvc_init -nX -fKHFDAQ or ckhfsvc_init X
The first version will rewind the thread pointer to the
start of the most recent KHFDAQ file, after starting up
the X thread if it's not already running. The second form
(without the -f option) will start up the X thread pointing
to KHFDAQ if thread X is NOT already running. If thread X
IS already running, the second command will not do
anything. It will not rewind the file. (The "-n" part of
the -n option can be omitted if -n... is the only option.)
-b L1_trigger_mask , default is -b0 for no trigger check. If a
trigger mask is specified, physics and
calibration events containing COMMON/EVBFIN/
will be filtered using this mask. Begin-run
records and scaler events contain no
L1 trigger word and are sent to the client.
-k keepup_mode , This is relevant for -fKHFDAQ. There are three
keepup modes:
-k0 : The server thread makes no attempt to keep
up with the incoming data. Once the server
thread starts to read a run, it will stay
with that run until it reads to the end.
At this point it will jump to the most
recent run, even though this may mean
skipping some runs in between.
-k1 : run-keepup (default). The server thread
jumps to a new run soon after it starts.
-k2 : spill-keepup. The server thread stays
within a few spills of the most recent
data. This option is not implemented yet.
There are two steps to make the offline JOB read from a server thread:
A) Change the JOB definition of the TAPE00 environment variable to:
export TAPE00; TAPE00="KHFSVC:X:bnl871.ags.bnl.gov"
Here X={0-39} represents the server thread number.
If the old form of the line (without "X:") is used, the program
defaults to X=9, provided thread 9 has been initialized.
B) Initialize the server thread. One wants to run the ckhfsvc_init
command before the Fortran executable starts to run. The best
way to do this is to include the following lines near the top
of the JOB script:
export KHFSVCINIT; KHFSVCINIT="ckhfsvc_init X"
${KHFSVCINIT}
ckhfsvc_query X
Again X={0-39} represents the server thread number. The first
of these three lines defines an environment variable KHFSVCINIT
for the JOB. KHFSVCINIT contains the command string needed to
(re-)initialize the appropriate thread. The second line executes
the command string. The third line queries the server thread
to echo the state of the thread after the initialization.
KHFSVCINIT allows the JOB to deal with a complication which often
arises when running on KHFDAQ data. This occurs when the network
connection fails or the acquisition computer is rebooted. The
default offline client behavior under these circumstances is to
terminate the JOB with a call to USEFIN. When running on KHFDAQ
data, however, one can cause the offline JOB to enter a
"reconnect cycle" in which it will keep issuing the command
string in KHFSVCINIT until it manages to re-establish the
connection and continue reading events. The ckhfsvc_init command
string in quotes will return successfully if it makes
contact with the remote server thread, and it will restart
the thread for -fKHFDAQ if it determines that the thread
has been destroyed. Normally, one would not put -fKHFDAQ
explicitly in this command string, because that would
rewind the current thread stream regardless of whether it
needed to be restarted. This would be inappropriate if the
interruption were merely due to a network glitch which
temporarily broke the client connection to an operative thread.
For the KHFSVCINIT reconnect to work properly, one needs to
include an entry USEWAT, discussed in the next section.
WAIT-AND-TRY-AGAIN Cycle:
When running in KHFDAQ mode, the server sometimes reads events
faster than they are received from the data acquisition system.
Before a server thread reaches the end of acquired data in a
currently active run, it will send a WAIT signal to the client
JOB. The client JOB can choose to ignore the WAIT signal and
terminate with a call to USEFIN (the default), or it can enter
a WAIT-AND-TRY-AGAIN cycle. To activate the WAIT-AND-TRY-AGAIN
choice, the user should put a SUBROUTINE USEWAT in his JOB
source code. The model for this short subroutine is found in the
offline source distribution. One needs to uncomment certain
indicated lines. The code can be put in the USER subroutine
itself as ENTRY USEWAT.
]]>