Users' Guide to the KHFSVC Event Server

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="" 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.