Midas C++ API - bk_xxx functions

This page contains the full API reference for the bk_xxx functions for creating and reading data banks in events.

For the structure of events and banks, see Event data format.

For explanations and examples of creating events, see Frontends: programming.

Data Bank Functions (bk_xxx)

Functions

bk_close

INT bk_close(void *pbh, void *pdata)

Close the Midas bank priviously created by bk_create(). The data pointer pdata must be obtained by bk_create() and used as an address to fill a bank. It is incremented with every value written to the bank and finally points to a location just after the last byte of the bank. It is then passed to bk_close() to finish the bank creation

Parameters:

pbh (void *) –
pointer to current composed event
pdata (void *) –
pointer to the data

Returns:

INT –
number of bytes contained in bank

Declared in include/midas.h:1964, defined in src/midas.cxx:18258

bk_create

void bk_create(void *pbh, const char *name, WORD type, void **pdata)

Create a Midas bank. The data pointer pdata must be used as an address to fill a bank. It is incremented with every value written to the bank and finally points to a location just after the last byte of the bank. It is then passed to the function bk_close() to finish the bank creation.

INT *pdata;
bk_init(pevent);
bk_create(pevent, "ADC0", TID_INT32, &pdata);
 pdata++ = 123
 pdata++ = 456
bk_close(pevent, pdata);

Parameters:

pbh (void *) –
pointer to the data area
name (const char *) –
of the bank, must be exactly 4 charaters
type (WORD) –
type of bank, one of the Midas_Data_Types values defined in midas.h
pdata (void **) –
pointer to the data area of the newly created bank

Returns:

void

Declared in include/midas.h:1962, defined in src/midas.cxx:18039

bk_find

INT bk_find(const BANK_HEADER * pbkh, const char *name, DWORD * bklen, DWORD * bktype, void **pdata)

Finds a MIDAS bank of given name inside an event.

Parameters:

pbkh (const BANK_HEADER *) –
pointer to current composed event
name (const char *) –
bank name to look for
bklen (DWORD *) –
number of elemtents in bank
bktype (DWORD *) –
bank type, one of TID_xxx
pdata (void **) –
pointer to data area of bank, NULL if bank not found

Returns:

INT –
1 if bank found, 0 otherwise

Declared in include/midas.h:1972, defined in src/midas.cxx:18470

bk_init

void bk_init(void *pbh)

Initializes an event for Midas banks structure. Before banks can be created in an event, bk_init() has to be called first.

Parameters:

pbh (void *) –
pointer to the area of event

Declared in include/midas.h:1956, defined in src/midas.cxx:17884

bk_init32

void bk_init32(void *event)

Initializes an event for Midas banks structure for large bank size (> 32KBytes) Before banks can be created in an event, bk_init32() has to be called first.

Parameters:

event (void *) –
pointer to the area of event

Returns:

void

Declared in include/midas.h:1957, defined in src/midas.cxx:17947

bk_init32a

void bk_init32a(void *event)

Initializes an event for Midas banks structure for large bank size (> 32KBytes) which are aligned on 64-bit boundaries. Before banks can be created in an event, bk_init32a() has to be called first.

Parameters:

event (void *) –
pointer to the area of event

Returns:

void

Declared in include/midas.h:1958, defined in src/midas.cxx:17960

bk_iterate

INT bk_iterate(const void *pbh, BANK ** pbk, void *pdata)

Iterates through banks inside an event. The function can be used to enumerate all banks of an event. The returned pointer to the bank header has following structure:

typedef struct {
char   name[4];
WORD   type;
WORD   data_size;
} BANK;

where type is a TID_xxx value and data_size the size of the bank in bytes.

BANK *pbk;
INT  size;
void *pdata;
char name[5];
pbk = NULL;
do
{
 size = bk_iterate(event, &pbk, &pdata);
 if (pbk == NULL)
  break;
  ((DWORD *)name) = *((DWORD *)(pbk)->name);
 name[4] = 0;
 printf("bank %s found\n", name);
} while(TRUE);

Parameters:

pbh (const void *) –
Pointer to data area of event.
pbk (BANK **) –
pointer to the bank header, must be NULL for the first call to this function.
pdata (void *) –
Pointer to the bank header, must be NULL for the first call to this function

Returns:

INT –
Size of bank in bytes

Declared in include/midas.h:1967, defined in src/midas.cxx:18579

bk_list

INT bk_list(const void *pbh, char *bklist)

Extract the MIDAS bank name listing of an event. The bklist should be dimensioned with STRING_BANKLIST_MAX which corresponds to a max of BANKLIST_MAX banks (midas.h: 32 banks max).

INT adc_calib(EVENT_HEADER *pheader, void *pevent)
{
  INT    n_adc, nbanks;
  WORD   *pdata;
  char   banklist[STRING_BANKLIST_MAX];

  // Display # of banks and list of banks in the event
  nbanks = bk_list(pevent, banklist);
  printf("#banks:%d List:%s\n", nbanks, banklist);

  // look for ADC0 bank, return if not present
  n_adc = bk_locate(pevent, "ADC0", &pdata);
  ...
}

Parameters:

pbh (const void *) –
pointer to current composed event
bklist (char *) –
returned ASCII string, has to be booked with STRING_BANKLIST_MAX.

Returns:

INT –
number of bank found in this event.

Declared in include/midas.h:1965, defined in src/midas.cxx:18318

bk_locate

INT bk_locate(const void *pbh, const char *name, void *pdata)

Locates a MIDAS bank of given name inside an event.

Parameters:

pbh (const void *) –
pointer to current composed event
name (const char *) –
bank name to look for
pdata (void *) –
pointer to data area of bank, NULL if bank not found

Returns:

INT –
number of values inside the bank

Declared in include/midas.h:1966, defined in src/midas.cxx:18367

bk_size

INT bk_size(const void *pbh)

Returns the size of an event containing banks. The total size of an event is the value returned by bk_size() plus the size of the event header (sizeof(EVENT_HEADER)).

Parameters:

pbh (const void *) –
pointer to the area of event

Returns:

INT –
number of bytes contained in data area of event

Declared in include/midas.h:1961, defined in src/midas.cxx:17973

bk_swap

INT bk_swap(void *event, BOOL force)

Swaps bytes from little endian to big endian or vice versa for a whole event.

An event contains a flag which is set by bk_init() to identify the endian format of an event. If force is FALSE, this flag is evaluated and the event is only swapped if it is in the "wrong" format for this system. An event can be swapped to the "wrong" format on purpose for example by a front-end which wants to produce events in a "right" format for a back-end analyzer which has different byte ordering.

Parameters:

event (void *) –
pointer to data area of event
force (BOOL) –
If TRUE, the event is always swapped, if FALSE, the event is only swapped if it is in the wrong format.

Returns:

INT –
1==event has been swap, 0==event has not been swapped.

Declared in include/midas.h:1971, defined in src/midas.cxx:18690