HannaLib: HERMES Analysis Tool Library

• Linking with HannaLib
• Debugging
• Syncing Slowcontrol Data
• Command line arguments
• Hannas little IO helpers
• Some table functions
• Event lists

#include <hanna/hadebug.h>

int ha_debuginit( char *envname );

Initialize the Hanna debuging module and use the environment variable envname to look up the module debugging levels.

int *ha_debugptr( char *name );

Get a pointer to the debugging level for module name. Note that you should always use the pointer to access the current debugging level since it might change asynchronously in future versions of HannaLib.

int ha_debugset( char *name, int value );

Set the debugging value for name to value.

void ha_debuglist( FILE *fp );

Write a list of module names and debug levels used so far to the file fp.

#include <hanna/haslow.h>

int ha_slowinit( char *name, char *driver );

Use slowcontrol file with name and the GAF driver driver as slowcontrol source. This file has to be timeordered and all keytable fields that are defined by the standard slowcontrol keytable. You should use files produced by the HEMES Slowcontrol Production.

int ha_slowsync( int evttime, int evttimemu, int runnum, int evtnum );

Synchronize the slowcontrol data so that it's valid for the event taking place at evttime (seconds) and evttimemu (microseconds). The number of run runnum and number of event evtnum is only used for debugging output.

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 or has changed.
Meaning of the arguments: This argument is normally just passed to the functions of the official Hermes Analysis library. See below for the values that are defined for this argument.

name	Name of table
starttime	Starttime from record key
starttimemu	Fractional part of starttime in micro seconds
endtime	Endtime from record key
endtimemu	Fractional part of endtime in micro seconds
flag_first	TRUE for every first slow table of a certain type
status	Status that defines a condition for table name.

/*------------------------------------------------------------------------*\ Flags given to the user_slow() function as status argument \*------------------------------------------------------------------------*/ #define HA_SLOWINIT 1 /* Just initializing */ #define HA_SLOWUPDATE 2 /* Received update */ #define HA_SLOWINVAL 3 /* Table not valid */

int ha_slowmodflag( char *tabname, int mode, int flag );

Modify a flag that controls the behaviour of slowcontrol table tabname. You can specify the tablename "ALL" to modify all tables HannaLib has found so far. If mode is TRUE, the flag(s) flag are set, if it's FALSE, it's reset. The following flags might be modified: /*------------------------------------------------------------------------*\ Flags used to define the status of a slowcontrol table \*------------------------------------------------------------------------*/ #define HA_SLOWIGN 0x01 /* Table is ignored */ #define HA_SLOWNOCHK 0x02 /* Table is not checked for validity */

#include <hanna/haargs.h>

int ha_addarg( char *name, void *buffer, char *valname, char *help );

Add one entry to the list of command line switches.
Meaning of the arguments:

name	Name of this switch, by convention this should begin with a minussign ("-")
buffer	Pointer to option value. If a commandline switch was found while parsing of the commandline, the variable pointed to by buffer will be changed depending of the type of the switch. For boolean switches (valname==NULL) buffer must point to an integer that is incremented for each occurrence of the switch. For switches augmented by a value, buffer must point to a character pointer that will be set to point to the switches value.
valname	If the switch requires an additional value, the name of this value (used by ha_usage()) is specified by valname. If the switch is boolean, this argument should be NULL.
help	Short help string that will be printed by ha_usage().

void ha_usage( char *prgname );

This will print a summary of all defined commandline switches. prgname is the name of the program that should be used in the printout.

Remarks

Hanna defines some switches that it uses itself. Here is the default usage output:

Usage : hannah [option [value]] [--] [file [...]] Options: --help - Help. --nokey - Don't use key table info --DST - Read DST format --tmp dname - Temporary directory (default: "./"). --slow fname - 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'. --driver dspec - Set input driver (default: FZ,filfor=EXCH). --flist fname - Read file list from file. file [...] - file(s) containing run data

#include <hanna/haio.h>

HFILE *ha_openinput( char *name, char *driver, char *tmpdir, char *dflname );

Opens a file with name name and driver driver for reading. Returns a Hanna file descriptor or NULL on failure. If the file name ends on .gz the file is uncompressed. ADAMO files are intermediately stored in the directory tmpdir, DAD files are uncompressed on the fly by zlib.
Hanna knows the following drivers:

RFIL	Dad file (as used for microDST's)
RPIP	Dad UNIX pipe
RMEM	Dad shared memory pipe
MRFIL	Dad multifile (as used for slow control data)
all other	Will be passed to ADAMO's OPENGAF() routine

Opening (non-multi-mode) DAD files with dflname set to a dataflow name will not generate the ADAMO objects in memory. You might use that feature when reading subsequent files of the same structure. Else-wise pass NULL as dflname.

void *ha_getkeyfld( HFILE *dscr, char *fname );

Returns a pointer to the key table field fname of the file dscr or NULL on failure. This function is just a wrapper for the (undocumented) Dad library call sm_FieldFromName() (thanks Wolfgang!).

int ha_rewind( HFILE *dscr );

Rewind an input file.

int ha_close( HFILE *dscr );

Close a file associated with a Hanna file descriptor.

int ha_fileactive( HFILE *dscr );

Test if the file associated with a Hanna file descriptor is active (return value unequal 0) or closed (return value 0).

int ha_nextkey( HFILE *dscr );

Read the next key table entry of an input file. Returns something unequal 0 if there was no next record (end of file).

int ha_getrecord( HFILE *dscr, int readflag );

Read or skip (readflag==FALSE) the record associated with the current key from the input file dscr.

#include <hanna/hatab.h>

HATAB *ha_newtab( aDataflow *tdf, char *name );

Build a Dad and Hanna table descriptor for the table name. If you're reading a GAF, pass NULL for tdf. If you're reading a DAD file, pass the address of the DAD dataflow decriptor here. This can either obtained using dadDataflow() on the DAD connection ID or by passing the dadtdf element of an HFILE descriptor if the file was opened using ha_openinput() (this field is set to NULL for GAFs so that is probably a good idea to use it).
Do not call this function twice for one table!

HATAB *ha_findtab( char *name );

Get the table descriptor for the table name that once was created with ha_newtab(). Returns NULL if the table not yet was created.

void *ha_gettabfld( HATAB *dscr, char *fname )

Get a pointer to the WCB of the field fname of table dscr.

#include <hanna/haeventl.h>

int ha_initeventlist( char *name );

Opens a the event list file pointed to by name and reads the first event specification. The return code is non-zero in case an error was encountered.

int ha_checkeventlist( int runnum, int burstnum, int evnum, int allow_buggy, int *eoflist );

Checks whether the event given by the runnum, burstnum, eventnum triplet should be accepted according to the event list. The routine returns a return code of >0 if the event got refused, ==0 if the event got accepted and <0 in case of an error. If the flag allow_buggy is non-zero then multiple entries with the same event specifications will be accepted and the check will be based on the last entry for the event. The variable pointed to by eoflist returns TRUE (<>0) if EOF (End Of File) was encountered for the event list file and FALSE (0) otherwise. For a description of the event list file format please consult the event list section in the Hanna frame documentation.