\hypertarget{QSEC_8h}{
\section{QSEC.h File Reference}
\label{QSEC_8h}\index{QSEC.h@{QSEC.h}}
}
Interface to the calibration event context updating routines. 

{\tt \#include \char`\"{}QSEC/QSEC\_\-ctx.h\char`\"{}}\par


Include dependency graph for QSEC.h:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=186pt]{QSEC_8h__incl}
\end{center}
\end{figure}


This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=91pt]{QSEC_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef enum \hyperlink{QSEC_8h_a18}{\_\-QSEP\_\-STATUS\_\-K} \hyperlink{QSEC_8h_a0}{QSEC\_\-STATUS\_\-K}
\begin{CompactList}\small\item\em Enumeration of the status codes. \item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum \hyperlink{QSEC_8h_a18}{\_\-QSEP\_\-STATUS\_\-K} \{ \par
\hyperlink{QSEC_8h_a18a1}{QSEC\_\-STATUS\_\-K\_\-ERR} =  -1, 
\par
\hyperlink{QSEC_8h_a18a2}{QSEC\_\-STATUS\_\-K\_\-TOO\_\-SMALL} =  -2, 
\par
\hyperlink{QSEC_8h_a18a3}{QSEC\_\-STATUS\_\-K\_\-NOGEM} =  -8, 
\par
\hyperlink{QSEC_8h_a18a4}{QSEC\_\-STATUS\_\-K\_\-OVRRUN} =  -9, 
\par
\hyperlink{QSEC_8h_a18a5}{QSEC\_\-STATUS\_\-K\_\-UNDRUN} =  -10, 
\par
\hyperlink{QSEC_8h_a18a6}{QSEC\_\-STATUS\_\-K\_\-INCLEN} =  -11
 \}
\begin{CompactList}\small\item\em Enumeration of the status codes. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
QSEC $\ast$ \hyperlink{QSEC_8h_a7}{QSEC\_\-alloc} (void)
\begin{CompactList}\small\item\em Allocate and construct the QSEC handle. \item\end{CompactList}\item 
void \hyperlink{QSEC_8h_a8}{QSEC\_\-update\-At\-Datagram} (QSEC $\ast$qsec, const LSF\_\-datagram $\ast$dgm)
\begin{CompactList}\small\item\em Update the run oriented information in the event context using the information from the event datagram. \item\end{CompactList}\item 
void \hyperlink{QSEC_8h_a9}{QSEC\_\-update\-At\-Contribution} (QSEC $\ast$qsec, const LSF\_\-contribution $\ast$ctb)
\begin{CompactList}\small\item\em Update the context based on the contribution. \item\end{CompactList}\item 
int \hyperlink{QSEC_8h_a10}{QSEC\_\-update\-At\-Record} (QSEC $\ast$qsec, const LSF\_\-record $\ast$rec)
\begin{CompactList}\small\item\em Update the context based on the record. \item\end{CompactList}\item 
int \hyperlink{QSEC_8h_a11}{QSEC\_\-expand} (QSEC $\ast$qsec, const LSF\_\-record $\ast$rec, QSE\_\-ebf\-Evt $\ast$ebf, int ebf\_\-size, int $\ast$ret\_\-size)
\begin{CompactList}\small\item\em Expand the event into EBF format. \item\end{CompactList}\item 
void \hyperlink{QSEC_8h_a12}{QSEC\_\-destruct} (QSEC $\ast$qsec)
\begin{CompactList}\small\item\em Destroy the QSEC handle. \item\end{CompactList}\item 
const QSE\_\-ctx $\ast$ \hyperlink{QSEC_8h_a13}{QSEC\_\-std\-Ctx\-Get} (const QSEC $\ast$qsec)
\begin{CompactList}\small\item\em Return a pointer to the standard QSE context block. \item\end{CompactList}\item 
const \hyperlink{struct__QSEC__ctx}{QSEC\_\-ctx} $\ast$ \hyperlink{QSEC_8h_a14}{QSEC\_\-app\-Ctx\-Get} (const QSEC $\ast$qsec)
\begin{CompactList}\small\item\em Return a pointer to the public QSEC application specific context block. \item\end{CompactList}\item 
unsigned int \hyperlink{QSEC_8h_a15}{QSEC\_\-sizeof} (void $\ast$prm)
\begin{CompactList}\small\item\em Return the size, in bytes, of the handle for updating the standard event meta-information. \item\end{CompactList}\item 
QSEC $\ast$ \hyperlink{QSEC_8h_a16}{QSEC\_\-construct} (QSEC $\ast$qsec, void $\ast$prm)
\begin{CompactList}\small\item\em Construct (initializes) the handle for updating the standard event meta-information. \item\end{CompactList}\item 
void \hyperlink{QSEC_8h_a17}{QSEC\_\-report\-Expand} (const QSEC $\ast$qsec, FILE $\ast$fp, unsigned int optns)
\begin{CompactList}\small\item\em Report the contents of an expansion. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Interface to the calibration event context updating routines. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
\begin{Desc}
\item[Id]\hyperlink{QSEC_8h}{QSEC.h},v 1.3 2007/04/05 22:36:49 saxton Exp \end{Desc}


\subsection{Typedef Documentation}
\hypertarget{QSEC_8h_a0}{
\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K@{QSEC\_\-STATUS\_\-K}}
\index{QSEC_STATUS_K@{QSEC\_\-STATUS\_\-K}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-STATUS\_\-K]{\setlength{\rightskip}{0pt plus 5cm}typedef enum \hyperlink{QSEC_8h_a18}{\_\-QSEP\_\-STATUS\_\-K}  \hyperlink{QSEC_8h_a0}{QSEC\_\-STATUS\_\-K}}}
\label{QSEC_8h_a0}


Enumeration of the status codes. 

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


\subsection{Enumeration Type Documentation}
\hypertarget{QSEC_8h_a18}{
\index{QSEC.h@{QSEC.h}!_QSEP_STATUS_K@{\_\-QSEP\_\-STATUS\_\-K}}
\index{_QSEP_STATUS_K@{\_\-QSEP\_\-STATUS\_\-K}!QSEC.h@{QSEC.h}}
\subsubsection[\_\-QSEP\_\-STATUS\_\-K]{\setlength{\rightskip}{0pt plus 5cm}enum \hyperlink{QSEC_8h_a18}{\_\-QSEP\_\-STATUS\_\-K}}}
\label{QSEC_8h_a18}


Enumeration of the status codes. 

\begin{Desc}
\item[]The errors breakdown into roughly two categories\begin{enumerate}
\item User errors\item Internal errors\end{enumerate}
\end{Desc}
\begin{Desc}
\item[User Errors]Currently there is one user errors.\begin{enumerate}
\item The user specified an output buffer that was too small to accommodate the event.\end{enumerate}
\end{Desc}
\begin{Desc}
\item[Internal Errors]The candidates for causing these errors are\begin{enumerate}
\item Internal error on the encoding side, i.e. the software that formatted and wrote the event out has an error.\item Internal error on the decoding side, i.e. the software that is decoding the event has an error.\item The input data was corrupted (for example a memory overwrite) after it was read in.\end{enumerate}
\end{Desc}
\begin{Desc}
\item[Enumerator: ]\par
\begin{description}
\index{QSEC_STATUS_K_ERR@{QSEC\_\-STATUS\_\-K\_\-ERR}!QSEC.h@{QSEC.h}}\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K_ERR@{QSEC\_\-STATUS\_\-K\_\-ERR}}\item[{\em 
\hypertarget{QSEC_8h_a18a1}{
QSEC\_\-STATUS\_\-K\_\-ERR}
\label{QSEC_8h_a18a1}
}]Generic failure \index{QSEC_STATUS_K_TOO_SMALL@{QSEC\_\-STATUS\_\-K\_\-TOO\_\-SMALL}!QSEC.h@{QSEC.h}}\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K_TOO_SMALL@{QSEC\_\-STATUS\_\-K\_\-TOO\_\-SMALL}}\item[{\em 
\hypertarget{QSEC_8h_a18a2}{
QSEC\_\-STATUS\_\-K\_\-TOO\_\-SMALL}
\label{QSEC_8h_a18a2}
}]The user provided buffer is too small to accommodate the expanded event. \index{QSEC_STATUS_K_NOGEM@{QSEC\_\-STATUS\_\-K\_\-NOGEM}!QSEC.h@{QSEC.h}}\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K_NOGEM@{QSEC\_\-STATUS\_\-K\_\-NOGEM}}\item[{\em 
\hypertarget{QSEC_8h_a18a3}{
QSEC\_\-STATUS\_\-K\_\-NOGEM}
\label{QSEC_8h_a18a3}
}]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. \index{QSEC_STATUS_K_OVRRUN@{QSEC\_\-STATUS\_\-K\_\-OVRRUN}!QSEC.h@{QSEC.h}}\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K_OVRRUN@{QSEC\_\-STATUS\_\-K\_\-OVRRUN}}\item[{\em 
\hypertarget{QSEC_8h_a18a4}{
QSEC\_\-STATUS\_\-K\_\-OVRRUN}
\label{QSEC_8h_a18a4}
}]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. \index{QSEC_STATUS_K_UNDRUN@{QSEC\_\-STATUS\_\-K\_\-UNDRUN}!QSEC.h@{QSEC.h}}\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K_UNDRUN@{QSEC\_\-STATUS\_\-K\_\-UNDRUN}}\item[{\em 
\hypertarget{QSEC_8h_a18a5}{
QSEC\_\-STATUS\_\-K\_\-UNDRUN}
\label{QSEC_8h_a18a5}
}]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. \index{QSEC_STATUS_K_INCLEN@{QSEC\_\-STATUS\_\-K\_\-INCLEN}!QSEC.h@{QSEC.h}}\index{QSEC.h@{QSEC.h}!QSEC_STATUS_K_INCLEN@{QSEC\_\-STATUS\_\-K\_\-INCLEN}}\item[{\em 
\hypertarget{QSEC_8h_a18a6}{
QSEC\_\-STATUS\_\-K\_\-INCLEN}
\label{QSEC_8h_a18a6}
}]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 \end{description}
\end{Desc}



\subsection{Function Documentation}
\hypertarget{QSEC_8h_a7}{
\index{QSEC.h@{QSEC.h}!QSEC_alloc@{QSEC\_\-alloc}}
\index{QSEC_alloc@{QSEC\_\-alloc}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-alloc]{\setlength{\rightskip}{0pt plus 5cm}QSEC$\ast$ QSEC\_\-alloc (void)}}
\label{QSEC_8h_a7}


Allocate and construct the QSEC handle. 

\begin{Desc}
\item[Returns:]A pointer to the allocated and constructed QSEC handle\end{Desc}
\hypertarget{QSEC_8h_a14}{
\index{QSEC.h@{QSEC.h}!QSEC_appCtxGet@{QSEC\_\-appCtxGet}}
\index{QSEC_appCtxGet@{QSEC\_\-appCtxGet}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-appCtxGet]{\setlength{\rightskip}{0pt plus 5cm}const \hyperlink{struct__QSEC__ctx}{QSEC\_\-ctx}$\ast$ QSEC\_\-app\-Ctx\-Get (const QSEC $\ast$ {\em qsec})}}
\label{QSEC_8h_a14}


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

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the QSEC application specific context block\end{Desc}
\hypertarget{QSEC_8h_a16}{
\index{QSEC.h@{QSEC.h}!QSEC_construct@{QSEC\_\-construct}}
\index{QSEC_construct@{QSEC\_\-construct}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-construct]{\setlength{\rightskip}{0pt plus 5cm}QSEC$\ast$ QSEC\_\-construct (QSEC $\ast$ {\em qsec}, void $\ast$ {\em prm})}}
\label{QSEC_8h_a16}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The handle to initialize, if specified as NULL, one will be allocated\item[{\em prm}]A run-time set parameter used to stylize the configuration\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The QSEC context structure\end{Desc}
\hypertarget{QSEC_8h_a12}{
\index{QSEC.h@{QSEC.h}!QSEC_destruct@{QSEC\_\-destruct}}
\index{QSEC_destruct@{QSEC\_\-destruct}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-destruct]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-destruct (QSEC $\ast$ {\em qsec})}}
\label{QSEC_8h_a12}


Destroy the QSEC handle. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]Pointer to the QSEC handle to delete.\end{description}
\end{Desc}
\hypertarget{QSEC_8h_a11}{
\index{QSEC.h@{QSEC.h}!QSEC_expand@{QSEC\_\-expand}}
\index{QSEC_expand@{QSEC\_\-expand}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-expand]{\setlength{\rightskip}{0pt plus 5cm}int QSEC\_\-expand (QSEC $\ast$ {\em qsec}, const LSF\_\-record $\ast$ {\em rec}, QSE\_\-ebf\-Evt $\ast$ {\em ebf}, int {\em ebf\_\-size}, int $\ast$ {\em ret\_\-size})}}
\label{QSEC_8h_a11}


Expand the event into EBF format. 

This just launders the call

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle\item[{\em rec}]The LSF record containing the event\item[{\em ebf}]The ebf buffer to expand the event into, this pointer must be 32-bit aligned\item[{\em ebf\_\-size}]The size, in bytes, of the buffer\item[{\em ret\_\-size}]Returned as the status of the expand\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Successful expand \item[{\em $<$0}]Failure, see the enumeration QSEC\_\-STATUS\_\-K for the reasons\end{description}
\end{Desc}
\hypertarget{QSEC_8h_a17}{
\index{QSEC.h@{QSEC.h}!QSEC_reportExpand@{QSEC\_\-reportExpand}}
\index{QSEC_reportExpand@{QSEC\_\-reportExpand}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-reportExpand]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-report\-Expand (const QSEC $\ast$ {\em qsec}, FILE $\ast$ {\em fp}, unsigned int {\em optns})}}
\label{QSEC_8h_a17}


Report the contents of an expansion. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle\item[{\em fp}]Pointer to the destination file\item[{\em optns}]Options controlling the report (not used)\end{description}
\end{Desc}
\hypertarget{QSEC_8h_a15}{
\index{QSEC.h@{QSEC.h}!QSEC_sizeof@{QSEC\_\-sizeof}}
\index{QSEC_sizeof@{QSEC\_\-sizeof}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}unsigned int QSEC\_\-sizeof (void $\ast$ {\em prm})}}
\label{QSEC_8h_a15}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em prm}]A run-time set parameter used to stylize the configuration\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The size, in bytes, of the handle for updating the standard event meta-information\end{Desc}
\hypertarget{QSEC_8h_a13}{
\index{QSEC.h@{QSEC.h}!QSEC_stdCtxGet@{QSEC\_\-stdCtxGet}}
\index{QSEC_stdCtxGet@{QSEC\_\-stdCtxGet}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-stdCtxGet]{\setlength{\rightskip}{0pt plus 5cm}const QSE\_\-ctx$\ast$ QSEC\_\-std\-Ctx\-Get (const QSEC $\ast$ {\em qsec})}}
\label{QSEC_8h_a13}


Return a pointer to the standard QSE context block. 

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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the QSE context block\end{Desc}
\hypertarget{QSEC_8h_a9}{
\index{QSEC.h@{QSEC.h}!QSEC_updateAtContribution@{QSEC\_\-updateAtContribution}}
\index{QSEC_updateAtContribution@{QSEC\_\-updateAtContribution}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-updateAtContribution]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-update\-At\-Contribution (QSEC $\ast$ {\em qsec}, const LSF\_\-contribution $\ast$ {\em ctb})}}
\label{QSEC_8h_a9}


Update the context based on the contribution. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle to update\item[{\em ctb}]The contribution\end{description}
\end{Desc}
\hypertarget{QSEC_8h_a8}{
\index{QSEC.h@{QSEC.h}!QSEC_updateAtDatagram@{QSEC\_\-updateAtDatagram}}
\index{QSEC_updateAtDatagram@{QSEC\_\-updateAtDatagram}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-updateAtDatagram]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-update\-At\-Datagram (QSEC $\ast$ {\em qsec}, const LSF\_\-datagram $\ast$ {\em dgm})}}
\label{QSEC_8h_a8}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle\item[{\em dgm}]The event datagram\end{description}
\end{Desc}
\begin{Desc}
\item[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\begin{enumerate}
\item Call LSF\_\-scan\-Contribtions and let it parse through them and invoke a user call back routine\item Do the scan by hand.\end{enumerate}
\end{Desc}
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.\hypertarget{QSEC_8h_a10}{
\index{QSEC.h@{QSEC.h}!QSEC_updateAtRecord@{QSEC\_\-updateAtRecord}}
\index{QSEC_updateAtRecord@{QSEC\_\-updateAtRecord}!QSEC.h@{QSEC.h}}
\subsubsection[QSEC\_\-updateAtRecord]{\setlength{\rightskip}{0pt plus 5cm}int QSEC\_\-update\-At\-Record (QSEC $\ast$ {\em qsec}, const LSF\_\-record $\ast$ {\em rec})}}
\label{QSEC_8h_a10}


Update the context based on the record. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em qsec}]The calibration event handle to update\item[{\em rec}]The event record\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em $>$0}]If successful update to an event record \item[{\em $<$0}]If unsuccessful update to an event record \item[{\em 0}]If this was not an event record\end{description}
\end{Desc}