GLAST / LAT > DAQ and FSW > FSW > Doxygen Index> QSEC / V3-1-1 > qsec / linux-gcc

Interface   Data Structures   File List   Data Fields   Globals  
g » glast » flight » QSD » source » QSEC » V3-1-1 » QSEC

QSEC.h File Reference

Interface to the calibration event context updating routines. More...

#include "QSEC/QSEC_ctx.h"
#include "EDS/EBF_gem.h"

Typedefs

typedef enum
_QSEC_STATUS_K 		QSEC_STATUS_K
 Enumeration of the status codes.

Enumerations

enum  _QSEC_STATUS_K {
  QSEC_STATUS_K_ERR = -1,
  QSEC_STATUS_K_TOO_SMALL = -2,
  QSEC_STATUS_K_NOGEM = -8,
  QSEC_STATUS_K_OVRRUN = -9,
  QSEC_STATUS_K_UNDRUN = -10,
  QSEC_STATUS_K_INCLEN = -11
}
 Enumeration of the status codes. More...

Functions

QSEC * QSEC_alloc (void)
 Allocate and construct the QSEC handle.
void QSEC_updateAtDatagram (void *qsec, const LSF_datagram *dgm)
 Update the run oriented information in the event context using the information from the event datagram.
void QSEC_updateAtContribution (void *qsec, const LSF_contribution *ctb)
 Update the context based on the contribution.
int QSEC_updateAtRecord (void *qsec, const LSF_record *rec)
 Update the context based on the record.
int QSEC_expand (QSEC *qsec, const LSF_record *rec, QSE_ebfEvt *ebf, int ebf_size, int *ret_size)
 Expand the event into EBF format.
void QSEC_destruct (QSEC *qsec)
 Destroy the QSEC handle.
const QSE_ctx * QSEC_stdCtxGet (const QSEC *qsec)
 Return a pointer to the standard QSE context block.
const QSEC_ctx * QSEC_appCtxGet (const QSEC *qsec)
 Return a pointer to the public QSEC application specific context block.
const EBF_gem * QSEC_gemGet (const QSEC *qsec)
 Return a pointer to the expanded GEM data.
unsigned int QSEC_sizeof (void *prm)
 Return the size, in bytes, of the handle for updating the standard event meta-information.
QSEC * QSEC_construct (QSEC *qsec, void *prm)
 Construct (initializes) the handle for updating the standard event meta-information.
void QSEC_reportExpand (const QSEC *qsec, FILE *fp, unsigned int optns)
 Report the contents of an expansion.

Detailed Description

Interface to the calibration event context updating routines.

Author:
James Swain & Owen Saxton
Id

Typedef Documentation

typedef enum _QSEC_STATUS_K QSEC_STATUS_K

Enumeration of the status codes.

The errors breakdown into roughly two categories
  1. User errors
  2. Internal errors
User Errors
Currently there is one user errors.
  1. The user specified an output buffer that was too small to accommodate the event.
Internal Errors
The candidates for causing these errors are
  1. Internal error on the encoding side, i.e. the software that formatted and wrote the event out has an error.
  2. Internal error on the decoding side, i.e. the software that is decoding the event has an error.
  3. The input data was corrupted (for example a memory overwrite) after it was read in.

Enumeration Type Documentation

enum _QSEC_STATUS_K

Enumeration of the status codes.

The errors breakdown into roughly two categories
  1. User errors
  2. Internal errors
User Errors
Currently there is one user errors.
  1. The user specified an output buffer that was too small to accommodate the event.
Internal Errors
The candidates for causing these errors are
  1. Internal error on the encoding side, i.e. the software that formatted and wrote the event out has an error.
  2. Internal error on the decoding side, i.e. the software that is decoding the event has an error.
  3. The input data was corrupted (for example a memory overwrite) after it was read in.
Enumerator:
QSEC_STATUS_K_ERR  Generic failure
QSEC_STATUS_K_TOO_SMALL  The user provided buffer is too small to accommodate the expanded event.
QSEC_STATUS_K_NOGEM  The GEM contribution could not be located in the input data. Without the GEM contribution, the extended counter information cannot be updated. This is likely caused by an internal error. It is possible that there is a bug in the encoding/decoding of the data or that the input data was somehow corrupted.
QSEC_STATUS_K_OVRRUN  There was data still in the input was still left after expanding thought it had completed. This is likely caused by an internal error. It is possible that there is a bug in the encoding/decoding of the data or that the input data was somehow corrupted.
QSEC_STATUS_K_UNDRUN  The input data was exhausted before the expansion thought it had completed. This is likely caused by an internal error. It is possible that there is a bug in the encoding/decoding of the data or that the input data was somehow corrupted.
QSEC_STATUS_K_INCLEN  An inconsistency in the calculation of the number of bytes to in the output stream and actual number. This is purely an internal error in the expansion/unpacking routines

Function Documentation

QSEC* QSEC_alloc ( void   ) 

Allocate and construct the QSEC handle.

Returns:
A pointer to the allocated and constructed QSEC handle

const QSEC_ctx* QSEC_appCtxGet ( const QSEC *  qsec  ) 

Return a pointer to the public QSEC application specific context block.

This routine is just an accessor to keep the structure of QSEC private.

Parameters:
qsec The calibration event handle
Returns:
A pointer to the QSEC application specific context block

QSEC* QSEC_construct ( QSEC *  qsec,
void *  prm 
)

Construct (initializes) the handle for updating the standard event meta-information.

Parameters:
qsec The handle to initialize, if specified as NULL, one will be allocated
prm A run-time set parameter used to stylize the configuration
Returns:
The QSEC context structure

void QSEC_destruct ( QSEC *  qsec  ) 

Destroy the QSEC handle.

Parameters:
qsec Pointer to the QSEC handle to delete.

int QSEC_expand ( QSEC *  qsec,
const LSF_record *  rec,
QSE_ebfEvt *  ebf,
int  ebf_size,
int *  ret_size 
)

Expand the event into EBF format.

This just launders the call

Parameters:
qsec The calibration event handle
rec The LSF record containing the event
ebf The ebf buffer to expand the event into, this pointer must be 32-bit aligned
ebf_size The size, in bytes, of the buffer
ret_size Returned as the status of the expand
Return values:
0 Successful expand
<0 Failure, see the enumeration QSEC_STATUS_K for the reasons

const EBF_gem* QSEC_gemGet ( const QSEC *  qsec  ) 

Return a pointer to the expanded GEM data.

This routine is just an accessor to keep the structure of QSEC private.

Parameters:
qsec The calibration event handle
Returns:
A pointer to the expanded GEM record

void QSEC_reportExpand ( const QSEC *  qsec,
FILE *  fp,
unsigned int  optns 
)

Report the contents of an expansion.

Parameters:
qsec The calibration event handle
fp Pointer to the destination file
optns Options controlling the report (not used)

unsigned int QSEC_sizeof ( void *  prm  ) 

Return the size, in bytes, of the handle for updating the standard event meta-information.

Parameters:
prm A run-time set parameter used to stylize the configuration
Returns:
The size, in bytes, of the handle for updating the standard event meta-information

const QSE_ctx* QSEC_stdCtxGet ( const QSEC *  qsec  ) 

Return a pointer to the standard QSE context block.

This routine is just an accessor to keep the structure of QSEC private.

Parameters:
qsec The calibration event handle
Returns:
A pointer to the QSE context block

void QSEC_updateAtContribution ( void *  qsec,
const LSF_contribution *  ctb 
)

Update the context based on the contribution.

Parameters:
qsec The calibration event handle to update
ctb The contribution

void QSEC_updateAtDatagram ( void *  qsec,
const LSF_datagram *  dgm 
)

Update the run oriented information in the event context using the information from the event datagram.

Parameters:
qsec The calibration event handle
dgm The event datagram
Note:
The root contribution is opaque to the caller, so QSEC must handle the contributions within the root. There are two strategies one could use
  1. Call LSF_scanContribtions and let it parse through them and invoke a user call back routine
  2. Do the scan by hand.
Initially I have opted for strategy #1, but the second strategy makes detailed error checking easier. For example, if the sequence of the contributions is fixed, it is likely easier to do this when doing the scan by hand.

int QSEC_updateAtRecord ( void *  qsec,
const LSF_record *  rec 
)

Update the context based on the record.

Parameters:
qsec The calibration event handle to update
rec The event record
Return values:
>0 If successful update to an event record
<0 If unsuccessful update to an event record
0 If this was not an event record

Generated on Thu Aug 20 15:29:46 2009 by  doxygen 1.5.3