The essential idea of the package is that each BOS bank has a C data
structure
associated with it. The C structures are obtained by parsing the .ddl
files
with an existing Perl script. Calls are then defined that instead of
returning
an index into the BOS common they return a pointer to a structure. This
makes BOS banks extremely easy to work with directly, avoiding the
common
practice of copying the contents of the BOS bank to a temporary array,
and
makes the code extremely easy to read.
The structure for each BOS bank is defined by a bank header followed by
an array of structures containing the contents of the BOS bank. The
bank header mirrors the information preceding the contents of each
BOS bank. The bank header is the same for all banks and is defined
below,
the source is located in packages/include/bostypes.h:
typedef struct {
int ncol;
int nrow;
char name[4];
int nr;
int nextIndex;
int nwords;
} bankHeader_t;
Structures are then defined for each of the BOS banks. This structure
contains a bankHeader_t followed by an array of structures containing
the contents of the BOS bank. The naming convention is clas<BANKNAME>_t
for the main bank and <bankname>_t for the array of structures. An
example
of a simple bank (DC0) is shown below:
typedef struct {
bankHeader_t bank;
dc0_t dc0[1];
} clasDC0_t;
where dc0_t is shown below;
typedef struct {
uint16 id; /* the address of the hit detector element */
uint16 tdc; /* tdc information (channels) */
} dc0_t;
where uint16 is an unsigned short.
Several utilities have been written in the c_bos_io library to use these
structures, the most fundamental is the function call getBank which
returns a pointer to a structure when one asks for a bank of a
particular
name. A short example of code which would print the entire contents of
the
first DC0 bank is shown below:
int i;
clasDC0_t *DCbank;
if(DCbank = (clasDC0_t *)getBank(&bcs_,"DC0 ")){
printf("Bank Name:%s, Number of entries: %d\n", DCbank->bank.name,
DCbank->bank.nrow);
for(i=0; i < DCbank->bank.nrow; i++)
printf("id: %d, tdc: %d\n", DCbank->dc0[i].id, DCbank->dc0[i].tdc);
} else {
printf("No DC0 bank found\n");
}
That's it! A few comments: &bcs_ is a pointer to the BOS common, the
return
value is getBank is a pointer to void which must be cast to the
appropriate
type, and if getBank fails to find a bank it returns NULL.
Routines also exist to make banks, drop banks, initialize BOS,
open/close files and sequentially read a file. The prototypes for these
routines exist in packages/include/bostypes.h. A simple program called
bosdump prints to stdout the contents of BOS banks using these
utilities provides a nice template for using this library. bosdump
is located in packages/utilities/bosdump a web page also exists
for c_bos_io under software libraries in the clas Off-Line pages:
http://www.cebaf.gov/~manak/c_bos_io.html
I believe the benefits of utilities like these are obvious, I also
strongly
feel that we should agree on one library of C routines to interface
with BOS - this will make everyone's code easier to read, easier to
maintain, it will avoid duplication of effort and will allow us all to
build on each other's work. The exact implementation of these routines
is
still somewhat up for grabs as not a lot of code has been written using
them - however this will quickly change as more code is written, and it
will become more and more costly to change the package - so I would urge
people interested in this library to provide comments.
-Joe