Hanna: Yet another HERMES Analysis Tool

• The command line interface
• Environment variables
• Signal handling
• Handling of Zebra Errors
• Event lists
• Your Analysis Code: User functions
• Reading Monte Carlo Data
• How to build an Analysis Program

Options:

--help	Help
--nokey	Don't use key table info
--DST	Read DST format
--MC	Read MC data
--tmp dname	Set temporary directory (default: ".").
--evtcntr int	Event counter scaler (0 is off, default: 100).
--slow fname	Set slow control file (default: None).
--sdriver dspec	Driver to read slow data (default: FZ,filfor=EXCH).
--soffset offset	Time offset for slow control data (default: 0.0).
--stime method	Select event time (AUTO,VME,UNIX,EFF) for synchronisation (default: AUTO).
--events fname	Only process events listed in file fname.
--evsloppy	Allow buggy event lists with multiple identical entries for the same event. Warning: Read the related documentation before using this option!
--driver dspec	Set input driver (default: FZ,filfor=EXCH).
--flist fname	Read file list from file fname.
file [...]	Input file(s) containing run data.

Return value: 0 on success, 1 on error.

Note 1: If you're processing more than one runfile in sequence you have to make sure, that the slowcontrol file contains information for all of them (that's the case for merged fillfiles). The runfiles have to be supplied ordered in time.

Note 2: The slowcontrol time offset is substracted from the true event time before the synchronization takes place. This has the same effect than shifting the slowcontrol data forward in time by the same interval. Note that this offset is only applied within the synchronization routine. All times passed to user routines etc. are not affected.

Note 3: The AUTO synchronization method uses the VME method for all run numbers higher then 6000 (1996+ data). For earlier runs Hanna checks for a field called iEffEvUnixTime in the dcEvInfo table and uses the EFF method if it's present. If this field is not found, the UNIX method is used.

Note 4: See below for the format of event list files.

Note 5: For a list of valid driver names see the description of the ha_openinput() library call.

Note 6: You can add your own command line switches using the ha_addarg() library call.

Note 7: The --evsloppy option emulates the handling of event lists of Hanna versions before 3.0; Please read the detailed documentation on the problems related to the use of event lists with multiple identical entries before using this flag!

Module=Level

MAIN

Controls the verbosity of the main loop (high values include the output of the lower levels):

-1	No output
0	Print startup message, display an event counter if connected to a TTY and print a time summary at the end.
1	Print list of requested debug module names.
2	Print a separator line for each new event.

ADAMO

Controls the debugging mode of the ADAMO library via SETCHK. The following relation between levels and debug modes is used:

0	NONE
1	RUNTIM
2	ACCESS
3	RSETS
4	WINDOWS
5	TABLES
6	ALL

SLOW

Control the debug level of the slowcontrol module(high values include the output of the lower levels):

-1	Don't print validity warnings
0	No output
1	Print a list of all slowcontrol tables at startup
2	Report each record read
3	Trace syncronisation algorithm
4	Print status of all tables after each synchronisation phase (lots of output)

IO

Control the debug level of Hanna's Input/Output module (high values include the output of the lower levels):

0	No output
1	Trace open, close IO operations
2	Report keytable structures of opened files
3	Trace read and next key operations

EVLIST

Control the debug level of Hanna's event list module (high values include the output of the lower levels):

0	No output
1	Generate warnings on multiple entries in the event list if run with the --evsloppy option.
2	Report every matched entry and EOF of the event list
3	Be very very verbose ;-)

Example

• HANNA_DEBUG="ADAMO=6" enables the highest ADAMO debugging level.
• HANNA_DEBUG="IO=3:SLOW=4" will give you lots of output.
• HANNA_DEBUG="EVLIST=1" will give you warnings for multiple entries in event lists.

Controlling Slowcontrol Table Handling

Example

• HANNA_SLOW= will disable the reading of any slowcontrol data.
• HANNA_SLOW=!dscCryoCal:dscRATES will ignore the tables dscCryoCal and dscRATES.

ZFATAM. !!!!! Going to ZFATAL for EXIT VIA ZTELL. !!!!! ZFATAL called from ZTELL called from MZGAR1 called from MZLIFT called from MZPUSH Current Store number = 0 (JQDIVI= 2) ========================================================== Hanna: Uuups, trapped ZFATAL call! Hanna offers you her condolences. Dumping core now... Abort (core dumped)

Note: This feature was turned off since DAD already catches ZFATAL calls and dumps core.

eventnum [burstnum [runnum [rflag [junk ...]]]]

An event is processed if the (eventnum, burstnum, runnum) triplet matches a non-comment line from the event list. With the first event that does not match that line, the next line is read and tested. If no next line is found, Hanna terminates.

Multiple entries in the event list for the same event are treated as an error which causes Hanna to terminate. However, if the --evsloppy option of the command line interface is given, this feature of some event lists will be accepted. The decision whether the event should be accepted or not will be based on the last entry matching the event specifications. Please read the additional documentation on event lists with multiple entries for the same event as they are potentially malign!

Here is a list of all this functions:

#include <hanna.h>

int ha_main( int argc, char *argv[] );

After booking commandlineflags with ha_addarg() you have to call this ha_main() in your main() function to start up the Hanna frame.

Please pass the arguments you receive by main() to ha_main() as they are.

int user_init( void );

Called after the slowcntrl module is initialized.

int user_end( int retcode );

Called at the very end. retcode is a returncode that you can evaluate (values unequal 0 indicate an error). The return value of user_end() is used as program exit code, so it's no bad idea to do something like return retcode;.

int user_runinit( int runnum );

Called whenever a new run is processed. Meaning of the arguments:

runnum

Number of this run

int user_runend( int retcode );

Called whenever a run was processed. Meaning of the arguments:

retcode

Returncode of the last user_event()/user_burstend() call of this run.

int user_event( int runnum, int eventnum, int evttime, int evttimemu, int index, int cur1, int cur2 );

Called whenever an event has to be processed. Meaning of the arguments:

runnum	Number of this run
eventnum	Number of this event
eventtime	Time of this event (as selected by the -stime switch). This is -1 for Monte Carlo data.
eventtimemu	Fractional part for the event time in microseconds.
index	ADAMO index on the g1Track table in microDST mode. index is ID if Hanna is reading hrc.event files.
cur1, cur2	Cursors on index

If user_event() indicates an error condition (return code unequal 0), Hanna will exit the main event loop and call all termination routines.

int user_slow( char *name, int starttime, int starttimemu, int endtime, int endtimemu, int flag_first, int status );

Called whenever a new slow table is read. Since this function might also be used with the HannaLib, see the description there.

int user_burstinit( int runnum, int burstnum, int bursttime, int bursttimemu, int burstgood );

Called only in microDST mode, whenever a new burst was read. Meaning of the arguments:

runnum	Number of this run
burstnum	Number of this burst
bursttime	Time of this burst (as selected by the -stime switch). This is -1 for Monte Carlo data.
bursttimemu	Fractional part for the time of this burst in microseconds.
burstgood	Flag which is set to 1 if the new burst matches an entry in an event list or set to 0 else. If no event list is given this flag is always set to 1.

If user_burstinit() returns a value larger than 0, Hanna will skip this burst and read the next record from the input file. If user_burstinit() returns a value smaller than 0 to indicate an error condition, Hanna will exit the main event loop and call all termination routines.

int user_burstend( int retcode );

Called only in microDST mode, whenever a new burst was processed. Meaning of the arguments:

retcode

Returncode of the last user_event() call of this burst.

If user_burstend() indicates an error condition (error code unequal 0), Hanna will exit the main event loop and call the termination routines.

Note: You don't have to supply a user function that you don't need. In this case Hanna will use a default dummy cfunction that doesn't do anything. But in any case you have to call ha_main() to start up hanna.

Since Monte Carlo events have no timetags, the evttime/bursttime arguments passed to user_event()/user_burstinit()/user_goodburstinit() are set to -1.

Important Note: The index passed to user_event() in microDST mode is valid on the g1MTrack table (and not on g1Track) when Monte Carlo data is read.

Quick introduction