\section{General Yohkoh Software}

\subsection{Routines for Reading and Saving Data}

\subsubsection{RD\_XDA, RD\_xxx} 
\index{RD\_BDA}
\index{RD\_HDA}
\index{RD\_SDA}
\index{RD\_WDA}
\index{RD\_XDA}

The RD\_xxx routines (RD\_BDA, RD\_HDA, RD\_SDA, RD\_WDA, RD\_XDA) 
allow you to read the reformatted data files.  Each
routine has the same calling sequence, and there is a generic reading routine
called RD\_XDA which will read data for any of the instruments.  After you have
established the input file name(s) ({\it infil}) and which data sets to 
extract ({\it dset\_arr}), you can read the data by a command:
%
\idlinputa{rd\_sda, infil, dset\_arr, index, data}	
\idlinputb{rd\_sda, infil, dset\_arr, index, data, roadmap}	 \index{RD\_SDA}
\idlinputb{rd\_xda, infil, -1, index, /nodata}
%
{\it index} is a structure which describes the data.  There is one index structure
for each dataset.  The roadmap is for all datasets in the files (not just
the selected datasets).  It is possible to read all datasets in the file
by specifying -1 for {\it dset\_arr}.  The {\it /nodata} switch tells the routine
to only read the index and roadmap, not the data.

\subsubsection{RD\_ROADMAP}
\index{roadmap}

RD\_ROADMAP will read the roadmap from a file (or list of files) by typing:
%
\idlinputa{rd\_roadmap,infil,roadmap,ndset} \index{RD\_ROADMAP}
%
where {\it infil} is a string array of file names.  The roadmap
variable is the same as you get from YODAT

\subsubsection{RD\_QS} \index{RD\_QS}

RD\_QS will read the quasi-static portion of a single reformatted file.  A
sample calling sequence is:
%
\idlinputd{rd\_qs, infil, qs}
%
\subsubsection{SAVEGEN and RESTGEN} \index{SAVEGEN}
\index{GENX files, reading/writing}

Details on SAVEGEN and RESTGEN are given in the SolarSoft Reference Manual.
NOTE: It is recommended to use 
SAV\_SDA, SAV\_BDA, SAV\_BSC, and SAV\_HXI whenever possible for standard
SXT, BCS, and HXI data sets.  

\subsubsection{SAV\_SDA}
\index{SXT archive files, writing}

SDA\_SDA will store an index and data array in an SDA format file.  The
data array can be byte, integer*2, integer*4 or real*4.  The dimensions of
the image do not have to be the original dimensions.  A sample is:
%
\idlinputa{sav\_sda, outfil, index, data}	\index{SAV\_SDA}
\idlinputb{sav\_sda, outfil, index, data, qs}
%
where {\it outfil} is the name of the file you wish to store the data in.  If you
wish to append to an existing file, then you can use the /APPEND switch. For
example:
%
\idlinputa{sav\_sda, outfil, index, data, /append}
%
Use RD\_SDA to restore the data.

\subsubsection{SAV\_BDA and SAV\_BSC}
\index{BCS archive files, writing}

SAV\_BDA and SAV\_BSC work in the same manner as SAV\_SDA but for
raw BDA data or BSC processed data.  Sample calls would be:
%
\idlinputa{sav\_bda, outfil, index, data, qs, dp\_sync} \index{SAV\_BDA} 
\idlinputc{sav\_bsc, outfil, index, data} \index{SAV\_BSC} 
%
\subsubsection{SAV\_HXI}

SAV\_HXI allows you to save HXT synthesized images.  A sample call would be:
%
\idlinputd{sav\_hxi, outfil, index, data} \index{SAV\_HXI} 
%

\subsubsection{SXT2FITS}

It is possible to take an SXT data file or an {\it index} and {\it data} that has
already been read in, and write a single FITS file for each image.  The
FITS header has all of the information on the date and time, the filters
used, the exposure duration, the resolution, and the DP mode and rate.  The
following command will create a file for each image in the {\it data} array: \index{FITS files}
%
\idlinputa{sxt2fits, index, data} \index{SXT2FITS}
%
The default file names are SF\_FITSyymmdd.hhmmss and 
SP\_FITSyymmdd.hhmmss for FFI and PFI images, respectively.  If a single output file name is passed
to the SXT2FITS routine, but there are several images to save, then it will
append an image number to the end of the file name.  In the following example,
the input array is 512$\times$512$\times$3, so it will create the files `flare.0001', `flare.0002'
and `flare.0003'.
%
\idlinputa{sxt2fits, index, data, outfil='flare'}
%
It is possible to specify an input file name in which case all images in that
file will have FITS files created.  It is also possible to specify a list
of the images to be saved.  Some examples of these calls are:
%
\idlinputa{sxt2fits, index, data, ss=ss}	
\idlinputb{sxt2fits, infil=infil}	
\idlinputc{sxt2fits, infil=infil, ss=ss}
%

\subsection{Routines for Data Selection}

\subsubsection{TIM2DSET}
\index{time, searching for closest}
\index{data selection, time}

TIM2DSET will take the roadmap and return the dataset number which is
closest to that time.  Examples,
%
\idlinputa{dset = tim2dset(roadmap, input\_times)}	\index{TIM2DSET}
\idlinputc{dset = tim2dset(roadmap, '23-jun-92 6:00')} 
%

\subsection{Routines for Making Time Plots}

\subsubsection{PLOTY}
\index{observing log}

PLOTY plots light curves from all the Yohkoh
instruments on the same plot with the same time axis.  If you have the
observing log on-line and wish to use it to make the plots, you can
specify the plot times.  It is recommended to plot no more than 
approximately 24 hours of data at a time.  An example is:
%
\idlinputa{ploty, '8-may-92 15:00', '8-may-92 18:40'} \index{PLOTY}
%
If you have identified an instrument file for which you want to see the light
curve for all the other instruments, you can use the following command
(it assumes that the other instrument data files exist on the same 
directory as the input file):
%
\idlinputa{ploty, infil='/yd5/flares/spr911115.2141'}
%
You can read the observing log data, and the use PLOTY with a command
like:
%
\idlinputa{rd\_obs, '8-may-92', '8-may-92 12:00', bcs, sxtf, sxtp, w\_h}	
\idlinputc{ploty, bcs, w\_h, sxtp, w\_h} 
%
\subsubsection{OBS\_PlOT}

TODO - needs text

\subsection{Routines for Data and Information Extraction}

\subsubsection{The Concept Behind the GT Routines}

A series of GT routines was created so that a single piece of information
can be extracted from a structure, whether the structure was a `roadmap'
or an `index' (the data are saved in a different location).  The routines
also allow for conversions to a string mnemonic or to physical units.  
It is possible to get a list of what the different values are by typing a
command like:
%
\idlinputa{print, gt\_filta()}
%
It is also possible to convert the output value to the string mnemonic by using the
{\it /STRING} switch.  For example:
%
\idlinputa{print, gt\_filta(roadmap, /string)}
%
This command only works for the routines which return a coded value.
A list of all of the GT routines currently available are:

% LIST_GT.TEX input starts here -------------------------------

\index{GT\_ routines}
\input list_gt.tex

% LIST_GT.TEX input starts here -------------------------------

\subsubsection{GT\_DP\_RATE}
\index{telemetry rate}
\index{spacecraft telemetry rate}

GT\_DP\_RATE will extract the information on the DP telemetry rate.
The values are shown below.  

\vspace{0.2in}\begin{tabular}{|l|l|} \hline
       1 & {Low  ( 1 Kbits/sec)} \\
       2 & {Med  ( 4 Kbits/sec)} \\
       4 & {High (32 Kbits/sec)} \\ \hline
\end{tabular}\vspace{0.2in}
~\\
%
\idlinputa{dprate = gt\_dp\_rate(index)}	\index{GT\_DP\_RATE}
\idlinputc{dprate = gt\_dp\_rate(roadmap, /string)} 
%
\subsubsection{DPRATE2SEC}

DPRATE2SEC will take a structure (or an integer value 1, 2 or 4 for
low, medium, or high) and return the number of seconds that passes for
a major frame at that telemetry rate.

\vspace{0.2in}\begin{tabular}{|l|l|} \hline
       1 & {  64 sec (Low)} \\
       2 & {  16 sec (Med)} \\
       4 & {   2 sec (High)} \\ \hline
\end{tabular}\vspace{0.2in}
%
\idlinputd{nsec  = dprate2sec(index)}\index{DPRATE2SEC} 
%
\subsubsection{GT\_DP\_MODE}
\index{telemetry mode}
\index{spacecraft telemetry mode}

GT\_DP\_MODE will extract the information on the DP mode.  There are 
several modes, but the most common are:

\vspace{0.2in}\begin{tabular}{|l|l|} \hline
        9 & {  Flare  } \\
       11 & {  BCS-OUT} \\ 
       12 & {  Night  } \\
       13 & {  Quiet  } \\ \hline
\end{tabular}\vspace{0.2in}
~\\
%
\idlinputa{dpmode = gt\_dp\_mode(index)}	\index{GT\_DP\_MODE}
\idlinputc{dpmode = gt\_dp\_mode(roadmap, /string)} 
%

\subsubsection{GET\_INFO}

\label{get_info}
GET\_INFO will take the roadmap or index structure and return a
string describing the main observing mode parameters for each 
dataset. 
%
\idlinputa{info\_array = get\_info(roadmap)} \index{GET\_INFO} 
%
An example for a dataset for SXT data is:

\begin{verbatim}
   0 15-NOV-91  22:42:24  FL/H  NaBan/Open  Full Norm C  16   238.0   64x 64
\end{verbatim}

The ``0'' is the image number in the index or roadmap which was passed to GET\_INFO, ``15-NOV-91  22:42:24''
is the start date and time of the exposure, ``FL/H'' says the DP was in flare mode
in high telemetry rate, ``NaBan/Open'' are the filters, ``Full'' is the
pixel resolution, ``Norm'' says it was a normal exposure (not a dark frame),
``C'' is compressed data, ``16   238.0'' is the DP exposure level (DPE)
and the expected exposure duration in milliseconds, and ``64x 64'' is the
image shape.

An example for a dataset for SXT data when using the /LONG option is:

\scriptsize
\begin{verbatim}
   0 15-NOV-91  22:42:24  FL/H  NaBan/Open  Full Norm C  16   238.0   64x 64  100%  S13W18   0% SAA  2.6
\end{verbatim}
\normalsize

The first 80 columns are the same as above.  The ``100\%'' says that all of the image 
was received from the S/C, ``S13W18''
are the heliocentric coordinates of the PFI, ``0\%'' of the image was saturated,
``SAA'' signifies that it was during an South Atlantic Anomaly (SAA) passage, and
``2.6'' is the number of minutes before spacecraft night.

For HXT,WBS and BCS data, the routine only returns the date, time,
DP mode and DP rate.

\subsection{Routines for Calibration and Analysis}

\subsubsection{FSP\_PROC [*]} \index{spectral fitting}

FSP\_PROC is a general routine for doing spectral fits. {\it detector} is a string 
variable containing the detector name, {\it cfile} is the input file name, the 
format for an input file is given in /ys/ucon/soft/mctiernan/spectral\_data\_format, 
{\it ofile} is an output file name.  {\it tyspec} denotes the type of spectrum you want 
to fit (try doc\_library, 'fsp\_proc' for a complete list). {\it fit\_pars} is the 
structure containing the results.  Optional parameters:
{\it sc\_par} is a structure containing spectrometer channel info, {\it ch\_dta} is a 
structure containing the data for each channel, {\it pfile} is the name for an 
output plot file, {\it sdel} is an array of channels you'd like to delete, 
{\it flux\_corr} is any correction to the overall flux you might want to make, 
{\it nsigmas} tells you how many sigmas above background a ``good'' channel will
be (default is 3.0), {\it noplot} suppresses screen plots.
%
\idlinputd{FSP\_PROC, detector, cfile, ofile, tyspec, fit\_pars} \index{FSP\_PROC}
%
\subsubsection{FSP\_11 [*]} \index{spectral fitting}

FSP\_11 is a general routine for doing spectral fits. {\it inpf} is a strarr 
containing the detector response filenames,  {\it tyspec} denotes the type of 
spectrum you want to fit (try doc\_library, 'fsp\_11' for a complete list). 
Data must be put in the proper fields of the structures {\it fit\_pars, sc\_par }
and $ch\_dta$. $fit\_pars$ is the structure containing the results, $sc\_par$ is a 
structure containing spectrometer channel info, $ch\_dta$ is a structure 
containing the data for each channel.  Optional parameters:
$ofile$ is the name for an output file, $pfile$ is the name for an output plot 
file, $sdel$ is an array of channels you'd like to delete, $flux\_corr$ is any 
correction to the overall flux you might want to make, $nsigmas$ tells you 
how many sigmas above background a ``good'' channel will be (default is 3.0), 
$noplot$ suppresses screen plots.
%
\idlinputd{FSP\_11, detector, inpf, tyspec, fit\_pars, sc\_par, ch\_dta} \index{FSP\_11}
%
\subsection{Routines for Image Alignment}

The routines described here can generally be used on SXT or 
ground-based images.

\subsubsection{SXT\_PREP}

See the description of SXT\_PREP on page~\pageref{sxt_prep} for details on aligning SXT images.

\subsubsection{Other Routines}

See the SolarSoft Reference Manual.


\subsection{Accessing Secondary Databases}

\subsubsection{CONTACTS}
\index{station contacts}

CONTACTS will give information on when the ground station contacts are 
for a given day.  The output from the command below is shown.
%
\idlinputa{contacts,'2-jun-92'}\index{CONTACTS}
%
\begin{verbatim}
             Kagoshima Space Center Contacts           Minutes of
                  Starts                   Ends       Day  Ngt  Tot
         JST              (UT)             JST
 2-JUN-92 02:56:14 ( 1-JUN-92 17:56:14)   03:07:14    3.5  7.5 11.0
 2-JUN-92 04:39:59 ( 1-JUN-92 19:39:59)   04:48:59    7.8  1.2  9.0

 2-JUN-92 20:27:14 ( 2-JUN-92 11:27:14)   20:37:14    4.0  6.0 10.0
 2-JUN-92 22:09:14 ( 2-JUN-92 13:09:14)   22:21:14    0.0 12.0 12.0
 2-JUN-92 23:52:29 ( 2-JUN-92 14:52:29)   00:04:14    0.0 11.8 11.8
\end{verbatim}
A blank line is inserted to show that the second set of contacts
is for a different series of contacts (they come in clusters of
five or six per day).  It is possible to get the station contacts times
for DSN stations by using the {\it /CANBERRA, /GOLDSTONE} or {\it
/MADRID} switches.  It is possible to specify an end time and output
files in the following example:
%
\idlinputd{contacts, '1-jun-92', '10-jun-92', outfil='contacts.txt'} 
%
\subsubsection{PR\_FEM}
\index{ephemeris, spacecraft (FEM)}
\index{spacecraft ephemeris (FEM)}
PR\_FEM will print out Yohkoh's day and night events by typing:
%
\idlinputd{pr\_fem, '1-jan'} \index{PR\_FEM}
%
\subsubsection{PR\_EVN}
\index{event log}
\index{EVN, event log}
\index{Yohkoh event log}

PR\_EVN helps you find when there is Yohkoh data available.  An event is driven
by a change between QUIET and FLARE mode, or when there is a data gap of more 
than 60 seconds.  By typing:
%
\idlinputa{pr\_evn, '23-jun-92'} \index{PR\_EVN}
%
a list of the times that Yohkoh data are available and the number of datasets
available for each instrument are listed for 24 hours starting at 23-jun-92 00:00.
By typing:
%
\idlinputa{pr\_evn, '15-nov-91 20:00', '17-nov-91 15:00', /flare}
%
all times that Yohkoh was in FLARE mode between those times is listed.  By typing:
%
\idlinputa{pr\_evn, '1-jan-92', '1-jan-93', /flare, /counts, mindur=5, outfil='pr\_evn.results'}
%
the FLARE modes for 1992 are listed, and since the /COUNTS option was used, the maximum 
counting rate for certain WBS, HXT, and BCS channels is printed instead of the
number of datasets available.  It also prints the GOES classification when
it is available.  See the User's Guide for a sample output listing.

\subsubsection{PLOT\_EVN}
\index{PLOT\_EVN}

PLOT\_EVN will plot a very basic time line showing when the
station contacts are available, when the SAA passages are, when
the S/C day and nights are, and the periods when there is 
Yohkoh data available.  It shows when there is FLARE and QUIET
data.

%% \subsubsection   {RD\_FEM, RD\_EVN, RD\_GEV, RD\_GXT and RD\_NAR}
\subsubsection{RD\_FEM}
\index{ephemeris, spacecraft (FEM)}
\index{spacecraft ephemeris (FEM)}

To read the FEM, EVN ,GEV or NAR structures, use a command similar to:
%
\idlinputa{rd\_fem, sttim, entim, fem}	\index{RD\_FEM}
\idlinputb{rd\_evn, index(0), index(n-1), evn}	\index{RD\_EVN}
\idlinputb{rd\_nar, '1-nov-91', '2-nov-91', evn}\index{RD\_NAR}\index{RD\_GEV}\index{RD\_GXT}
%
Look at the File Control Document for a description of the structures
which are returned.

\subsubsection{RD\_OBS}
\index{observing log, reading}

A sample standard calling sequence for reading the observing log data files
for all instruments is:
%
\idlinputa{rd\_obs, '8-may-92', '8-may-92 12:00', bcs, sxtf, sxtp, w\_h, fid}\index{RD\_OBS}
%
It is possible to only read SXT full-frame data by using the one of the 
following command:
%
\idlinputa{rd\_obs, '8-may-92', '8-may-92 12:00', bcs, sxtf, sxtp, w\_h, fid, /sxtf}	
\idlinputb{rd\_obs, '8-may-92', '8-may-92 12:00', bcs, sxtf, /sxtf}	
\idlinputb{rd\_obs, '8-may-92', '8-may-92 12:00', bcs, sxtf, /nobcs}
%
To read the WBS data, you can use the command:
%
\idlinputa{rd\_obs, '8-may-92', '8-may-92 12:00', bcs, sxtf, sxtp, w\_h, /w\_h}
%
The observing log output structures are positional and are sorted 
alphabetically.  The observing log files must be in the \$DIR\_GEN\_OBD, 
\$DIR\_GEN\_OSF, \$DIR\_GEN\_OSP, and \$DIR\_GEN\_OWH directories
appropriately.


\subsection{Reading Exabyte Archive Tapes}

See the description of GO\_RDTAP in the User's Guide and the description of
RDTAP on page~\pageref{rdtap} in the appendix of the Reference Guide. \index{GO\_RDTAP}

