\chapter{On Your Own}
After learning how to `use' the ASCA\_ANL
it is time to know how to write your own analysis tools.
Since the ASCA\_ANL provides you good environment for ASCA analysis,
it is very easy to write your analysis program.
However,
and you have to know rules on writing programs on the ASCA\_ANL
before you start writing.
Also,
a few tools are provided for you to create new program easily.

In this chapter
we show you a way to create your original program on the ASCA\_ANL.
In some case
the program {\tt gisspec\_f} (or {\tt gisspec\_c}) is quoted as an example.
This program is attached to the distribution kit of the ASCA\_ANL.
and explained its usage in this manual (See \S \ref{sec:walk-through}).
You are expected to be familiar to how to use this program.
If not so,
ask how to use the program or read Section\ref{sec:walk-through}
before you begin to read here.

\section{What is the Module}
\label{sec:module}
First of all,
what is called the module in the ASCA\_ANL?
To create a new and your original module
you had better know its structure and functions in the ASCA\_ANL.
In this section
we will outline how to create the module for the ASCA\_ANL.
It includes
an explanation of a structure of the module
and some rules and recommendations on writing the module.
Most part of this section is the same for FORTRAN and C,
although detailed rules can be different between the languages
as mentioned later in this manual.

\subsection{Structure of the Module}
The module of the ASCA\_ANL consists of seven subroutines\footnote{
A calling subroutine is written in FORTRAN.
So,
one can say FORTRAN is a "native" language of the ASCA\_ANL.
But,
you also can write your module in C,
of course,
almost in the same fashion.
}.
In order to create a new module named {\tt USER},
for example,
you need subroutines named
\begin{itemize}
\item {\tt USER\_init} (Initialization routine),
\item {\tt USER\_com} (Communication routine),
\item {\tt USER\_his} (Histogram booking routine),
\item {\tt USER\_bgnrun} (Beginning-of-Run routine),
\item {\tt USER\_ana} (Analysis routine),
\item {\tt USER\_endrun} (End-of-Run routine), and
\item {\tt USER\_exit} (Exit routine).
\end{itemize}
These routines are called by the main program of the ASCA\_ANL.
The subroutines are required even if you do not need their functions.
For example,
you have to prepare {\tt USER\_his}
even if you do not have to book any histogram.
In such a case
you can write a subroutine which contains {\tt Return} statement only.

Anyway,
you don't have to understand details in each routine at present.
But all you have to know here is
``the module consists of seven basic routines''.

\subsection{Module in the ASCA\_ANL}
The seven subroutines in the module
are called by the ASCA\_ANL system.
A relationship between each subroutine
and a command in the command menu is be summarized as following:
\begin{description}
  \item[{\tt USER\_init}] corresponds to {\tt ANALYZE\_DATA}. \\
	This subroutine is called
	while 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.
  \item[{\tt USER\_com}] corresponds to {\tt MODIFY\_PARAM}. \\
	This subroutine is called for only modules
	that is selected by {\tt MODIFY\_PARAM} command.
	Since this command can be invoked any times,
	you can call this subroutine any times.
  \item[{\tt USER\_his}] corresponds to {\tt BOOK\_HISTOGRAM}. \\
	This subroutine is called for only modules
	that is selected by {\tt BOOK\_HISTOGRAM}.
	Since it is illegal to book histogram more than once,
	this subroutine can be called once for one module.
  \item[{\tt USER\_bgnrun}] corresponds to {\tt READ\_DATA}. \\
	This subroutine is called once for one data set to be processed
	just after {\tt READ\_DATA} command is invoked.
  \item[{\tt USER\_ana}] corresponds to {\tt READ\_DATA}. \\
	This subroutine is called $N$ times in processing $N$ photons
	after a series of calls of ``\_bgnrun'' entries.
  \item[{\tt USER\_endrun}] corresponds to {\tt READ\_DATA}. \\
	This subroutine is called once for one data set to be processed
	after a series of calls of ``\_ana'' entries.
  \item[{\tt USER\_exit}] corresponds to {\tt EXIT}. \\
	This subroutine is called
	just after {\tt EXIT} command is invoked.
\end{description}
In addition,
relationship between the commands and subroutines in a module
are illustrated in Figure \ref{fig:call_module}.
Note that
order of subroutine calls is always the same
as defined by the command {\tt DEFINE\_ANALYSIS}.
Also,
some of subroutines above are called less times than described above
in case that
the analysis flow is controlled by the return values of the subroutines.
See \S \ref{sec:flow-control} for details on return values.

\section{How to Create the Module}
Now you are ready to create
your own module to analyze ASCA data in your own way.
As writing usual program on your computer system,
you have to write a source file at first.
But,
not as in usual cases,
there are many restrictions and recommendations in writing a module.
In this section
we show the way to write a module for your analysis
while also summarizing such rules on a module
from a programmer's points of view.

\subsection{mkanlmodule}
A useful command `mkanlmodule' is also in the distribution kit.
This command creates a template for the module.
If you creates it with this command,
most of recommendations are satisfied automatically.
Also,
you can choose in which language, FORTRAN or C, you want to write module.

You can invoke this command
by setting an appropriate path to {\tt PATH} environment variable.
This command should be in the directory specified by {\tt ASCA\_ANL\_BIN}
in the file Includes.make\footnote{
We guess you already know this file
because you have compiled the program {\tt gisspec\_f}.
}
If you don't know where it is,
please ask a person who installed the ASCA\_ANL in your system
where the {\tt ASCA\_ANL\_BIN} means.

Before invoking {\tt mkanlmodule}
you have better know that it has two different modes to interface you,
{\em i.e.},
an interactive mode and a command line mode.
In an interactive mode
you are prompted to answer a few questions
on how to create the template of your module.
In a command line mode
you can specify all parameters in a command line.
You can find below how to use {\tt mkanlmodule} in both modes.

\subsubsection{Interactive Mode}
First, type
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% mkanlmodule
\end{verbatim}\end{quote}
without any command line option.
%
You are asked for a name of the module you intend to write.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name:  ?
\end{verbatim}\end{quote}
%
Now let us assume you are going to create the module named `USER'.
In that case, type {\tt USER} against the prompt.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name:  ? USER
\end{verbatim}\end{quote}
%
You are asked for `your language' in turn.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Do you write it in FORTRAN (Y/N): Y ?
\end{verbatim}\end{quote}
%
If it is FORTRAN,
reply {\tt Y}.
Reply {\tt N} in case of C language.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Do you write it in FORTRAN (Y/N): Y ? Y
\end{verbatim}\end{quote}
%
In above case we choose FORTRAN language.
The next and last question is for a name of an output file.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Output file: USER.f ?
\end{verbatim}\end{quote}
%
In this example
{\tt USER.f} is a default name of an output file.
If you accept this name {\tt USER.f}, hit a return key.
If not, specify the name like this:
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Output file: USER.f ? user.f
 Empty module written in user.f
\end{verbatim}\end{quote}
%
Now you can see a file {\tt user.f} is created in a current directory.
Look into the file.
That is a template for the module,
{\em i.e.},
an empty\footnote{
Can you believe it is `empty'?
} module for the ASCA\_ANL.

\subsubsection{Command Line Mode}
You can invoke {\tt mkanlmodule} in `command line mode'
by invoking it with command line options.
In this mode
you have to specify all the parameter on what your module is like.

As in the previous section,
for example,
let us assume that you want to create the module named `USER' in FORTRAN
and that a name of an output file is `user.f'.
Then you can get the file by typing like this:
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% mkanlmodule -FORTRAN -o user.f USER
\end{verbatim}\end{quote}
%
or just typing
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% mkanlmodule USER > user.f
\end{verbatim}\end{quote}
%
Above two command generates exactly the same results.

Synopsis of this command is the following
and command line options for {\tt mkanlmodule} are listed
in Table\ref{tab:mkanlmodule-command-line-option}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% mkanlmodule [ option ] module_name
\end{verbatim}\end{quote}

\begin{table}[hbt]
\begin{tabular}{ll}
\hline
Option & Function \\
\hline
{\tt -FORTRAN} & Forces to create a module written in FORTRAN (default). \\
{\tt -Fortran} & the same as above. \\
{\tt -C}       & Forces to create a module written in C language. \\
{\tt -o \underline{file}} & Specifies an output file name. \\
	& An outpur is redirected to a standard output
	when \underline{file} is `-' (default).\\
\hline
\end{tabular}
\caption{Command line option for {\tt mkanlmodule}}
\label{tab:mkanlmodule-command-line-option}
\end{table}

\subsection{Coding Analysis}
\label{sec:photon-info}
Let us start coding your own analysis
by filling an empty module with mkanlmodule.
It is a good idea
that we start to fill a subroutine {\tt USER\_ana}.
The subroutine {\tt USER\_ana} is called photon by photon;
that means here placed an essence of your original way of analysis.
Hereafter,
we explain how to fill {\tt USER\_ana}
with reffering {\tt gisspec\_f.f} as an example.

In {\tt USER\_ana}
you process each photon as following:
\begin{enumerate}
  \item get photon information\footnote{
  For example,
  photon arrival time, PHA of the photon, DETX of the photon, etc.
  },
  \item process the photon, and
  \item put a new information on the photon(if needed\footnote{
  This procedure is necessary in case you create a filter module.
  })
\end{enumerate}

In order to access information on each photon
the {\tt EVS} and {\tt BNK} system are used.
In {\tt gisspec\_f.f},
we intend to analyze only GIS PH mode data
you can select them by calling a logical function {\tt EVS}
like this (you can see this at the beginning of {\tt GISSPEC\_ana}.):
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c check if PH mode or not
      If ( EVS('GIS:PH mode') ) then
         Continue
      Else
         Write(*,*) 'DATAMODE is not PH'
         status = ASCA_ANL_QUIT
         Return
      Endif
\end{verbatim}\end{quote}

An argument of the logical function {\tt EVS} is called "EVS keyword".
In above case
{\tt 'GIS:PH mode'} is an EVS keyword\footnote{
This keyword is reserved by the ASCA\_ANL system.
The reserved EVS keywords are listed in Appendix \ref{sec:EVS}.
%in Table \ref{tab:EVS-key} 
} 
to know whether the photon is read out in GIS PH mode or not.
If the current photon had arrived during GIS PH mode,
{\tt If} statement causes an execution of {\tt Continue}.
Otherwise,
{\em i.e.},
in case of GIS data in other mode or SIS data,
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
         Write(*,*) 'DATAMODE is not PH'
         status = ASCA_ANL_QUIT
\end{verbatim}\end{quote}
are executed and returned to a calling routine in the ASCA\_ANL.

By returning with {\tt ASCA\_ANL\_QUIT}\footnote{
The value for {\tt ASCA\_ANL\_QUIT} is defined in asca\_anl.inc.
See a file {\tt Includes.inc} in your current directory.}
set to {\tt status} (the third argument of {\tt GISSPEC\_ana})
you can force the ASCA\_ANL discard the whole data set
which is read by {\tt READ\_DATA} command(See \S \ref{sec:walk-through}).
In above case
only GIS PH mode data is selected and others are discarded.
In the same way
By returning with {\tt ASCA\_ANL\_SKIP} set to {\tt status}
you can force the ASCA\_ANL discard the current photon.
This feature is useful for a filter module.
See \S \ref{sec:flow-control} for details.

After selecting data
let us get parameters of the photon by calling {\tt BNKget} subroutine.
If you need to know a sensor ID, an energy of a photon, etc.,
call a subroutine {\tt BNKget} like in {\tt gisspec\_f.f}.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c get sensor id
      CALL BNKget('ANL:SENSOR', sizeof(sensor), size, sensor)

c get pha and pi
      CALL BNKget('GIS:PHA', sizeof(pha), size, pha)
      CALL BNKget('GIS:PI', sizeof(pi), size, pi)
      .....
\end{verbatim}\end{quote}
%
In this example
{\tt size}, {\tt sensor}, {\tt pha}, and {\tt pi}
are integer variables in {\tt gisspec\_f.f}.
After the call,
for example,
{\tt pha} is set to a value of "PHA column"
in an analyzed science FITS file\footnote{
If you analyze FRF with {\tt GISREAD}/{\tt GISTUNE},
obtained value is read from FRF.
}.
{\tt size} is set to a size of data actually got by the call.
The variable {\tt size} is equal to four in an above case
if the data is successfully obtained.

The first argument of the subroutine {\tt BNKget} is called BNK  
keyword.
{\tt 'GIS:PHA'} is a BNK keyword
to obtain a value of "PHA column" in a FITS file.
The BNK keyword {\tt 'GIS:PHA'} is reserved by the ASCA\_ANL system.
The reserved BNK keywords are listed
in Table \ref{tab:BNK-key} in Appendix \ref{app:BNK-key}.
The size of data you should specify as a second argument of {\tt  
BNKget}
are also listed in the table.

The last process in {\tt GISSPEC\_ana} is to fill data into histograms.
You can assume the histograms are booked preceeding to {\tt USER\_ana} calls
by {\tt BOOK\_HISTOGRAM} command.
Also,
histogram ID's are declared in {\tt USER\_his}.
We will explain how to declare histograms in {\tt USER\_his} later.
Anyway,
you can see following statements in {\tt gisspec\_f.f}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c make spectrum & image
      If ( (2 .eq. sensor) .or. (3 .eq. sensor) ) then
         offset = sensor * 100
         Call Hf1(offset+00, real(pha), 1.0)
         Call Hf1(offset+10, real(pi), 1.0)
         Call Hf1(offset+20, real(rt), 1.0)
         Call Hf1(offset+30, real(rti), 1.0)
         Call Hf2(offset+40, real(rawx), real(rawy), 1.0)
         Call Hf2(offset+50, real(detx), real(dety), 1.0)
         Call Hf2(offset+60, real(skyx), real(skyy), 1.0)
      Endif
\end{verbatim}\end{quote}
In this example
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
         Call Hf1(offset+00, real(pha), 1.0)
\end{verbatim}\end{quote}
filles {\tt 1.0} into a bin
corresponding to a value of {\tt pha} in 1 dimensional histograms
with histogram ID of 200 and 300 for GIS--2 and GIS--3, respectively.
In the same way
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
         Call Hf2(offset+40, real(rawx), real(rawy), 1.0)
\end{verbatim}\end{quote}
fills {\tt 1.0} into a bin
corresponding to values of {\tt RAWX} and {\tt RAWY}
in 2 dimensional histograms
with histogram ID of 240 and 340 for GIS--2 and GIS--3, respectively.
See Appendix \ref{chap:HBOOK}
for an detailed explanation of arguments of Hf1 and Hf2.

The ASCA\_ANL requires two kinds of settings as following:
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c set GISSPEC:OK for ASCA_ANL_OK
      Call EVSset('GISSPEC:OK')
      status = ASCA_ANL_OK
c
      Return
      End
\end{verbatim}\end{quote}
However, you don't worry about this
because {\tt mkanlmoudule} creates these statements automatically.

\subsection{Definition of Histogram}
In order to fill a value into a histogram
the histogram is booked preceedingly.
To do this,
{\tt USER\_his} subroutine is used.
In our {\tt GISSPEC\_his}
histograms for GIS spectra and GIS images are booked.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c Define Histogram
      Call Hbook1(200, 'GIS2 PHA', 1024, -0.5, 1023.5, 0.0)
      Call Hbook1(300, 'GIS3 PHA', 1024, -0.5, 1023.5, 0.0)
      ...
c RAWX/Y is 0-255
      Call Hbook2(240, 'GIS2 RAWX vs RAWY',
     &    256, -0.5, 255.5, 256, -0.5, 255.5, 0.0)
      Call Hbook2(340, 'GIS3 RAWX vs RAWY',
     &     256, -0.5, 255.5, 256, -0.5, 255.5, 0.0)
\end{verbatim}\end{quote}
The first two calls of {\tt Hbook1} declare 1 dimensional histograms
titled {\tt GIS2 PHA} and {\tt GIS3 PHA}
with histogram ID of 200 and 300, respectively.
Both are defined as histograms covering {\tt -0.5} to {1023.5} with 1024 bins.
Another two calls of {\tt Hbook2} declare 2 dimensional histograms
titled {\tt GIS2 RAWX vs RAWY} and {\tt GIS3 RAWX vs RAWY}
with histogram ID of 240 and 340, respectively.
Remember that these ID's are the same as those used in {\tt GISSPEC\_ana}.
See Appendix \ref{chap:HBOOK}
for an detailed explanation of arguments of Hbook1 and Hbook2.

The last statement is to set {\tt status}
(only one argument of {\tt USER\_ana}).
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      status = ASCA_ANL_OK
      Return
      End
\end{verbatim}\end{quote}
Again, you don't worry about this
because {\tt mkanlmoudule} creates these statements automatically.

\subsection{User Interface}
Some modules have several parameters to be specified by users.
To ask parameters to users,
{\tt USER\_com} is used.
In our example program {\tt gisspec\_f}
an good example can be seen in {\tt circreg\_com}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c ask user for sensor ID
         Call Intrd('Sensor to set (-1=end of set)', sensor)
         .....
c ask user for center and radius of selection region
         Call Fltrd('DETX of Center (pixel)', cx(sensor))
         Call Fltrd('DETY of Center (pixel)', cy(sensor))
         Call Fltrd('Radius (pixel)', r(sensor))
\end{verbatim}\end{quote}
The first call of {\tt Intrd} ask a user for a four-byte integer value
with {\tt Sensor to set (-1=end of set)} as a prompt.
The subroutine {\tt Intrd} also prints out 
a value in the four-byte integer variable {\tt sensor} before this call
as a default value(See \S \ref{sec:walk-through}).
After returning from this call,
a specified value is set to the variable {\tt sensor}.
In the same way
a four-byte floating point variable can be asked as in the above example.
The subroutine {\tt Fltrd} does everything boring
such as printing out a message to a user and treating a default value.
These subroutines {\tt Intrd} and {\tt Fltrd} are in the CLI package.

There are many cases to ask a user for various types of values
including a string, a logical value, and so on.
Sometimes
you want to ask a user for a command which defines an action of your module.
These are comfortably done by subroutines in the CLI/COM packages.
See the memo on CLI/COM in files {\tt cli.mem} and {\tt com.mem}\footnote{
These are stored in a directory doc/ in the distribution kit.
Ask a person who installed the ASCA\_ANL in your computer
where the directory is.
} as a reference.
One of good examples of COM package 
is a command line interface of such a kind in the ASCA\_ANL.
You already know
that the list of command is printed with a prompt
like {\tt ANL: Select  1 Option} or {\tt ANL: Select  1 or More, Then OK},
that a command can be abbreviated,
and so on.
All these are done by a subroutine {\tt Inquire}\footnote{
See the memo {\tt com.mem} for details.
} in the COM package.
A complex user interface is realized
by a simple call of {\tt Inquire} in your module.

Note that
the unified user interface
is one of the most important features of the ASCA\_ANL
and you are strongly recommended to use CLI/COM packages
at user interface in your own module.

\subsection{Initialization and Termination}
In some applications
we need to initialize a module before the analysis
or to do something before the program is terminated.
{\tt USER\_init} and {\tt USER\_exit} are reserved for such actions.

In {\tt gisspec\_f}
only two initializations are done.
First,
EVS flags for the module are defined like this.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
c EVS
      Call EVSdef('GISSPEC:BEGIN')
      Call EVSdef('GISSPEC:ENTRY')
      Call EVSdef('GISSPEC:OK')
\end{verbatim}\end{quote}
%
Second,
a version number of the module is put with {\tt BNKput}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Call ANL_put_version('GISSPEC' , 'version 4.0')
\end{verbatim}\end{quote}

These two are all you have to do in {\tt USER\_init}
and are automatically generated by {\tt mkanlmodule}.
Of course,
you can put other initialization in {\tt USER\_init},
for example,
you can define other EVS flags or BNK keywords\footnote{
You have to be careful to define your own EVS/BNK keywords.
See \S \ref{sec:BNK-EVS-key} for detailed explanations.
}.
In most cases,
however,
you don't have to add anything to {\tt USER\_init}.

In {\tt GISSPEC\_exit}
we can see nothing but setting a value to {\tt status}.
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Subroutine GISSPEC_exit (status)
      Implicit NONE
c output
      Integer status
c include
      Include 'Includes.inc'
c
      status = ASCA_ANL_OK
      Return
      End
\end{verbatim}\end{quote}
This means
nothing is done for the module {\tt GISSPEC} at the termination.

Again, in most cases
you don't have to add anything to {\tt USER\_exit}.

\subsubsection{Note for initialization of local variale}
Now you may plan to initialize variables for the module in {\tt USER\_init}.
But, wait a minute. Does your module work O.K.?

In the ASCA\_ANL
{\tt USER\_init} is NOT necessarily called at first
among seven subroutines required for a module,
{\em i.e.},
{\tt USER\_com} and {\tt USER\_his} can be called before {\tt USER\_init}
(See Figure \ref{fig:call_module}).
Therefore
if you set a default value to a parameter in {\tt USER\_init}
and if the parameter can be modified with a {\tt MODIFY\_PARAM} command,
you will have an unexpected result in case that you modify the parameter.
In this case
the parameter is always set to the default value set in {\tt USER\_init}
because {\tt USER\_init} is called after a call of {\tt USER\_com}.

To avoid this kind of problem,
initialization of variables have to be done with another method.
If you write a module in FORTRAN,
you may use a block data initialization.
If in C,
you had better use a static global variable for such a parameter.
In both cases
the initialization is performed at their compilation,
so you can get an expected action of your module.

\subsection{Opening and Closing Data Set}
{\tt USER\_bgnrun} and {\tt USER\_endrun} are subroutines
to open and close the data set, respectively.
Thus,
Most modules does not have to fill these subroutines.
In {\tt gisspec\_f} these two are almost blank.
Although {\tt EVSset} in {\tt GISSPEC\_bgnrun} have to be done here,
{\tt mkanlmodule} creates following subroutines automatically.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Subroutine GISSPEC_bgnrun (status)
      Implicit NONE
c output:
      Integer status
c include
      Include 'Includes.inc'
c  EVS set
      Call EVSset('GISSPEC:BEGIN')
c
      status = ASCA_ANL_OK
      Return
      End
\end{verbatim}\end{quote}

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
      Subroutine GISSPEC_endrun (status)
      Implicit NONE
c output
      Integer status
c include
      Include 'Includes.inc'
c
      status = ASCA_ANL_OK
      Return
      End
\end{verbatim}\end{quote}

\section{How to ``Link'' Your Module}
To link your modules to the ASCA\_ANL
you have to write appropriate makefile for your program.
However it is a little bit boring to create a makefile.
So we recommend to use a makefile in the sample as a template.
If you follow our recommendation,
it is better for you to know what is happening
while compiling and linking your modules.
In this section
we show how to link your modules
from how to create makefile for the ASCA\_ANL
to what is happening in linking your modules.

\subsection{Makefile in the Sample}
Makefile for samples consist of three files,
that is,
{\tt Makefile}, {\tt Makefile.tmpl}, and {\tt Includes.make}.
{\tt Makefile} contains usual rules to ``make'' your program,
and {\tt Makefile.tmpl} includes macro definitions, suffix rules, and so on.
A directory structure of your computer system
is described in {\tt Includes.make}
which is arranged by a person who installed the ASCA\_ANL.

Since macros and suffix rules written in {\tt Makefile.tmpl}
are common and useful for most application of the ASCA\_ANL,
you can use this file as a tool box to ``make'' your module.
You don't have to follow instructions in following sections
when you ``make'' your module with {\tt Makefile.tmpl},
because it automatically creates files required and compiles them.
All you have to do is to create a file
containing names of modules to be linked to your program.
The rules to create this file are:
\begin{itemize}
  \item the name of the file have to have an extension ``.def''
  \item names of modules are separated by one carriage return
  \item the last character of this file is carriage return
\end{itemize}

To modify {\tt Makefile} for your program
a header of {\tt Makefile.tmpl} (lines commented out at the beginning)
is useful as a reference.
You cut there,
paste it to {\tt Makefile},
modify macros to fit your program,
and remove comment marks {\tt \#}.
Here you are ready to ``make'' your program.
Type,
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% make
\end{verbatim}\end{quote}
without your program name.
Then
{\tt make} judges the OS,
creates required files to link modules,
compiles them,
and links them.
Finally
you can get your own analysis program.

\subsection{What is happening}
When you use a makefile for samples
as a template of a makefile for your program,
you don't have to care about how to compile and link your program.
However for those who want to know what is happening
while samples are automatically compiled,
we explain how to link your module to the ASCA\_ANL
and make an executable of your analysis program
in following sections.

Following sections are written as instructions for you to link by yourself.
Read and follow instructions if you are interested in.
Note that
in case of using sample makefile
all these are automatically executed.

\subsubsection{Overview}
Before "making" your analysis program,
you have to create one or two text files.
The files includes several FORTRAN subroutines and C functions
interfacing the ASCA\_ANL system and your (or "ready-made")  
modules.
Don't worry,
there are commands in the ASCA\_ANL package
to create these files automatically.
All you have to do is to specify the names of the modules.

The commands are {\tt mkanlinit} and {\tt mkanlCwrapper}.
(Later in this section we will show you how to use them.)
The "mkanlinit" creates a file containing C functions
necessary for all the modules you want to link.
Thus,
you have to run the {\tt mkanlinit} whenever you create a new analysis  
program.

The {\tt mkanlCwrapper} creates a file containing a C functions\footnote{
The functions just for interfacing C and FORTRAN.
}
necessary for the modules written in C
but not created by the command {\tt mkanlmodule}\footnote{
The {\tt mkanlmodule} attaches the same interfacing functions
at the end of a template.
Create a template by {\tt mkanlmodule} and see its end!
}.
Thus,
if you don't have any C module,
you don't have to run the {\tt mkanlCwrapper}.
But,
if you have more than one module written in C,
you have to run the "mkanlCwrapper".
Note that
you don't have to run {\tt mkanlCwrapper}
as long as you starts to write a module
from a template created by {\tt mkanlmodule}

To obtain an executable of your program,
compile these interface files by a compiler in your system
and link them to the ASCA\_ANL together with the module you registered.
An example of makefile is in the distribution kit of the ASCA\_ANL
and also in Appendix.
You can easily create a makefile for your program
by a slight change\footnote{
For example,
path name of the ASCA\_ANL system in your computer system
path name of libraries ({\em e.g.} CERN Library),
name of the program you create,
the modules you registered,...
}
of the sample makefile.

Now it is time to "make" it.
You get your original analysis program.
Enjoy!

\subsubsection{mkanlinit}
In order to construct your analysis program
you have to register modules you use in the program.
The mkanlinit creates a text file
which contains a function {\tt main()}'
and a few C functions to register the modules.
The text file usually has a name of {\tt anlinit.c},
but you can specify it as you desired.

Anyway run mkanlinit first.
The mkanlinit is in a distribution kit of ASCA\_ANL.
Please ask a system manager of your computer system
where the mkanlinit is installed.

You will be asked for a name of the module you want to register.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ?
\end{verbatim}\end{quote}
%
If you want to register a module named {\tt FITSREAD} at first,
reply {\tt FITSREAD} to the question.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 1]:  ? FITSREAD
Enter module name or *command [ 2]:  ?
\end{verbatim}\end{quote}
%
If you also want to register a module named {\tt USER},
reply {\tt USER} to the next question.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 2]:  ? USER
Enter module name or *command [ 3]:  ?
\end{verbatim}\end{quote}
%
In this way you can register as many modules as you need.

To finish specifying the module name
press a return key without typing any name.
Then you will see the module names to be registered
and be asked for a name of an output file,
{\em i.e.}
the text file which contains a few FORTRAN subroutines
to register the modules.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name or *command [ 3]:  ?

 Following modules are to be linked to ASCA_ANL:
     [ 1] FITSREAD
     [ 2] USER

Output file: anlinit.c ?
\end{verbatim}\end{quote}
%
If you accept a default name {\tt anlinit.c},
press return key.
If you want to specify another name,
reply the name to the question.

In case that a file with the same name already exists
you will be confirmed if you intend to delete the old file or not.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
'anlinit.c' already exists, delete (Y/N): N ?
\end{verbatim}\end{quote}
%
If you reply {\tt Y},
the old file will be deleted and the output file will be created.
If you reply {\tt N},
the old file will not be deleted and you will be asked for a file  
name again.

After replying all the questions above,
the mkanlinit creates the text file containing the registration  
subroutines and terminates.

\subsubsection{mkanlCwrapper}
If you link modules written in C by your hand\footnote{
This means `not by a command {\tt mkanlmodule}' here.
},
you have to create another text file
which contains several C functions\footnote{
Written in "cfortran" format.
The cfortran is a standard package in CERN Library
interfacing C and FORTRAN.
} (called C wrappers)
required for the C modules
to be called by the ASCA\_ANL written in FORTRAN.
The text file usually has a name of {\tt anlCwrapper.c},
but you can specify it as you desired.

Anyway run mkanlCwrapper first.
The mkanlCwrapper is in a distribution kit of ASCA\_ANL.
Please ask a system manager of your computer system
where the mkanlCwrapper is installed.

You will be asked for a name of the C module you want to link.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name [ 1]:  ?
\end{verbatim}\end{quote}
%
If you want to link a module named {\tt User},
reply {\tt User} to the question.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name [ 1]:  ? User
Enter module name [ 2]:  ?
\end{verbatim}\end{quote}
%
Notice
that this specification is case-sensitive.
You have to specify the exact name in C program.
This fact also means
you have to use the same case for all the entries.
For example,
once you make an entry {\tt User\_init},
you can not name a communication routine {\tt USER\_com}
but you have to name it {\tt User\_com}.

To finish specifying the module name,
press return key without typing any name.
Then you will see the C module names to be linked to the  
ASCA\_ANL
and be asked for a name of an output file,
{\em i.e.}
the text file which contains several C wrappers for the ASCA\_ANL.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Enter module name [ 2]:  ?

 Following modules (written in C) are to be linked to ASCA_ANL:
     [ 1] User

Output file: anlCwrapper.c ?
\end{verbatim}\end{quote}
%
If you accept a default name {\tt anlCwrapper.c},
press return key.
If you want to specify another name,
reply the name to the question.

In case that a file with the same name already exists
you will be confirmed if you intend to delete the old file or not.
%
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
'anlCwrapper.c' already exists, delete (Y/N): N ?
\end{verbatim}\end{quote}
%
If you reply {\tt Y},
the old file will be deleted and the output file will be created.
If you reply {\tt N},
the old file will not be deleted and you will be asked for a file  
name again.

After replying all the questions above,
the mkanlCwrapper creates the text file containing the C wrappers
and terminates.
