\chapter{Reference for Expert}

\section{Module and Command}
A module is a unit of an analysis program with the ASCA\_ANL.
A user can create various analysis programs by combining modules.
A module consists of seven subroutines.
Each subroutine takes charge of a part of tasks of the module
and a role of each subroutine is defined by the ASCA\_ANL system.
These subroutines are called by the ASCA\_ANL system
when corresponding commands are issued.

Table\ref{tab:routines_in_module} summarizes
names of the subroutines,
related commands,
and roles which the subroutines should play.
In Table\ref{tab:command-1} and \ref{tab:command-2}
we summarize commands of the ASCA\_ANL program
with a related subroutine in a module.
In Table\ref{tab:routines_in_module},
\ref{tab:command-1}, and \ref{tab:command-2}
we assume a module's name is `{\tt USER} for clarity.

\begin{table}[hbt]
\begin{center}
\begin{tabular}{|l|l|l|p{0.4\textwidth}|}
\hline
Name & Related Command & Role & Called When \\
\hline
%
{\tt USER\_init} & {\tt ANALYZE\_DATA} & Initialization
& Jumping into the second stage of analysis,
  {\em i.e.},
  after entering the command {\tt ANALYZE\_DATA}
  and before new command menu (includes {\tt READ\_DATA}, etc.) showing up. \\
%
{\tt USER\_com} & {\tt MODIFY\_PARAM} & User Interface
& a module {\tt USER} is selected in {\tt MODIFY\_PARAM} command. \\
%
{\tt USER\_his} & {\tt BOOK\_HISTOGRAM} & Histogram Booking
& a module {\tt USER} is selected in {\tt BOOK\_HISTOGRAM} command. \\
%
{\tt USER\_bgnrun} & {\tt READ\_DATA} & Data Set Opening
& a data set is open. \\
%
{\tt USER\_ana} & {\tt READ\_DATA} & Event Analysis
& an event are read from a data set. \\
%
{\tt USER\_endrun} & {\tt READ\_DATA} & Data Set Closing
& a data set is closed. \\
%
{\tt USER\_exit} & {\tt EXIT} & Termination
& {\tt EXIT} command is invoked. \\
\hline
\end{tabular}
\caption{Subroutines composing a module}
\label{tab:routines_in_module}
\end{center}
\end{table}

\begin{table}[hbt]
\begin{center}
\begin{tabular}{|l|l|p{0.5\textwidth}|}
\hline
Command & Related subroutine & Function \\
\hline
{\tt DEFINE\_ANALYSIS} & None & Define an analysis chain \\
{\tt SHOW\_ANALYSIS}   & None & Show a currently defined analysis chain \\
{\tt MODIFY\_PARAM}    & {\tt USER\_com}
                       & Call user interface subroutines of modules\\
{\tt BOOK\_HISTOGRAM}  & {\tt USER\_his}
                       & Register modules for which histograms will be booked\\
{\tt ANALYZE\_DATA}    & {\tt USER\_his}, {\tt USER\_init}
                       & Book histograms for specified modules
			 and jump to the second stage of the analysis \\
{\tt QUIT}             & None & Quit from the program without analyzing data \\
\hline
\end{tabular}
\caption{Commands in the first stage (defining an analysis chain)
on an analysis program}
\label{tab:command-1}
\end{center}
\end{table}

\begin{table}[hbt]
\begin{center}
\begin{tabular}{|l|p{0.3\textwidth}|p{0.5\textwidth}|}
\hline
Command & Related subroutine & Function \\
\hline
{\tt READ\_DATA}    & {\tt USER\_bgnrun}, {\tt USER\_ana},
                      and {\tt USER\_endrun}
                    & Open data set and start analysis \\
{\tt SAVE\_HIST}    & None & Save resultant histograms into an HBOOK file \\
{\tt CLEAR\_HIST}   & None & Clear histograms \\
{\tt SHOW\_STATUS}  & None & Print summary of EVS flags \\
{\tt RESET\_STATUS} & None & Clear summary of EVS flags \\
{\tt EXIT}          & {\tt USER\_exit} & Exit from the program \\
\hline
\end{tabular}
\caption{Commands in the second stage (driving an analysis chain)
on an analysis program}
\label{tab:command-2}
\end{center}
\end{table}

The relationship between the ASCA\_ANL command and subroutines in a module
are illustrated in Figure \ref{fig:call_module}
In Figure\ref{fig:call_module}
each subroutine is indicated in a doubled oval.
For example,
{\tt USER\_init} should be in a doubled oval named ``{\tt \_init}'' entries,
and so on.
In addition,
in each oval there are subroutines of one kind for some of the linked modules.
In case of {\tt gisspec\_f},
subroutines {\tt FITSREAD\_init}, {\tt CIRCREG\_init}, and {\tt GISSPEC\_init}
is in ``{\tt \_init}'' entries in this order\footnote{
Exactly speaking,
this order is defined by a command {\tt DEFINE\_ANALYSIS}.
See \S \ref{sec:walk-through} as reference.
}.

\begin{figure}[p]
\begin{center}
\epsfile{file=call_module-v1.00-flip.eps,height=\textheight}
\caption{Schematic drawing of relationship
between the ASCA\_ANL command and subroutines in a module}
\label{fig:call_module}
\end{center}
\end{figure}

See Chapter\ref{chap:details-on-F} or Chapter\ref{chap:details-on-C}
for details.

\section{Analysis Chain}
An analysis sequence with the ASCA\_ANL is called an ``analysis chain''.
The analysis chain consists of several modules,
a root module to read data (See \S \ref{sec:root-module}),
some filter modules to filter events,
and an (or a few) analysis module(s) to accumulate events to histograms.
In this flow
you may need to control an analysis flow to eliminate ``bad'' events.

To control an analysis flow,
each module can receive/give information from/to the ASCA\_ANL system
through arguments of a {\tt USER\_ana} entry.
In this section
we summarize how to contact with the ASCA\_ANL system with the arguments.

\subsection{Flow Control}\label{sec:flow-control}
{\tt USER\_ana} entry has three arguments.
The first argument is {\tt nevent},
the second is {\tt eventid},
and the third is {\tt status}.

\subsubsection{\tt nevent}
{\tt nevent} is the number of events
which a root module (See \S \ref{sec:root-module}) reads successfully,
or the number of iterations of an event loop.
Therefore
{\tt nevent} starts from 1 and an analysis is terminated
when {\tt nevent} reaches the number of events
specified at the beginning of event loop (See \S \ref{sec:walk-through}).
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Number of events (-1=all, 0=exit): -1 ? 100
\end{verbatim}\end{quote}
In this case
{\tt nevent} takes a value from 1 to 100 successively.

This is an input argument.
Do not change this value in a module.

\subsubsection{\tt eventid}
{\tt eventid} shows a characteristic of a current event.
There are two types of event at present,
{\em i.e.},
an observation event and a pseudo event (See \S \ref{sec:pseudo-event}).
If a current event is an observation event,
\begin{quote}
  {\tt eventid} $=$ {\tt EVENTID\_OBS},
\end{quote}
and if a current event is a pseudo event,
\begin{quote}
  {\tt eventid} $=$ {\tt EVENTID\_PSEUDO}.
\end{quote}

This is an input argument.
Do not change this value in a module.

\subsubsection{\tt status}
{\tt status} is a flag to control an analysis flow.
The ASCA\_ANL system evaluates {\tt status}
right after returning from a call of a module
and determine the stream of an analysis flow
so that you can control an analysis flow by setting a value to {\tt status}.

A flow control can be specified from three points of view,
whether a current event should be passed to downstream modules,
whether the system should continue to read events from a current data set,
and whether current status of EVS flags should be accumulated\footnote{
EVS flags accumulated in an analysis is shown at the end of an analysis
(printed just after {\tt EXIT} command is invoked)
or when {\tt SHOW\_STATUS} command is invoked.} (event counting).
In Table \ref{tab:status}
control values (values to be set to {\tt status})
and their meanings are listed.

\begin{table}[htb]
\begin{tabular}{|l|c|c|c|c|}
\hline
 & & \multicolumn{3}{|c|}{Flow control} \\
Value & Additivity & Discard event & Discard data set & 
Disable to accumulate \\
 \hline
ASCA\_ANL\_OK   & No  & $\times$   & $\times$   & $\times$   \\
ASCA\_ANL\_SKIP & No  & $\bigcirc$ & $\times$   & $\times$   \\
ASCA\_ANL\_QUIT & No  & $\bigcirc$ & $\bigcirc$ & $\bigcirc$ \\
ANL\_DISCARD    & Yes & $\bigcirc$ & $\times$   & $\times$   \\
ANL\_ENDLOOP    & Yes & $\times$   & $\bigcirc$ & $\times$   \\
ANL\_NOCOUNT    & Yes & $\times$   & $\times$   & $\bigcirc$ \\ \hline
\end{tabular}
\caption{List of control values}
\label{tab:status}
\end{table}

There are two types of control values,
additive values and non-additive (or classic) ones.

Additive values can be added to synthesize a desired flow control.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
         status = ANL_DISCARD + ANL_ENDLOOP
\end{verbatim}\end{quote}
In this example
a current event is discarded
({\em i.e.}, not be passed to downstream modules),
a current data set is also discarded
({\em i.e.} remaining events in the data set is ignored),
but current EVS flags are accumulated.

On the other hand,
classic values can NOT be added.
You only can set one value to {\tt status}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
         status = ASCA_ANL_QUIT
\end{verbatim}\end{quote}

{\tt status} is an output argument.
Set a value before returning from a module
and do not care about a value when a module is called.

\subsection{Pseudo Event}\label{sec:pseudo-event}
An analysis program with the ASCA\_ANL sometimes includes filter modules
which filter events read from a data set.
In such a case
it can be difficult to measure an exposure time
because the total exposure may be affected by all of the filters.
If you have a ``clock pulse'' in the analysis system,
however,
you can easily measure the exposure time after fintering
by counting the clock pulse after the filters.

A pseudo event is an artificial event
which was introduced to calculate exposure time in a simple way.
It is generated by a root module (See \S \ref{sec:root-module})
at the top of an analysis chain
and is filtered out by filtering modules (if so designed).
To distinguish pseudo events from a normal events,
several indicators work in a special way.
Table\ref{tab:pseudo-flag} summarizes the special indications
for pseudo events.

\begin{table}[htb]
\begin{center}
\begin{tabular}{|l|l|l|l|}
\hline
Indicator & Attribution & Value for Pseudo Event & Value for Normal Event \\
\hline
event ID & Argument of {\tt USER\_ana}
          & {\tt EVENTID\_PSEUDO}
          & {\tt EVENTID\_OBS} \\
{\tt ANL:SENSOR} & BNK keyword
          & {\tt SENSOR\_PSEUDO}
          & sensor ID \\
{\tt SIS:PSEUDO Event} & EVS flag
          & ``true'' for SIS exposure
          & ``false'' \\
{\tt GIS:PSEUDO Event} & EVS flag
          & ``true'' for GIS exposure
          & ``false'' \\
{\tt SIS:SIS0 Pseudo}   & EVS flag
          & ``true'' for SIS0 exposure
          & ``false'' \\
{\tt SIS:SIS1 Pseudo}   & EVS flag
          & ``true'' for SIS1 exposure
          & ``false'' \\
{\tt GIS:GIS2 Pseudo}  & EVS flag
          & ``true'' for GIS2 exposure
          & ``false'' \\
{\tt GIS:GIS3 Pseudo}  & EVS flag
          & ``true'' for GIS3 exposure
          & ``false'' \\
\hline
\end{tabular}
\caption{Indicators of pseudo events}
\label{tab:pseudo-flag}
\end{center}
\end{table}

\section{Data I/O}
In order to get information on each event,
BNK and EVS are available in a module.
BNK provides a simple data bank system,
which enables us to get and put the event data
({\em e.g.}, {\tt ASCATIME}, {\tt PI}, etc.).
EVS manages flags related to each event and sums them up.
Both BNK and EVS uses their keywords as pointers to the data and the flag.
On the other hand,
results of an analysis are stored in histograms
by HBOOK subroutines ({\em e.g.}, {\tt HF1} and {\tt HF2})\cite{HBOOK4}.
.
HBOOK provides us many useful subroutines which handles histograms.

\subsection{BNK/EVS Keywords}\label{sec:BNK-EVS-key}
The ASCA\_ANL system defines a group of BNK keywords
which are available for any module.
Most of them are related to photon information,
such as {\tt ASCATIME} and {\tt PI}.
Also,
some EVS keywords are reserved for common usage.
Such keywords include information on a bit rate or a data mode.
In Table\ref{tab:BNK-key} and Table\ref{tab:EVS-list}
we summarize BNK and EVS keywords reserved by the system, respectively.

\begin{table}[p]
\begin{center}
\epsfile{file=bnkkey-v1.00.eps,height=\textheight}
\caption{BNK keywords}
\label{tab:BNK-key}
\end{center}
\end{table}

\begin{table}[htb]
\begin{center}
\begin{tabular}{|l||c|c|c|} \hline
EVS keyword       & FITSREAD   & SISREAD    & GISREAD    \\ \hline \hline
{\tt ANL:BIT HIGH}      & $\bigcirc$ & $\bigcirc$ & $\bigcirc$ \\ \hline
{\tt ANL:BIT MEDIUM}    & $\bigcirc$ & $\bigcirc$ & $\bigcirc$ \\ \hline
{\tt ANL:BIT LOW}       & $\bigcirc$ & $\bigcirc$ & $\bigcirc$ \\ \hline
{\tt SIS:FAINT mode}    & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt SIS:BRIGHT mode}   & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt SIS:FAST mode}     & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt SIS:BRIGHT2 mode}  & $\bigcirc$ &            &            \\ \hline
{\tt GIS:PH mode}       & $\bigcirc$ &            & $\bigcirc$ \\ \hline
{\tt GIS:MPC mode}      & $\bigcirc$ &            & $\bigcirc$ \\ \hline
{\tt SIS:SIS0 Event}    & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt SIS:SIS1 Event}    & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt GIS:GIS2 Event}    & $\bigcirc$ &            & $\bigcirc$ \\ \hline
{\tt GIS:GIS3 Event}    & $\bigcirc$ &            & $\bigcirc$ \\ \hline
{\tt SIS:PSEUDO Event}  & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt GIS:PSEUDO Event}  & $\bigcirc$ &            & $\bigcirc$ \\ \hline
{\tt SIS:SIS0 Pseudo}   & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt SIS:SIS1 Pseudo}   & $\bigcirc$ & $\bigcirc$ &            \\ \hline
{\tt SIS:GIS2 Pseudo}   & $\bigcirc$ &            & $\bigcirc$ \\ \hline
{\tt SIS:GIS3 Pseudo}   & $\bigcirc$ &            & $\bigcirc$ \\ \hline
\end{tabular}
\caption{EVS flags}
\label{tab:EVS-list}
\end{center}
\end{table}

\subsection*{Note for user-defined BNK/EVS keyword}
A user module can define a new BNK/EVS keyword in {\tt USER\_init}.
The name of the keyword have to have an module's name like {\tt USER:something}
to avoid a possible overlapping of a keyword name.
This restriction also affects how to refer such a data
which other modules define and BNKput.
Once you write a module {\tt USER2} including BNKget like:
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Call BNKget('USER:something', sizeof(something), size, something),
\end{verbatim}\end{quote}
the module {\tt USER2} ALWAYS have to be linked with the module
{\tt USER} and causes a fatal error in running when {\tt USER} is not linked.

In order to go through this problem,
a few choices are possible.
\begin{enumerate}
\item Change the module {\tt USER2} not to refer {\tt USER:something}.\\
      This is the simplest solution but is not always possible.
\item Check existence of the module {\tt USER}
      before BNKget in the module {\tt USER2}.\\
      To check the existence,
      we can use {\tt ANL\_get\_chain\_info},
      or one of utility routines supplied with the ASCA\_ANL system.
      See Chapter \ref{chap:utility-routines} for details.
\end{enumerate}

In general
it is not recommended to design a module
which is largely depending on an other module's existence.
Such a tight relationship between modules
may reduce convenience of ``modularization''
and value of your module as a software resource.
In some case
it indicates a possibility that you can merge their functions into one module.
In any case
please check necessity and validity of dividing a function into two modules
before you design such a module.

\subsection{BNKF/EVSF --- Faster BNK/EVS ---}
When data in BNK or EVS is accessed
({\em e.g.}, when {\tt BNKget} or {\tt EVSset} is called),
BNK and EVS searches a specified keyword in an internal keywords table,
find a place in which specified data is stored,
and return the stored value.
Because of these searching keywords
data I/O with BNK or EVS can be a problem by reducing a speed on its execution.

To avoid this,
following four subroutines are implemented.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Subroutine BNKFput(key, index, n, iarray)
      Character*(*) key         ! input
      Integer index             ! input/output
      Integer n                 ! input
      Integer iarray            ! output

      Subroutine BNKFget(key, index, size, used, iarray)
      Character*(*) key         ! input
      Integer index             ! input/output
      Integer size              ! input
      Integer used              ! output
      Integer iarray            ! output

      Logical Function EVSF(key,index)
      Character*(*) key         ! input
      Integer index             ! input/output

      Subroutine EVSset(key,index)
      Character*(*) key         ! input
      Integer index             ! input/output
\end{verbatim}\end{quote}

These subroutines search a place of specified data
when it is called with {\tt index = 0}
and return the place as {\tt index}.
When you call these with the returned {\tt index},
these return a value in the place specified by {\tt index}
without searching the keyword to find the stored data.
In this way
we can reduce an overhead of the call of these subroutines.

Typical usage of these subroutines will be followings.
In FORTRAN,
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Integer sensor, size
      Integer index1/0/, index2/0/, index3/0/, index4/0/
      Save index1, index2, index3, index4

      Call BNKFput('ANL:SENSOR', index1, sizeof(sensor), sensor)
      Call BNKFget('ANL:SENSOR', index2, sizeof(sensor),
     &             size, sensor)
      Call EVSFset('USER:ENTRY', index3)
      If ( EVSF('ANL:GIS2 Pseudo', index4) )
     &   Write(*,*) 'GIS2 Pseudo'
\end{verbatim}\end{quote}
%
and in C,
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <cfortran.h>
#include <bnk.h>
#include <evs.h>

        int sensor, size;
        static int index1=0, index2=0, index3=0, index4=0;
        
        BNKFPUT("ANL:SENSOR", index1, sizeof(sensor), &sensor);
        BNKFGET("ANL:SENSOR", index2, sizeof(sensor), size, &sensor);
        EVSFSET("USER:ENTRY", index3);
        if ( EVSF("ANL:GIS2 Pseudo", index4) ) printf("GIS2 Pseudo");
\end{verbatim}\end{quote}

\subsection{Support Macros for BNKF/EVSF}
For C language people
there are another way of making use of faster BNK/EVS system.
The macro definition file {\tt bnkf.h} and {\tt evsf.h}
are in the ASCA\_ANL distribution kit.

include/bnkf.h:

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
#define BNKFGETM(key,size,used,value)   {\
        static int index = 0;\
        int vsize = size;\
        bnkfget_(key, &index, &vsize, &used, value, sizeof(key)-1);\
}

#define BNKFPUTM(key,size,value)        {\
        static int index = 0;\
        int vsize = size;\
        bnkfput_(key, &index, &vsize, value, sizeof(key)-1);\
}
\end{verbatim}\end{quote}

include/evsf.h:

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
#define EVSFM(key,index)        evsf_(key, &(index), sizeof(key)-1)
#define EVSFSETM(key)   {\
        static int index = 0;\
        evsfset_(key, &index, sizeof(key)-1);\
}
\end{verbatim}\end{quote}

Typical usage will be a following.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <cfortran.h>
#include <bnk.h>
#include <bnkf.h>       /* <--- additional! */
#include <evs.h>
#include <evsf.h>       /* <--- additional! */

        int sensor, size;
        static int index = 0;
        
        BNKFPUTM("ANL:SENSOR", sizeof(sensor), &sensor);
        BNKFGETM("ANL:SENSOR", sizeof(sensor), size, &sensor);
        EVSFSETM("USER:ENTRY");
        if ( EVSFM("ANL:GIS2 Pseudo", index) ) printf("GIS2 Pseudo");
\end{verbatim}\end{quote}

\subsubsection{CAUTION}
Because support macros in {\tt bnkf.h} and {\tt evsf.h} are NOT functions,
you have to pay a special attention in writing a module.
You have to write macros as many times as the number of data
you want to access.

If you write a following code to get four data,
``ANL:SENSOR'', ``ANL:DETX'', ``ANL:DETY'', and ``ANL:PI'',
it does NOT work.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
int i, value[4];
static char keyword[4][20] = {"ANL:SENSOR","ANL:DETX","ANL:DETY","ANL:PI"};
for (i=0;i<4;i++) {
        BNKFGETM(keyword[i], sizeof(value[i]), size, &value[i]);
}
\end{verbatim}\end{quote}
In above case a macro {\tt BNKFGETM} is expanded as one line
so that only one internal index is reserved.
If you need to get four data with {\tt BNKFGETM},
you have to write {\tt BNKGETM} four times like this.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
int value[4];
BNKFGETM("ANL:SENSOR", sizeof(value[0]), size, &value[0]);
BNKFGETM("ANL:DETX", sizeof(value[1]), size, &value[1]);
BNKFGETM("ANL:DETY", sizeof(value[2]), size, &value[2]);
BNKFGETM("ANL:PI", sizeof(value[3]), size, &value[3]);
\end{verbatim}\end{quote}

\subsection{Buffer Size of BNK and HBOOK}
Both BNK and HBOOK allocate a certain size of memory to store the data.
Hereafter we call the memory area ``BNK buffer'' and ``HBOOK buffer'',
respectively.
Because the size of these buffers are defined
so large that most analysis can go well.
In some applications, however,
you may need lager size of memory to be allocated for BNK data or histograms.

The size of buffer can be specified in {\tt mkanlinit}.
When you reply a following question with ``*'',
{\tt mkanlinit} recognizes it as a beginning of a parameter name to be set.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}

Therefore type as followings
if you want to set the size of HBOOK buffer to 2000000.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ? *HBOOK_BUF_SIZE 2000000
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}
Note that the unit of the size is four bytes
so that ``2000000'' means 8000000 bytes.

Again abbreviations are valid here\footnote{
But we do NOT recommend abbreviate too much.
}.
Also,
any space and carriage return after the ``*'' are ignored.
Thus,
Following replies make no difference.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ? *HBOOK 2000000
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ? *HBOOK_BU 2000000
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ? * HBOOK_BUF_SIZE 2000000
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ? *
Command: HBOOK_BUF_SIZE ? HBOOK_BUF_SIZE
HBOOK_BUF_SIZE: 2200000 ? 2000000
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}

In Table\ref{tab:BNK-HBOOK-buffer}
we summarize parameters which you can set in {\tt mkanlinit}.

\begin{table}[htb]
\begin{center}
\begin{tabular}{|l|c|l|}
\hline
Parameter & Unit & Remark \\
\hline
{\tt HBOOK\_BUF\_SIZE} & 4 bytes & size of HBOOK buffer \\
{\tt BNK\_BUF\_SIZE}   & 4 bytes & size of BNK buffer \\
\hline
\end{tabular}
\end{center}
\caption{Parameters to be set in {\tt mkanlinit}}
\label{tab:BNK-HBOOK-buffer}
\end{table}

Although the sizes of both BNK and HBOOK buffer
can be expanded with this feature of {\tt mkanlinit},
you must be careful to determin the size to be set.
Even if you allocate a large size of memory for histograms (HBOOK buffer),
it is no use if {\em Display45} can not read in your resultant histograms.
So there seems to make no sense
to expand the size more than that allocated in {\em Display45}\footnote{
Ask an installer of {\em Display45} for the size.
}.
For the BNK buffer,
getting large size of memory of the data area may cause
a large overhead of copying the data when the data is accessed
(with {\tt BNKget}, etc.).
Perhaps you can find another solution to realize your design
without expanding the BNK buffer to an unrealistic size.

\section{Root Module}\label{sec:root-module}
A root module\footnote{
\tt FITSREAD, SISREAD, and GISREAD are supplied with the ASCA\_ANL.
} is specially designed
to read events from a data set and send them to downstream modules.
Therefore it is required
that a root module have to exist in an analysis chain,
that only one root module are allowed in a chain,
and that it should be at the top of a chain.

Because of its special role in a chain
there are several additional rules in writing it.
Let us assume you are writing a root module named {\tt ROOT}.
Followings are required rules,
{\em i.e.},
ANY root module have to satisfy following rules.

\begin{enumerate}
\item Call {\tt ANL\_initroot} in {\tt ROOT\_init}. \\
  {\tt ANL\_initroot} defines common BNK/EVS keywords.
  To call this in FORTRAN, just say,
  \begin{quote}\baselineskip 3.2mm\begin{verbatim}
   ...
         Subroutine ROOT_init (status)
         Implicit None
   ...
         Integer st
   ...
   c Common BNK/EVS
         Call ANL_initroot(st)
   ...
  \end{verbatim}\end{quote}
  and in C,
  \begin{quote}\baselineskip 3.2mm\begin{verbatim}
  ...
  #include <anl_initroot.h>
  ...
  void
  root_init(int *status)
  {
     int st;
     ...
  /* Common BNK/EVS */
     ANL_INITROOT(st);
     ...
   }
  \end{verbatim}\end{quote}
  the return status {\tt st} of {\tt ANL\_initroot} is reserved for the future
  and means nothing at present.

\item Set ``event ID''. \\
  An event ID is the second argument of {\tt ROOT\_ana} entry.
  The values to be set are:
  \begin{quote}
  event ID $=$ {\tt EVENTID\_PSEUDO} in case of a pseudo event \\
  event ID $=$ {\tt EVENTID\_OBS} in case of an observation data
  \end{quote}
  If you write a root module in C,
  special procedures are required to set an event ID.
  \begin{enumerate}
    \item Change an definition of function {\tt ROOT\_ana}. \\
          The second argument must change to a pointer to an integer.
         \begin{quote}\baselineskip 3.2mm\begin{tt}
          void \\
          root\_ana(int nevent, \underline{int *eventid}, int *status)
         \end{tt}\end{quote}
    \item Change a C wrapper for {\tt ROOT\_ana} entry. \\
          The fifth argument\footnote{Or the second from the right}
          of the C wrapper must change from {\tt INT} to {\tt PINT}.
         \begin{quote}\baselineskip 3.2mm\begin{tt}
         FCALLSCSUB3(root\_ana,ROOT\_ANA,root\_ana,INT,\underline{PINT},PINT)
         \end{tt}\end{quote}
    \item Change an declaration of function {\tt ROOT\_ana} (if any). \\
         \begin{quote}\baselineskip 3.2mm\begin{tt}
          void root\_ana(int, \underline{int *}, int *);
         \end{tt}\end{quote}
  \end{enumerate}
\end{enumerate}

In addition,
there are recommended feature of a root module.

\begin{enumerate}
\item BNKput Euler angles. \\
  For attitude correction
  we need to know an attitude as Euler angles.
  To unify how to access an attitude information,
  {\em i.e.}, how to get Euler angles at the moment,
  a root module are recommended to BNKput Euler angles for downstream modules.
  BNK keyword's name is ``{\tt ANL:EULER}'' (See \S \ref{sec:BNK-EVS-key}).
\item Generate pseudo events. \\
  Pseudo events are very useful to measure an exposure time of an observation.
  Many users make use of pseudo events to do that,
  a root module is strongly recommended to generate pseudo events.
  Also, a root module have to BNKput an interval of pseudo events in second
  with a BNK keyword ``{\tt ANL:PSEUDO\_INTERVAL}''
  (See \S \ref{sec:BNK-EVS-key}).
\item BNKput a current file name. \\
  In most applications the data set is provided as a event file.
  A root module is recommended to BNKput its name for downstream modules.
  BNK keyword is ``{\tt ANL:FILENAME}'' (See \S \ref{sec:BNK-EVS-key}).
\end{enumerate}

For downstream modules,
of course,
a root module have to as many information of events in a data set as possible.
For example,
a root module have to BNKput various information on a current event,
{\em e.g.},
{\tt ASCATIME} to ``{\tt ANL:TIME}'',
{\tt DETX} to ``{\tt ANL:DETX}'',
and {\tt PI} to ``{\tt ANL:PI}''.
Also,
it must to EVSset various flags,
{\em e.g.},
``{\tt SIS:SIS0 Event}'' for an observation event of SIS0,
``{\tt SIS:FAINT}'' for an SIS faint mode event,
and ``{\tt ANL:BIT HIGH}'' in case of an event taken during high bit rate
(See \S \ref{sec:BNK-EVS-key}).
That means design of a root module is very important for the ASCA\_ANL system.
Please note that
a root module may determine quality of an analysis in some cases.
%when you design a root module.
In the end
we recommend to consult a member of ASCA\_ANL Working Group
before designing a root module.
