Latch Database

The data unpacking routine unpacks the latch information into GROUP_LATCHES.

To uniquely identify each latched bit, one has to know what word in GROUP_LATCHES to take and which bit inside this word to look at.

The "Latch Database" package described in this document was written to make the use of GROUP_LATCH easier. For example, it provides functions to access the latch bits using symbolic names, such as "lev1a1", "tpxmult1", "tpx2bit3", etc...

Header files, Libraries, Sources and Map files

The C header file latchDatabase.h defines the data structures and functions used by the latch database.

Programs using the latch database should link with the libdata.a library.

The source code is located in the libdata subsystem.

The database data file is located in the map manager file db-files.Map, subsystem db-files, item latches.

Format of the Map file

The database data file has the following format, one entry per bit:

latches.nbits:	256

latches.1.name: triggerbit1
latches.1.word: 0
latches.1.bit: 0
latches.1.used: 1

latches.2.name: triggerbit2
latches.2.word: 0
latches.2.bit: 1
latches.2.used: 1

...

• latches.nbits --- number of entries in the database
• latches.NNN.name --- name of the latch bit NNN. The name is empty for unused database slots.
• latches.NNN.word --- index of the latch word in GROUP_LATCHES
• latches.NNN.bit --- the location of th ebit inside the word, counting from 0.
• latches.NNN.used --- 0 if this bit is unused, !0 if it is used.

Format of the latchDatabase_t array

typedef struct
{
  int flags;		/* the flags are defined in the header file */
  const char *name;     /* name of the bit */
  int offset;           /* offset into the GROUP_LATCHES group, counting from zero */
  int bit;              /* bit number inside the word, range is from 0 to 31 */

} latchDatabaseEntry_t;

typedef struct
{
  int nbits;

  latchDatabaseEntry_t bit[1];

} latchDatabase_t;

Subroutines used to access the latch database

latch_getDatabase(int runNo)

Purpose:

• load the database file into a latchDatabase_t array.

Arguments:

• runNo --- load the database for the given run

Return Value:

• a pointer to the database latchDatabase_t array. This array is allocated dynamically and should be deallocated after use by calling 'free()'.

int latch_lookupDatabase(database,bitName)

Purpose:

• find a bit given it's symbolic name and return it's index in the latchDatabase_t array.

Arguments:

• database --- the latch database returned by the 'latch_getDatabase() call.
• bitName --- the latch bit to find.

Return Value:

• < 0 --- the requested scaler was not found.
• >= 0 --- an index into the latch database.

int latch_getBitValue(latches,database,bitName)

Purpose:

• return the value of the named latch bit.

Arguments:

• latches --- pointer to GROUP_LATCHES
• database -- the latch database
• bitName --- the name of the bit to get

Return Value:

• < 0 ------ error: could not find the requested bit and such.
• 0 or 1 --- the value of the bit

Author: K.Olchanski, 1996-Apr-13