Recovering run state and run variable data

SpecTcl Home  General Information User Guide Programmer's Guide Obtaining and Installing

This page describes how to recover run state and run variable data produced by the production readout software. Run state and run variables are TCL variables. Within production readout, run state variables are write locked while a run is in progress. Run variables, by contrast may change.

The software described on this page analyzes the NSCL data buffers created by the production readout software, recreating the run state and run variables.

The remainder of this document:

• Describes how to enable runstate and runvariable processing
• Describes the programmatic services that make runstate and runvariable data available to C/C++ user written software you have integrated with SpecTcl. Note that user written TCL Scripts can just directly reference run state and run variables, as they are converted to ordinary TCL variables.

Enabling Run State and run variable processing

The run state and run variable processing is implemented as callbacks within the NSCL buffer processing framework used by the scaler buffer processing software. The simplest way to enable run statne and run variable processing is to:

1. Enable scaler buffer processing
2. Add to that run state and run variable processing

To add runstate and run variable processing to scaler buffer processing you must make modifications to your MySpecTclApp.cpp file that:

1. Include header files that define the Documentation callback
2. Register this callback to be invoked when the analysis framework encounters runvariable and run state buffers

Including header files that define the documentation callback

The code fragment below shows additional header files that must be included in your MySpecTclApp.cpp file:

#include <buftypes.h>
#include <Globals.h>
#include <DocumentationCallback.h>

Globals.h enables you to locate the TCL interpreter used by SpecTcl. DocumentationCallback.h defines the callbackthat decodes the documentation buffers containing runstate and run variables.

Adding documentation callbacks

The code fragment below taken from CMySpecTclApp::CreateAnalysisPipline shows how to add the documentation buffer processing callback to the scaler analysis framework.

    CDocumentationCallback* pDocCallback = new CDocumentationCallback(gpInterpreter);
    CBufferProcessor* pProcessor = ScalerStage.getProcessor();
    pProcessor->addCallback(STATEVARBF, *pDocCallback);
    pProcessor->addCallback(RUNVARBF, *pDocCallback);

    RegisterEventProcessor(ScalerStage);    // Pre-existing for scaler analysis.

The first line creates a documentation callback object. This object will actually analyze the buffers. Next the scaler event processor is asked to give its Buffer processing object (see the buffer processor man page for more information about this). Finally,the documentation callback is registered to process both STATEVARBF (run state variable), and RUNVARBF (run variable) buffers before the scaler event processor is registered on the analysis pipeline.

Services offered to C/C++ software

If you maintain a pointer to the CDocumentationCallback object you created, you can access the services of this object from within your own C++ application specific code. The member functions below are available for your use:

class CDocumentationCallback {
public:
  STD(string) getValue(STD(string) name) const;
  STD(string) getElementValue(STD(string) name, STD(string) element) const;
  void addChangeHandler(STD(string) name, CVariableTraceCallback& callback);
  void removeChangeHandler(STD(string) name, CVariableTraceCallback& callback);

};

• getValue Returns as a string the value of a TCL variable. If you want to return an array element, use TCL array element access syntax, (e.g. myarray(element)). If the variable does not exist, this call will throw a CDocumentationException. This exception is a subclass of CException and so a catch of CException& will catch this.
• getElementValueIs similar to getValue, however it is buit to make retrieving array element values simpler. The name parametsr is the name of an array, and element is the name of the element from within the array whose value you want to retrieve. The function also throws a CDocumentationException in the event the array element is not defined.
• addChangeHandlerAllows you to add a variable traceback object (see the CVariableTraceCallback manpage for more information) to the specified variable. name is the name of the variable to trace. If you want to trace an entire array, provide the name of the array. To trace an element of an array, provide the full element name (e.g. myarray(element)). The trace callback will only be called when the variable is modified.
• removeChangeHandlerAllows you to remove a previously established change handler from the variable, array or array element specified by name. If the specified callback has note been registered on name then a CDocumentationException is thrown.
  Top

  ---

  Last modified: Fri Feb 25, 2005 by Ron Fox: fox@nscl.msu.edu
  © Copyright NSCL 1999, All rights reserved