Content-type: text/html Man page of Buffer analysis framework library

Buffer analysis framework library

Section: NSCL Data analysis packages (3)
Updated: 0.1
Index Return to Main Contents
 

NAME

libBufferAnalysis - C interface to buffer analysis framework  

SYNOPSIS


  /* Include these:  */
  #include <config.h>
  #include <BufferAnalysis.h>
  #include <buffer.h>
  #include <buftypes.h>

  /* And you get these  */

  
  typedef void   (NSCLBufferCallback)(unsigned int, const void*, void*);

  void ProcessNSCLBuffer(const void* pBuffer); /*!< Process a single buffer */
  int  ScalersSeen();                          /*!< scalers present this run? */
  int  ScalerCount();                          /*!< # scalers this run */
  unsigned long LastIncrement(unsigned int n); /*!< increment for a channel */
  float Total(unsigned int n);                 /*!< Totals for a channel    */
  long LastIntervalStart();                    /*!< scaler interval start time   */
  long LastIntevalEnd();                       /*!< Scaler interval end time */
  const char*  Title();                        /*!< Run title. */
  unsigned int RunNumber();                    /*!< Number of current run   */
  const char*  RunStartTime();                 /*!< When the run started.  */
  const char*  RunEndTime();                   /*!< When the run ended.    */

  void AddBufferCallback(NSCLBufferCallback* cb,
                         unsigned int        type,
                         void*               userdata); /*!< add a callback */
  void RemoveBufferCallback(NSCLBufferCallback* cb,
                            unsigned int        type,
                            void*               userdata); /*!< get rid of a callback */


  /* In your code: */

  void* gpTCLApplication;

  /* Compile sort of like this */

  cc -o yourprogram yourprogram.c -I$SpecTclHome/include  -L$SpecTclHome/lib \
        -lAnalysis -ltclPlus -lException -lBufferAnalysis

 

DESCRIPTION

BufferAnalysis provides a C language programming framework for ad-hoc analysis of NSCL data buffers. While this framework is used within SpecTcl for NSCL specific buffer processing, you may also use this framework to build ad-hoc analysis programs that don't depend on SpecTcl to operate.

The software decodes buffers by buffer type and dispatches to an ordered set of callbacks that can be established on each buffer type. The library establishes a standard set of callbacks to support the processing of run state transition and scaler buffers to maintain the information that is provided by the other functions in the library.

See EXAMPLES below for more information about how to use this software.  

PUBLIC INTERFACE

typedef void (NSCLBufferCallback)(unsigned int, const void*, void*)
This typedef defines a the form of the callback functions you can register for each buffer type. The first parameter of your callback is the buffer type. This allows the same callback to be registered on multiple buffer types. The second paramter will be a pointer to the buffer. The final parameter will be your userdata parameter to AddBufferCallback passed to your callback without any interpretation.
void ProcessNSCLBuffer(const void* pBuffer)
Call this function to process a bufffer. The buffer type is decoded, and all callbacks (standard and user supplied) are invoked for the appropriate buffer type in the order in which they were registered. Normally your program will register zero or more callbacks, open an event file and then, for each buffer in the file, you will call ProcessBuffer passing it the buffer as a parameter.
int ScalersSeen()fR
This can be called at any time in an analysis (even from within one of your callbacks). ScalersSeen will return nonzero if at least one scaler buffer has been processed in the run being analyzed. The functions that retrieve scaler data will not retrieve valid data unless ScalersSeen would return true.
int ScalerCount()
Returns the number of scalers that were read this run if ScalersSeen() returns true. Otherwise this will return -1. Note that all properly terminated NSCL runs will have at least one scaler buffer, just prior to the end of run.
unsigned long LastIncrement(unsigned int n)
Returns the value of the last increment for scaler channel number n. Scaler channels are numbered from 0. If ScalersSeen() would return false, this will return a -1.
float Total(unsigned int n)
Returns the total number of counts read from a scaler channel n at this point in the run. This will return -1 if ScalerSeen would return false.
long LastIntervalStart()
Returns the number of seconds into the run at which the most recent scaler readout interval started. This will be -1 if ScalersSeen would return false.
long LastIntevalEnd()
Returns the number of seconds in to the run at which the most recent scaler readout interval ended. This will be a -1 if ScalersSeen would return false.
const char* Title()
Returns a pointer to the title string that was present in the most recent control buffer. Control buffers include start, stop, pause, resume buffer types. If there has been no control buffer at this point (only possible if the run is badly formatted enough not to contain a begin buffer, or if you have not sent any buffers to the processing engine), this will returna pointer to an empty string.
const char* RunStartTime()
Returns a pointer to a timestamp string that indicates when the current run was started. This string will have the form ``Month day, year, hh:mm:ss'' For example, the timestamp that describes when this text was being typed in is: ``February 18, 2005, 10:32:40''
const char* RunEndTime()
Returns a pointer to a timestamp string that indicates when the current run was ended. This string will have the same form as the string returned by RunStartTime. If the run has seen a start buffer, but no end buffer yet, this string will be empty.
void AddBufferCallback(NSCLBufferCallback* cb, unsigned inttype, void* userdata)
Call this function to install a callback funtion on a buffer type. The first parameter cb is a pointer to your callback function. type is the type of buffer you want to install a callback on. userdata is user data that will be passed without interpretation to your function when it is called. Note that buffer types are defined symbolically in the header buftypes.h, the structure of the buffer header and buffer bodies are described by the structs in the header buffer.h.
void RemoveBufferCallback(NSCLBufferCallback* cb, unsigned int type, void* userdata)
Call this function to remove a callback from a buffer type. cb is the pointer to the callback you established. type is the buffer type on which it was established. userdata is the userdata that was associated with the callback.
 

EXAMPLES

Note: much error checking that should be done is not done in the examples below in order to keep the brief.

The first example, processes buffers and prints out the scaler totals at the end of a run. Note that this requires on user callbacks. 


#include <config.h>
#include <BufferAnalysis.h>

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

#include <stdio.h>
int main(int argc, char** argv)
{
  unsigned short buffer[4096];
  int fd;
  int nread;
  int i;

  fd = open(argv[1], O_RDONLY);
  
  while((nread = read(fd, buffer, sizeof(buffer))) > 0) {
    ProcessNSCLBuffer(buffer);
  }
  printf("File: %s, Run number %d, Title: %sStarted %s Ended %s,
         argv[1], RunNumber(), Title(), RunStartTime(), RunEndTime());
  printf("Elapsed run time: %d seconds, LastIntervalEnd());
  for(i = 0; i < ScalerCount(); i++) {
    printf("Scaler channel %d total: %f,
           i, Total(i));
  }

  return 0;
}

The second example establishes a scaler buffer callback that prints out scaler increments and totals for each scaler buffer. It uses the fact that callbacks are ordered to avoid having to actually analyze the buffer as all the information it needs is produced by the standard callbacks. In order to identify the run, a begin run callback is also established. 


#include <config.h>
#include <BufferAnalysis.h>
#include <buftypes.h>

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>

#include <stdio.h>


void BeginCallback(unsigned int ntype, const void* pBuffer, void* pData)
{
  const char* pFilename = (const char*)pData;

  printf("Starting analysis of %s, Run %d %sun started: %s,
         pFilename, RunNumber(), Title(), RunStartTime());

}
void ScalerCallback(unsigned int ntype, const void* pBuffer, void* pData)
{
  int i;
  printf("---- Scalers from %d sec to %d sec elapsed time----",
         LastIntervalStart(), LastIntervalEnd());

  for(i =0; i < ScalerCount(); i++) {
    printf("Chanel %d Increments %d  Totals %d,
           i, LastIncrement(i), Total(i));
  }
}


int main(int argc, char** argv)
{
  unsigned short buffer[4096];
  int fd;
  int nread;
  int i;

  fd = open(argv[1], O_RDONLY);
 
  AddBufferCallback(BeginCallback, BEGRUNBF, argv[1]);
  AddBufferCallback(ScalerCallback, SCALERBF, NULL);
 
  while((nread = read(fd, buffer, sizeof(buffer))) > 0) {
    ProcessNSCLBuffer(buffer);
  }

  printf("Run Ended %s, RunEndTime());

  return 0;
}
void*  gpTCLApplication;

 

BUGS

The LastIncrement function can only operate over 1/2 full scale range since it uses negative values to return errors. This provides only 31 bits of scaler range, while some NSCL scaler modules support 32 bits of range.

 

SEE ALSO

CBufferProcessor(3), CBufferCallback(3)
 

Index

NAME
SYNOPSIS
DESCRIPTION
PUBLIC INTERFACE
EXAMPLES
BUGS
SEE ALSO
This document was created by man2html, using the manual pages.
Time: 18:37:14 GMT, February 18, 2005