\chapter{Details on C Module}\label{chap:details-on-C}
Here are described the rules for a C module in detail.
In the following description,
for simplicity,
we assume the name of the module of {\tt User}.

You need to include several header files for a C modules.
Here is a list of headers required.
\begin{center}
\begin{tabular}{lll}
\hline
  header & belongs to & includes \\
\hline
  cfortran.h	& CERN library	& macros to interface C and FORTRAN\\
  hbook.h	& CERN library	& macros of cfortran for HBOOK\\
  asca\_anl.h	& ASCA\_ANL	& constants for flags\\
  cli.h		& ASCA\_ANL	& macros of cfortran for CLI\\
  com.h		& ASCA\_ANL	& macros of cfortran for COM\\
  bnk.h		& ASCA\_ANL	& macros of cfortran for BNK\\
  evs.h		& ASCA\_ANL	& macros of cfortran for EVS\\
  anl\_misc.h	& ASCA\_ANL	& macros of cfortran for utility routines\\
\hline
\end{tabular}
\end{center}

Also,
you have to notice the case of letters here in following points.
\begin{itemize}
\item
All subroutines belonging to the same module
have to have the same case of letters.
For example,
if you define the name as {\tt User},
you have to name {\tt User\_init} and so on,
and you can't write it as {\tt USER\_init} nor {\tt USer\_init}.
\item
All subroutines belonging to libraries\footnote{
For example,
HBOOK, BNK, EVS, and utility routines of the ASCA\_ANL(in libMISC.a)
are written in FORTRAN.
}
written in FORTRAN must call with a name in upper case letters.
For example,
the subroutine {\tt BNKdef}\footnote{
The subroutine in BNK defining a keyword.
}
should be called as {\tt BNKDEF("User:BEGIN")}.
\end{itemize}

In en explanation of "Arguments" of the subroutines
a character in parentheses means
a directional characteristic of the argument;
"(I)" means "input argument"
which is used to pass a value to the subroutine,
"(O)" means "output argument"
which is used to return a value to the caller,
and "(I/O)" means "modification argument"
which is used
both to pass a value to the subroutine
and to return a value to the caller.

You must not change a value of the input argument in any case.
Also,
you have to set a value to the output argument before returning.
In setting a value
you are strongly recommended
to use a constant in a header file "asca\_anl.h"
as described in the following
instead of a raw number.
You may modify a value of the modification argument if necessary.

Furthermore,
you have to satisfy "Requirements" for each subroutine,
and are strongly recommended to follow "Recommendation".

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_init} ---Initialization routine.
\item{Synopsis}\\
   {\tt
     void User\_init(int *status)
   }
\item{Arguments} \\
 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt status} & O & Reserved for the future.\par
                      Should be {\tt ASCA\_ANL\_OK} when it returns.
 \end{tabular}
\item{Required} \\
   In this subroutine you have to set up a few flags by calling EVSdef.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
EVSDEF("User:BEGIN")
EVSDEF("User:ENTRY")
EVSDEF("User:OK")
\end{verbatim}\end{quote}
   The name of these keyword {\tt "User:BEGIN"}, {\tt "User:ENTRY"},
   {\tt "User:OK"} are reserved and can not be changed by the user.
   Also,
   the you must declare version number of this module "User" like this:
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL_PUT_VERSION("User","version 1.0")
\end{verbatim}\end{quote}
   The first argument of {\tt ANL\_PUT\_VERSION} is the module name,
   and second argument is a string (up to 16 characters)
   containing version number.
   You can change a format of expressing the version number as you like.
\item{Comments} \\
   This subroutine is called once before starting data analysis.
   {\tt EVSDEF} and {\tt BNKDEF} (see \S \ref{sec:photon-info})
   are recommended to be in this subroutine.
\end{description}

\vspace{1cm}

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_com} --- Communication routine
\item{Synopsis}\\
   {\tt
      void User\_com(int *status)
   }
\item{Arguments} \\
 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt status} & O & Reserved for the future.\par
                      Should be {\tt ASCA\_ANL\_OK} when it returns.
 \end{tabular}
\item{Required} \\
   None.
\item{Comments} \\
   This subroutine is called in response to the command
   {\tt MODIFY\_PARAM} (see also \S \ref{sec:walk-through}).
   Parameters of analysis ({\em e.g.} sensor ID)
   should be asked to an analyzer in this subroutine.
\end{description}

\vspace{1cm}

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_his} --- Histogram booking routine
\item{Synopsis}\\
   {\tt
      void User\_his(int *status)
   }
\item{Arguments} \\
 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt status} & O & Reserved for the future.\par
                      Should be {\tt ASCA\_ANL\_OK} when it returns.
 \end{tabular}
\item{Required} \\
   None.
\item{Comments} \\
   This subroutine is called in response to the command
  {\tt ANALYZE\_DATA} if specified by the command {\tt BOOK\_HISTOGRAM}
  (see also \S \ref{sec:walk-through}).
   All histograms should be booked in this subroutine.
\end{description}

\vspace{1cm}

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_bgnrun} --- Beginning-of-Run routine.
\item{Synopsis}\\
   {\tt
      void User\_bgnrun(int *status)
   }
\item{Arguments} \\
 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt status} & O & Controls the flow of data.\par
        Set {\tt ASCA\_ANL\_OK},\par
        \hfill\parbox{0.65\textwidth}{
            if the beginning of the run goes good.
        }\par
        Set {\tt ASCA\_ANL\_QUIT},\par
        \hfill\parbox{0.65\textwidth}{
            if you want to discard the current data set (or the current file
            in many case) after this subroutine.
            After the discard
            the ASCA\_ANL system terminates to process the current data set
            without calling analysis entries ({\tt *\_bgnrun}) of modules 
            downstream in reference to this module.
        }\par
 \end{tabular}
\item{Required} \\
   At the beginning of this subroutine you have to set one of the EVS flag
   whose keyword is {\tt "User:BEGIN"}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
EVSSET("User:BEGIN")
\end{verbatim}\end{quote}
\item{Comments} \\
   This subroutine is called once
   just after each data set ({\em e.g.} data file) is opened.
   That means
   this subroutine is called $N$ times
   in case of analyzing $N$ sets of data,
   if no module returns {\tt ASCA\_ANL\_QUIT}
   as a status of the subroutine {\tt *\_bgnrun}.
   In this subroutine
   initialization for each data set should be placed.
\end{description}

\vspace{1cm}

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_ana} --- Analysis routine.
\item{Synopsis}\\
   {\tt
      void User\_ana(int nevent,int eventid,int *status) \\
   }
\item{Arguments} \\

 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt nevent} & I & Sequential number of events.\\
   {\tt eventid} & I & Event ID.\par
        {\tt evnentid = ASCA\_ANL\_OBS}\par
        \hfill\parbox{0.65\textwidth}{
             when the current photon is the observed one.
        }\par
        {\tt evnentid = ASCA\_ANL\_PSEUDO}\par
        \hfill\parbox{0.65\textwidth}{
             when the current photon is the pseudo event.
        }\par\\
   {\tt status} & O & Controls the flow of data.\par
        \medskip
        \underline{\bf Classic control values} (NOT additive) \par
        Set {\tt ASCA\_ANL\_OK},\par
        \hfill\parbox{0.65\textwidth}{
            if the analysis goes good.
        }\par
        Set {\tt ASCA\_ANL\_QUIT},\par
        \hfill\parbox{0.65\textwidth}{
            if you want to discard the current data set (or the current file
            in many case) after this subroutine.
            After the discard
            the ASCA\_ANL system terminates to process the current data set
            without calling analysis entries ({\tt *\_ana}) of modules 
            downstream in reference to this module.
            Note that NONE of EVS flags are accumulated for the current photon
            when this value is set.
        }\par
        Set {\tt ASCA\_ANL\_SKIP},\par
        \hfill\parbox{0.65\textwidth}{
            if you want to discard the current photon after this subroutine.
            After the discard
            the ASCA\_ANL system starts to process the next photon data,
            skipping analysis entries ({\tt *\_ana}) of modules
            downstream in reference to this module.
        }\par
        \bigskip
        \underline{\bf Additive control values} \par
        Add {\tt ANL\_DISCARD},\par
        \hfill\parbox{0.65\textwidth}{
            if you want to discard the current photon after this subroutine.
            After the discard
            the ASCA\_ANL system starts to process the next photon data,
            skipping analysis entries ({\tt *\_ana}) of modules
            downstream in reference to this module.
        }\par
        Add {\tt ANL\_ENDLOOP},\par
        \hfill\parbox{0.65\textwidth}{
            if you want to discard the current data set (or the current file
            in many case) after this subroutine.
            After the discard
            the ASCA\_ANL system terminates to process the current data set
            without calling analysis entries ({\tt *\_ana}) of modules 
            downstream in reference to this module.
        }\par
        Add {\tt ANL\_NOCOUNT},\par
        \hfill\parbox{0.65\textwidth}{
            if you DON'T want to accumulate the current EVS flags
            after this subroutine.
            This flag DOES NOT affect the procedure to call modules
            downstream in reference to this module.
            Note that NONE of EVS flags are accumulated for the current photon
            when this flag is issued.
        }\par\\
 \end{tabular}\newpage
\item{Required} \\
   At the beginning of this subroutine you have to set one of the EVS flag
   whose keyword is {\tt "User:ENTRY"}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
EVSSET("User:ENTRY")
\end{verbatim}\end{quote}
   If the data is successfully analyzed and all is good at the end of this 
   subroutine,
   you must set one of the EVS flag whose keyword is {\tt "User:OK"}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
EVSSET("User:OK")
\end{verbatim}\end{quote}
\item{Comments} \\
   This subroutine is called for each photon in data set.
   That means
   this subroutine is called $N$ times
   in case of analyzing $N$ photons.
   All you have to write in this subroutine
   is an analysis for one photon,
   {\em e.g.},
   to add one photon to an appropriate bin in energy histogram.
   Iterative call of this subroutine realizes the photon-by-photon analysis.
\end{description}

\vspace{1cm}

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_endrun} --- End-of-Run routine.
\item{Synopsis}\\
   {\tt
      void User\_endrun(int *status)
   }
\item{Arguments} \\
 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt status} & O & Reserved for the future.\par
                      Should be {\tt ASCA\_ANL\_OK} when it returns.
 \end{tabular}
\item{Required} \\
   None.
\item{Comments} \\
   This subroutine is called once
   just after an analysis of each data set,
   if the subroutine {\tt *\_bgnrun} of the same module was called
   before the analysis of the same data set.
   That means
   this subroutine is called $N$ times
   in case of analyzing $N$ sets of data,
   if no module returns {\tt ASCA\_ANL\_QUIT}
   as a status of the subroutine {\tt *\_bgnrun}.
\end{description}

\vspace{1cm}

\newpage
\begin{description}
\item{Subroutine}\\
   {\tt User\_exit} --- Exit routine.
\item{Synopsis}\\
   {\tt
      void User\_exit(int *status)
   }
\item{Arguments} \\
 \begin{tabular}{l@{\ (}c@{)\ }p{0.7\textwidth}}
   {\tt status} & O & Reserved for the future.\par
                      Should be {\tt ASCA\_ANL\_OK} when it returns.
 \end{tabular}
\item{Required} \\
   None.
\item{Comments} \\
   This subroutine is called once
   just before exiting the ASCA\_ANL.
   You do not have to save histograms you created in your analysis
   because the histograms are saved in response to the command
   {\tt SAVE\_HISTOGRAM} (see also \S \ref{sec:walk-through})
   or in response to answering {\tt y} when you are asked by ASCA\_ANL,
   {\tt Save histogram (Y/N): Y ?}, before your exit.
\end{description}








