QSTD_labels.h File Reference

Defines the ASCII labels for the Science Statistics Physics entries. More...

Typedefs
typedef struct _QSTD_labels	QSTD_labels
typedef struct _QSTD_labelsHandlers	QSTD_labelsHandlers
typedef struct _QSTD_labelsVersions	QSTD_labelsVersions
Functions
const QSTD_labels *	QSTD_labelsHandlersResolveFull (const QSTD_labelsHandlers *handlers, unsigned int handlerId, unsigned int version)
	Retrieves a pointer for the labels for the specified handler.
const QSTD_labelsVersions *	QSTD_labelsHandlersResolve (const QSTD_labelsHandlers *handlers, unsigned int handleId)
	Retrieves a pointer for the labels for all the versions of the specified handler.
const QSTD_labels *	QSTD_labelsVersionsResolve (const QSTD_labelsVersions *versions, unsigned int version)
	Retrieves a pointer for the labels for the specified version.
const char *	QSTD_labelsHandlerGet (const QSTD_labels *labels)
	Retrieves a pointer to title string (the handler name).
const char *	QSTD_labelsConditionGet (const QSTD_labels *labels, unsigned int conditionId)
	Retrieves a pointer to condition string (the condition's name).

---

Detailed Description

Defines the ASCII labels for the Science Statistics Physics entries.

Author:

JJRussell - russell@slac.stanford.edu

   CVS $Id: QSTD_labels.h,v 1.1 2008/06/10 22:25:45 russell Exp $

Overview

The label facility recognizes that a handler's standard statistics not only has its own set of strings for labeling the handler itself and the 32 condition counters, but also accommodates the notion that these labels may change as the statistics evolves in times. Therefore, the label facitily is laid out in hierarchy that is three deep

• QSTD_labels, this sits at the bottom of the hierarchy and binds the handler and condition names together. It is specific to a given version and of a given handler.

• QSTD_labelsVersions, this sits in the middle of the hierarchy and binds all the versions of the QSTD_labels of a given handler together. As such, it is specific to a handler.

• QSTD_labelsHandlers, this sits at the top of the hierarchy and binds the QSTD_labelsVersions for all the handlers together.

Implementation Explanation

Note that this defines an interface, but not an implementation. There is a default implementation in the QSSP source directory based on static strings. This is not ideal, because it binds all this information in one place when, in fact, this information should be sourced from the packages that define the standard statistics for each handler. This, however, is a logistics nightmare at this point because that would require modifying packages that live on the embedded side of the great divide, something that is a administrative no-no. So, one is left with this rather unsatistfying solution for the time-being.

Typical usage

Assuming one has

• A handler identifier and a version number called handler and version
• A QSTD_labelsHandlers structure called handlers

the code to find the labels for this version of the handler statistics would be

        QSTD_labelsVersions *versions;
        QSTD_labels           *labels;
        const char      *handler_name;
        const char    *condition_name;

        / * 
          |    Fetch the versions for this handler, 
          |    then  the labels   for this version
          |
          |    One could also use the convenience routine
          |
          |     labels = QSTD_labelsHandlersResolveFull (handlers,
          |                                              handler,
          |                                              version);
 /
        versions = QSTD_labelsHandlersResolve (handlers, handler);
        labels   = QSTD_labelsVersionsResolve (versions, version);

        handler_name       = QSTD_labelsHandlerGet (labels);
        printf ("Handler: %s\n", handler_name);
        for (idx = 0; idx < 32; idx++)
        {
             condition_name = QSTD_labelsConditionGet (labels, idx);
             printf ("%s %u\n", condition_name, condition_counters[idx]);
        }

Additional Notes

The routines are set-up such that every handler/version will resolve to some QSTD_label structure, even if it is a default structure that only yields generic labels.

---

Function Documentation

const char* QSTD_labelsConditionGet	(	const QSTD_labels *	labels,
		unsigned int	conditionId
	)

Retrieves a pointer to condition string (the condition's name).

Parameters:

	labels	The label structure for the handler
	conditionId	The condition identify [0,31]

References _QSTD_labels::conditions.

const char* QSTD_labelsHandlerGet

(

const QSTD_labels *

labels

)

Retrieves a pointer to title string (the handler name).

Parameters:

labels

The label structure for the handler

References _QSTD_labels::handler.

const QSTD_labelsVersions* QSTD_labelsHandlersResolve	(	const QSTD_labelsHandlers *	handlers,
		unsigned int	handler
	)

Retrieves a pointer for the labels for all the versions of the specified handler.

Parameters:

	handlers	The labels for all the handlers
	handler	The handler's identifier (e.g. EH_ID_K_GAMMA, etc)

References _QSTD_labelsHandlers::versions.

Referenced by QSTD_labelsHandlersResolveFull().

const QSTD_labels* QSTD_labelsHandlersResolveFull	(	const QSTD_labelsHandlers *	handlers,
		unsigned int	handler,
		unsigned int	version
	)

Retrieves a pointer for the labels for the specified handler.

Parameters:

	handlers	The labels for all the handlers
	handler	The handler's identifier (e.g. EH_ID_K_GAMMA, etc)
	version	The version number

References QSTD_labelsHandlersResolve(), and QSTD_labelsVersionsResolve().

Referenced by QSTD_updateAtDatagram().

const QSTD_labels* QSTD_labelsVersionsResolve	(	const QSTD_labelsVersions *	versions,
		unsigned int	version
	)

Retrieves a pointer for the labels for the specified version.

Parameters:

	versions	The labels for all versions of the handler
	version	The version number

References _QSTD_labelsVersions::cnt, and _QSTD_labelsVersions::labels.

Referenced by QSTD_labelsHandlersResolveFull().