\chapter{Built-in Modules}
The ASCA\_ANL has a few built-in modules to do common tasks\footnote{
For example,
a task of reading data from FITS file is commonly required in a data analysis.
}
in a data analysis.
The modules are designed\footnote{
Clearly,
as a result,
the modules reduce your labor to create a new analysis program.
}
to avoid ``a flood of software tools''\footnote{
This means different people make different tools with different algorithm,
which leads to the different result for the same analysis.
}
by unifying a tool for each task.
Therefore,
you are strongly recommended to use the built-in modules
when you needs the same function as that of one of built-in module.

All the built-in modules here are 
listed in Table \ref{tab:built-in}
and supplied as a library {\tt libANL\_MODULE.a}.
The libraries are automatically created by installing the ASCA\_ANL
%and stored in the directory {\tt lib/}
(see \S \ref{sec:install}).
%The library name is {\tt lib{\em module-name}.a},
%{\em i.e.},
%the library for {\tt FITSREAD} has its name of {\tt libFITSREAD.a}. 

In this section
we briefly introduce functions of the built-in modules.

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|c|}
\hline
Name & Function & Reference \\ \hline
{\tt FITSREAD}
	& Read FITS file and extract the data for each photon
	& \S\ref{sec:FITSREAD} \\
{\tt SISREAD}
	& Read FRF and extract the SIS raw data for each photon
	& \S\ref{sec:SISREAD} \\
{\tt SISTUNE}
	& Apply various calibration constants to the raw SIS data
	& \S\ref{sec:SISREAD} \\
{\tt GISREAD}
	& Read FRF and extract the GIS raw data for each photon
	& \S\ref{sec:GISREAD} \\
{\tt GISTUNE}
	& Apply various calibration constants to the raw GIS data
	& \S\ref{sec:GISREAD} \\ \hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Functions of built-in modules in a library {\tt libANL\_MODULE.a}}
\label{tab:built-in}
\end{table}

\section{FITSREAD}\label{app:BNK-key}\label{sec:FITSREAD}
{\tt FITSREAD} is one of the most up-stream modules.
It  reads FITS file and extracts the data
for each photon  by utilizing FITSIO routine.
For the modules in the lower stream of the analysis sequence,
{\tt FITSREAD} puts data in the BNK data buffer.
User module can access data
by calling {\tt BNKget} in their analysis routine.
The BNK keywords are same as ones defined in the FITS file,
except for the header  ``{\tt GIS:}'' for GIS and ``{\tt SIS:}'' for SIS.
BNK keywords and the size used in {\tt FITSREAD}
are summarized in Table~\ref{tab:BNK-key}.

\subsubsection{Pseudo Event}
{\tt FITSREAD} can generate pseudo events separated by a constant time interval.
The time interval can be specified arbitrarily.
You can distinguish between a observation event and a pseudo event
using {\tt eventid}, {\tt EVS}, or a BNK keyword ``{\tt ANL:SENSOR}''.
You can calculate an exposure time with pseudo events.

\subsubsection{Parameter Settings}
You may specify how {\tt FITSREAD} acts
by setting parameters with {\tt MODIFY\_PARAM} command.
In Table \ref{tab:FITSREAD:MODIFY_PARAM}
we summarize commands in {\tt MODIFY\_PARAM} of {\tt FITSREAD}.

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|c|}
\hline
Command & Function & Default \\ \hline
{\tt SHOW}
	& Display current settings
	& --- \\
{\tt PSEUDO\_INTERVAL}
	& Set time interval of pseudo events\footnote{
		No pseudo event is generated if set to 0.0.}
	& 0.0 \\
{\tt EULER}
	& Set whether to BNKput Euler angles
	& No \\
{\tt EXIT}
	& Exit from {\tt MODIFY\_PARAM}
	& --- \\ \hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Commands in {\tt MODIFY\_PARAM} of {\tt FITSREAD}}
\label{tab:FITSREAD:MODIFY_PARAM}
\end{table}

\section{SISREAD with SISTUNE}\label{sec:SISREAD}
{\tt SISREAD} is another most up-stream module
that delivers data to other modules.
It is based on the utility functions
implemented in {\tt tlmeventsFRF} written by K. Mitsuda (ISAS)
and allows a user to access FRF file directly.
Note that
{\tt SISREAD} only reads raw data
such as {\tt CCDID}, {\tt PHA}, {\tt RAWX}, etc.
In order to calculate calibrated data,
such as {\tt DETX}, {\tt X},
{\tt SISTUNE} should be assigned as a down stream module.
{\tt SISTUNE} reads raw data
and converts them into calibrated data based on calibration constants.
{\tt SISTUNE} also utilizes functions in {\tt tlmeventsFRF}.
Calibrated data are stored in BNK data buffer
and passed to the down stream modules.
The same keywords as {\tt FITSREAD}
are used for BNK in {\tt SISREAD/SISTUNE}.

\subsubsection{Pseudo Event}
{\tt SISREAD} can generate pseudo events at the beginning of each CCD frame.
The interval can't be specified arbitrarily.
Using these pseudo events,
you can not only recognize CCD frames easily
but also calculate an exposure time.

\subsubsection{Parameter Settings}
You may specify how {\tt SISREAD} and {\tt SISTUNE} acts
by setting parameters with {\tt MODIFY\_PARAM} command.
In Table \ref{tab:SISREAD:MODIFY_PARAM} and \ref{tab:SISTUNE:MODIFY_PARAM}
we summarize commands
in {\tt MODIFY\_PARAM} of {\tt SISREAD} and {\tt SISTUNE}, respectively.

\clearpage

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|c|}
\hline
Command & Function & Default \\ \hline
{\tt BitRate}
	& Select bit rate of the data
	& ANY \\
{\tt Pseudo-Event}
	& Set whether to generate pseudo events\footnote{
		You can not specify its time interval}
	& OFF \\
{\tt Euler-Angle}
	& Set whether to BNKput Euler angles
	& Yes \\
{\tt Return-to-Menu}
	& Return to ASCA\_ANL menu (Exit from {\tt MODIFY\_PARAM})
	& --- \\ \hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Commands in {\tt MODIFY\_PARAM} of {\tt SISREAD}}
\label{tab:SISREAD:MODIFY_PARAM}
\end{table}

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|c|}
\hline
Command & Function & Default \\ \hline
{\tt Teldef-File}
	& Sets a name of a teldef file
	& ``-'' \\
{\tt Reference-Position}
	& Sets a reference point to convert coordinates
	& (0.0, 0.0) \\
{\tt Return-to-Menu}
	& Return to ASCA\_ANL menu (Exit from {\tt MODIFY\_PARAM})
	& --- \\ \hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Commands in {\tt MODIFY\_PARAM} of {\tt SISTUNE}}
\label{tab:SISTUNE:MODIFY_PARAM}
\end{table}

\section{GISREAD with GISTUNE}\label{sec:GISREAD}
{\tt GISREAD} is yet another most up-stream module
that delivers data to other modules.
It is based on the utility functions
implemented in {\tt GIPHS} written by Y. Ishisaki
and allows a user to access FRF file directly.
Note that
{\tt GISREAD} only reads raw data
such as {\tt PHA}, {\tt RAWX}, {\tt RISE\_TIME}, etc.
In order to correct these raw data
{\tt GISTUNE} should be assigned as a down stream module.
{\tt GISTUNE} obtains data
and applies various calibration constants to the raw data.
{\tt GISTUNE} also utilizes functions in {\tt GIPHS}.
Corrected data is stored in BNK data buffer
and passed to the down stream modules.
The same keywords as {\tt FITSREAD}
are used for BNK in {\tt GISREAD/GISTUNE}.

\subsubsection{Pseudo Event}
{\tt GISREAD} can generate pseudo events separated by a constant time interval.
The interval can be specified arbitrarily.
You can distinguish between an observation event and a pseudo event
using {\tt eventid}, {\tt EVS}, or a BNK keyword ``{\tt ANL:SENSOR}''.
You can calculate an exposure time with pseudo events.

\subsubsection{Parameter Settings}
You may specify how {\tt GISREAD} and {\tt GISTUNE} acts
by setting parameters with {\tt MODIFY\_PARAM} command.
In Table \ref{tab:GISREAD:MODIFY_PARAM} and \ref{tab:GISTUNE:MODIFY_PARAM}
we summarize commands
in {\tt MODIFY\_PARAM} of {\tt GISREAD} and {\tt GISTUNE}, respectively.

\subsubsection{Special BNK Keywords}
{\tt GISREAD} and {\tt GISTUNE} define special BNK keywords
showed in Table \ref{tab:GISREAD:SpecialBNK} and
\ref{tab:GISTUNE:SpecialBNK}, respectively.

\subsubsection{Special EVS Keywords}
{\tt GISTUNE} defines special EVS keywords
showed in Table \ref{tab:GISTUNE:SpecialEVS}.

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Command & Function & Default \\ \hline
{\tt SHOW}
	& Display current settings
	& --- \\
{\tt GIS2}
	& Read GIS2 events
	& ON \\
{\tt GIS3}
	& Read GIS3 events
	& ON \\
{\tt GISMON}
	& Set whether GIS monitor counts should be counted by EVS
	& OFF \\
{\tt EULER}
	& Set whether Euler angle should be BNKput
	& ON \\
{\tt BITRATE}
	& Select bit rate of the data
	& HML \\
{\tt POINTING}
	& Select data in pointing mode\footnote{
		When ACS maneuver flag is OFF}
	& ON \\
{\tt OBS}
	& Select data in observation mode
	& ON \\
{\tt GISOK}
	& Select data only when GIS status is O.K.\footnote{
		When GIS ON, CPU running, RBM flag OFF, 
		and nominall value of HV and fine gain}
	& ON \\
{\tt GISNORM}
	& Select data only when GIS mode is normal\footnote{
		When PH mode, nominal bit assignment (10-8-8-5-0),
		nominal RT window, position method FLF, etc.}
	& ON \\
{\tt GISSPD}
	& Read data with GIS spread discr. flag ON/OFF/BOTH
	& BOTH \\
{\tt GISCNT}
	& Set min./max. value of GIS count rate (c/s/super-frame)
	& 0.0 -- 0.0 \\
{\tt RBMCNT}
	& Set min./max. value of RBM count rate (c/s/super-frame)
	& 0.0 -- 0.0 \\
{\tt RIGIDITY}
	& Set min./max. value of cut-off rigidity (GeV/c)
	& 0.0 -- 0.0 \\
{\tt SUNH}
	& Set min./max. value of Sun elevation (degree)
	& 0.0 -- 0.0 \\
{\tt ELEV}
	& Set min./max. value of target elevation (degree)
	& 0.0 -- 0.0 \\
{\tt DYE}
	& Set min./max. value of target elevation from day earth (degree)
	& 0.0 -- 0.0 \\
{\tt NTE}
	& Set min./max. value of target elevation from night earth (degree)
	& 0.0 -- 0.0 \\
{\tt PSEUDO\_INTERVAL}
	& Sets time interval of pseudo events\footnote{
		No pseudo event is generated if set to 0.0.}
	& 1.0 \\
{\tt EXIT}
	& Exit from {\tt MODIFY\_PARAM}
	& --- \\ \hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Commands in {\tt MODIFY\_PARAM} of {\tt GISREAD}}
\label{tab:GISREAD:MODIFY_PARAM}
\end{table}

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
BNK keyword name & Type & Comment \\ \hline
{\tt GISREAD:FILENAME}
	& Character*(*)
	& FRF file name reading now \\
{\tt GISREAD:PSEUDO\_INTERVAL}
	& Real*8
	& Pseudo event interval (sec). \\
& 	& If 0.0, no pseudo events are generated \\
{\tt GISREAD:ARRIVAL\_TIME}
	& Real*8
	& Equal to {\tt ANL:TIME} if timing bits are assigned, \\
&	& otherwise 0.0 \\
{\tt GISREAD:TELEMETRY\_TIME}
	& Real*8
	& Event time calculated from the word position of \\
&	& the event appeared in telemetry. \\
&	& If no timing bits are assigned, equal to {\tt ANL:TIME} \\
\hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Special BNK keywords of {\tt GISREAD}}
\label{tab:GISREAD:SpecialBNK}
\end{table}

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
Command & Function & Default \\ \hline
{\tt SHOW}
	& Display current settings
	& --- \\
{\tt ENABLE}
	& Enable various functions of {\tt GISTUNE}
	& --- \\
{\tt DISABLE}
	& Disable various functions of {\tt GISTUNE}
	& --- \\
{\tt DIRECTORY}
	& Set default directory name of calibration files
	& /asca/caldb \\
{\tt PHTUNE}
	& Set file names of gain maps
	& 'phfl\_s2\_v3.table' for S2 \\
	&
	& 'phfl\_s3\_v3.table' for S3 \\
{\tt HKTUNE}
	& Enable/disable correction of gain with temperature
	& ENA \\
{\tt LDHTUNE}
	& Enable/disable correction of gain with LDHIT count rate
	& DIS \\
{\tt RTTUNE}
	& Set file names of rise time maps
	& 's2xyrtflf.fits' for S2 \\
	& 
	& 's3xyrtflf.fits' for S3 \\
{\tt RTMASK}
	& Set file names of rise time masks
	& 'rtmask' for S2 \\
	&
	& 'rtmask' for S3 \\
{\tt XYLIN}
	& Set file names of maps for RAW-DET conversion
	& 'xflf\_s2.table' for S2 X-coord. \\
	& 
	& 'yflf\_s2.table' for S2 Y-coord. \\
	&
	& 'xflf\_s3.table' for S3 X-coord. \\
	&
	& 'yflf\_s3.table' for S3 Y-coord. \\
{\tt COORD}
	& Enable/disable attitude correction
	& ENA \\
{\tt ASCALINSKY}
	& Enable/disable to use ASCALIN-compatible sky coordinates
	& ENA \\
{\tt ABERRATION}
	& Enable/disable aberration correction
	& ENA \\
{\tt EULER}
	& Set reference Euler angles\footnote{
		Use an attitude of the first event when AUTO}
	& AUTO \\
{\tt REFJ2000}
	& Set reference sky position\footnote{
		Use Z-axis direction of the first event when AUTO}
	& AUTO \\
{\tt ROLLANGLE }
	& Set roll angle
	& 0.0 \\
{\tt GAINHIST}
	& Set file name of gain history file
	& 'gis\_temp2gain.fits' \\
{\tt PHGAIN }
	& Set extra factor for PI value
	& 1.0 for S2 \\
	& 
	& 1.0 for S3 \\
{\tt TELDEF }
	& Set file names of teldef files
	& gis2teldefv2.fits for S2 \\
	& 
	& gis3teldefv2.fits for S3 \\
{\tt EXIT}
	& Exit from {\tt MODIFY\_PARAM}
	& --- \\ \hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Commands in {\tt MODIFY\_PARAM} of {\tt GISTUNE}}
\label{tab:GISTUNE:MODIFY_PARAM}
\end{table}

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|l|}
\hline
BNK keyword name & Type & Comment \\ \hline
{\tt GISTUNE:PI:R8}
	& Real*8
	& Value of {\tt GIS:PI} before rounding \\
{\tt GISTUNE:RTI:R8}
	& Real*8
	& Value of {\tt GIS:RTI} before rounding \\
{\tt GISTUNE:X:R8}
	& Real*8
	& Value of {\tt GIS:X} before rounding \\
{\tt GISTUNE:Y:R8}
	& Real*8
	& Value of {\tt GIS:Y} before rounding \\
{\tt GISTUNE:DETX:R8}
	& Real*8
	& Value of {\tt GIS:DETX} before rounding \\
{\tt GISTUNE:DETY:R8}
	& Real*8
	& Value of {\tt GIS:DETY} before rounding \\
\hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Special BNK keywords of {\tt GISTUNE}}
\label{tab:GISTUNE:SpecialBNK}
\end{table}

\begin{table}[htb]
\begin{minipage}{\textwidth}
\begin{center}
\begin{tabular}{|l|l|}
\hline
EVS keyword name & Set when \\ \hline
{\tt GISTUNE:BEGIN}
	& gistune\_begin() is called \\
{\tt GISTUNE:ENTRY}
	& gistune\_ana() is called \\
{\tt GISTUNE:OK}
	& gistune\_ana() returns ASCA\_ANL\_OK \\
{\tt GISTUNE:EULER ERROR}
	& gistune\_ana() cannot get {\tt ANL:EULER}
	  and returns ASCA\_ANL\_SKIP \\
{\tt GISTUNE:LDHIT ERROR}
	& gistune\_ana() cannot get LDHIT count rate
	  and returns ASCA\_ANL\_SKIP \\
{\tt GISTUNE:RTMASK}
	& a event is rejected by the rist time mask
	  and returns ASCA\_ANL\_SKIP \\
\hline
\end{tabular}
\end{center}
\end{minipage}
\caption{Special EVS keywords of {\tt GISTUNE}}
\label{tab:GISTUNE:SpecialEVS}
\end{table}
