\magnification=1200
\tolerance=400
\input smmrept_mac.macro
\input table.macro
%
\pageno=-1				% Negative to have roman numerals
\centerline{\bigbold SMM X-RAY POLYCHROMATOR} \bigskip\bigskip
\centerline{\bigbold SOFTWARE USER'S GUIDE} \smallskip
\vfill
\centerline{October 1993} \smallskip
\centerline{(Version 2.0)}

\vfill
\centerline{Prepared for}\smallskip
\centerline{Goddard Space Flight Center}\smallskip
\centerline{Solar Data Analysis Center} \smallskip
\centerline{Contract NAS5-31235}
\vfill
\centerline{by}
\vfill
\centerline{Dr.~Dominic~M.~Zarro}
\medskip
\centerline{Applied Research Corporation}
\centerline{8201 Corporate Drive}
\centerline{Landover, MD~~20785}

\bigskip \bigskip
\centerline{Dr.~Julia~L.~R.~Saba}
\medskip
\centerline{Lockheed Solar \& Astrophyics Laboratory}
\centerline{O/91-30, Bldg. 252, 3251 Hanover Street}
\centerline{Palo Alto, CA~~94304}

\bigskip 
\centerline{and}
\bigskip

\centerline{Dr.~Michael~McSherry}
\medskip
\centerline{University of Belfast}
\centerline{Ireland}

\vfill
\eject

\centerline{\bigbold TABLE OF CONTENTS}\bigskip

\bigskip\leftline{\bf 1. OVERVIEW}\smallskip
\toc{1.1} {Introduction                         }{1--1\@}
\toc{1.2} {Description of the XRP Instrument    }{1--1\@}
\toc{1.2.1} {The BCS Instrument                 }{1--2\@}
\toc{1.2.2} {The FCS Instrument                 }{1--2\@}
\toc{1.3} {Summary of XRP Data and Software }   {1--4\@}
\toc{1.4} {Getting Started                      }{1--5\@}
\toc{1.4.1} {REFORMAT                           }{1--7\@}

\bigskip\leftline{\bf 2. FORTRAN DATA REDUCTION PROGRAMS}\smallskip
\toc{2.1}{BCS Programs                         }{2--1\@}
\toc{2.1.1 }{BOTON                             }{2--1\@}
\toc{2.1.2 }{MKBRR                             }{2--1\@}
\toc{2.1.3 }{LISTBRR                           }{2--2\@}
\toc{2.1.4 }{CALBRR                            }{2--4\@}
\toc{2.1.5 }{SPCFIT                            }{2--5\@}
\toc{2.1.6 }{BCSPRO                            }{2--6\@}
\toc{2.2}   {FCS Programs                      }{2--7\@}
\toc{2.2.1 }{FOTON                             }{2--7\@}
\toc{2.2.2 }{MKFIS                             }{2--7\@}
\toc{2.2.3 }{LISTFIS                           }{2--8\@}

\bigskip\leftline{\bf 3. IDL DATA ANALYSIS PROGRAMS}\smallskip

\toc{3.1 }  {BCS Programs                      }{3--1\@}
\toc{3.1.1 }{PLOTBDA                           }{3--1\@}
\toc{3.1.2 }{PLOTBRR                           }{3--2\@}
\toc{3.1.3 }{PLOTFIT                           }{3--3\@}
\toc{3.2}   {FCS Programs                      }{3--3\@}
\toc{3.2.1 }{PLOTFIS                           }{3--3\@}
\toc{3.2.2 }{RDFIS                             }{3--5\@}
\toc{3.2.3 }{RUST                              }{3--6\@}
\toc{3.2.4 }{FLUXCAL                           }{3--7\@}
\toc{3.2.5 }{FTEMAP                            }{3--9\@}
\toc{3.2.6 }{PLOTFTE                           }{3--11}
\toc{3.2.7 }{TEMCAL                            }{3--11}

\bigskip\leftline{\bf 4. IDL/WIDGET PROGRAMS}\smallskip

\toc{4.1 } {BCS                                }{4--1\@}
\toc{4.2 } {FCS                                }{4--3\@}
\toc{4.3 } {LISTBCS                            }{4--4\@}
\vfill\eject

\chapter{1}{OVERVIEW}

\section{1.1 INTRODUCTION}

This manual describes the programs that are available for the reduction,
display, and analysis of soft X-ray imaging and spectral observations obtained
with the X-ray Polychromator (XRP) instrument on the Solar Maximum Mission
(SMM).  The XRP programs are written in Fortran and Interactive Data Language
and are tailored for a VAX/VMS operating system.  The Fortran programs are
used primarily for copying raw data from tape to magnetic disk, applying
first order corrections to the data (e.g.,  background subtraction,
sensitivity corrections), and listing the contents of particular data
files. The IDL programs are used primarily for reading and plotting
spectra, images, and lightcurves from selected data files. The software is 
available online at the Solar Data Analysis Center (SDAC) (NASA/GSFC,
Greenbelt, MD) and can be accessed as discussed in Appendix A. 

This manual is divided into four chapters. Chapter 1 gives a brief overview of
the XRP instrument, a description of the associated data files that are created
during various stages of the data reduction and analysis (Table 1-3), a summary
listing of the available programs in alphabetical order (Table 1-4), a
flowchart relating the data files and their associated programs (Figure 1-1)
and a summary guide to the programs ordered by task (Table 1-5). 
It also describes the REFORMAT procedure which is the necessary first step in
copying XRP data from Exabyte tape to disk. Chapters 2 and 3 give detailed
descriptions of the Fortran and IDL programs, respectively, concentrating on
their usage and their limitations. Chapter 4 describes the newly developed
IDL/widget programs that provide a graphical user interface to the XRP
software. Further information about the XRP software can be obtained by
contacting the SDAC staff (see Appendix A).

\section{1.2 DESCRIPTION OF THE XRP INSTRUMENT}

The primary objective of the SMM-XRP was the study of the physical conditions
in the corona for a variety of solar phenomena. This was achieved through the
use of two complementary instruments: the Bent Crystal Spectrometer (BCS) and
the Flat Crystal Spectrometer (FCS). The XRP acquired data during the peak of
solar cycle 21 (February to November 1980), during its decline (following the
in-orbit repair of SMM in April 1984), and through the rise phase of cycle 22
(until October 1989). 

\subsection{1.2.1 The BCS Instrument}

The BCS was designed to observe the spatially integrated fluxes in eight
high-temperature soft x-ray emission lines produced by solar flare plasma. The
primary goals of the BCS were:

\item{ $\bullet$ } to study flare dynamics using line shift and broadening
measurements; 

\item{ $\bullet$ } to measure temperature, emission measure, abundances,
and equilibrium states to characterize the physical conditions in the flare
plasma. 

The characteristics of the BCS are listed in Table 1-1.  The BCS had eight bent
Bragg crystal spectrometers with position-sensitive detectors. It was
collimated to 6 arcmin FWHM and was capable of changing its time resolution
from 11~s to 0.5~s or less by using dynamic memory and sacrificing spectral
coverage or resolution. The BCS was sensitive to the  high-temperature ($T_e$
$>$ 10 MK) component of the flare plasma. Most of the BCS data were taken in
the standard flare mode, which recorded spectra every 11 or 7.6~s (depending on
the number of operational channels) until a specified threshold was reached. In
flare mode, the integration time decreased to 3.6~s.  After 1980, BCS channels
2 and 8 no longer functioned. Most of the BCS analysis software has been
written for Channels 1 (the Ca XIX channel) and 4 (the low-resolution Fe XXV
channel). 


\goodbreak
\midinsert
\settabs 5\columns
\centerline{\bf Table 1-1. BCS Characteristics}
\medskip
\vskip 0.1truecm\hrule\vskip 0.1truecm
\+\quad Channel\hfill&\hfill Ion Stage\hfill&\hfill Wavelength\hfill
 &\hfill Peak T$_e$\hfill&\hfill Resolution\hfill&\cr
\+&\hfill Number\hfill&\hfill (\AA)\hfill&
 \hfill ($10^6$ K)\hfill&\hfill $\lambda/\delta\lambda$\hfill&\cr
\vskip 0.1truecm\hrule\vskip 0.1truecm
\+\quad 1\hfill&\hskip 0.5cm Ca XIX&\hfill 3.165 -- 3.231\hfill
 &\hfill 35\hfill&\hfill \ 3463\hfill&\cr
\+\quad 2*\hfill&\hskip 0.5cm Fe$^{inner}_{shell}$\hfill&\hfill 1.928 
 -- 1.945\hfill
 &\hfill \ 2\hfill&\hfill 11206\hfill&\cr
\+\quad 3\hfill&\hskip 0.5cm Fe$^{inner}_{shell}$\hfill&\hfill 
 1.839 -- 1.947\hfill
 &\hfill \ 2\hfill&\hfill \ 4075\hfill&\cr
\+\quad 4\hfill&\hskip 0.5cm Fe XXV\hfill&\hfill 1.840 -- 1.984\hfill
 &\hfill 50\hfill&\hfill \ 3967\hfill&\cr
\+\quad 5\hfill&\hskip 0.5cm Fe XXV\hfill&\hfill 1.866 -- 1.879\hfill
 &\hfill 50\hfill&\hfill \ 8937\hfill&\cr
\+\quad 6\hfill&\hskip 0.5cm Fe XXV\hfill&\hfill 1.854 -- 1.867\hfill
 &\hfill 50\hfill&\hfill \ 8937\hfill&\cr
\+\quad 7\hfill&\hskip 0.5cm Fe XXV\hfill&\hfill 1.842 -- 1.855\hfill
 &\hfill 50\hfill&\hfill \ 8911\hfill&\cr
\+\quad 8*\hfill&\hskip 0.5cm Fe XXVI\hfill&\hfill 1.769 -- 1.796\hfill
 &\hfill 60\hfill&\hfill \ 7005\hfill&\cr
\vskip 0.1truecm\hrule\vskip 0.1truecm
\+\quad * Channel has data for 1980 only \cr
\smallskip
\endinsert

\subsection{1.2.2 The FCS Instrument}

The FCS was designed to:

\item{ $\bullet$ } image soft X-rays emitted over a wide range of 
coronal temperatures (from 2-70~MK) to determine the structure and
evolution of flares and active regions; 

\item{ $\bullet$ } obtain high resolution spectra from 1.5-23~\AA\/ to
determine plasma temperatures, emission measure, density, abundances, and
dynamics; 

\item{ $\bullet$ } monitor the evolution of soft X-ray fluxes 
with up to 0.256~s time resolution.

The FCS characteristics are listed in Table 1-2. The FCS was a seven-channel
Bragg crystal spectrometer built on a raster mechanism. The FCS contained an
optical sensor in channel 8 (with a small known offset from the X-ray
detectors) which could be used for image  coregistration. The FCS isolated
specific areas in the corona for study through its narrow collimation 
(12-16~arcsec FWHM response, depending on the detector),  producing modest
spatial resolution images or well-resolved X-ray spectra. At the ``home
position'' (HP) of the wavelength drive, each X-ray channel could monitor the
emission from a prominent soft X-ray line. By scanning its wavelength drive,
the FCS could access an even wider range of soft X-ray lines. The FCS could
image an area up to 7 arcmin square in up to six bright spectral lines
simultaneously, make rapid scans over a wide wavelength range or at high
resolution across individual line complexes, or combine the two modes to make
spectroscopic observations over a predetermined area. 

About 400 FCS observations using the wavelength drive (``crystal runs'') were
executed during the mission. These included scans of individual profiles at one
or more spatial locations, taking 10-30~s each; scans of line complexes (such
as density-diagnostic triplets), taking 1-2~mins; and long spectral
scans of all the accessible wavebands, taking 10-20~mins. Several
sequences combined images in bright lines at several wavelength drive positions
with scans of the corresponding line profiles at the brightest pixel. Some of
the FCS sequences (designed to study active regions or quiescent solar
structures) were run in a ``standalone mode''. Most of the remaining sequences
(designed to study flares) were triggered by a flare flag from the BCS. 

\goodbreak
\midinsert
\settabs 7\columns
\centerline{\bf Table 1-2. FCS Characteristics}
\medskip
\vskip 0.1truecm\hrule\vskip 0.1truecm
\+\hfill HP Ion\hfill&\hfill Wavelength\hfill&\hfill Peak T$_e$\hfill
 &Crystal\hfill&\hfill Scan Extent\hfill&\hfill Resolution\hfill
 &\hfill FOV\hfill&\cr
\+\hfill Stage\hfill&\hfill (\AA)\hfill&\hfill ($10^6$ K)\hfill
 &&\hfill (\AA)\hfill&\hfill ($\lambda/\delta\lambda$)\hfill
 &\hfill (arcsec)\hfill&\cr
\vskip 0.1truecm\hrule\vskip 0.1truecm
\+\hskip 0.5cm O VIII\hfill&\hfill 18.969\hfill&\hfill \ 3\hfill
 &KAP&\hfill 13.1 -- 22.4\hfill&\hfill \ \ 997\hfill&\hfill 
 16\hfill&\cr
\+\hskip 0.5cm Ne IX* \hfill&\hfill 13.447\hfill&\hfill \ 4\hfill
 &Beryl&\hfill 10.5 -- 14.9\hfill&\hfill \ 2300\hfill&\hfill 
 15\hfill&\cr
\+\hskip 0.5cm Mg XI\hfill&\hfill \ 9.169\hfill&\hfill \ 6\hfill
 &ADP&\hfill \ 7.3 -- 10.1\hfill&\hfill \ 8140\hfill&\hfill 
 14\hfill&\cr
\+\hskip 0.5cm Si XIII\hfill&\hfill \ 6.649\hfill&\hfill 10\hfill
 &Quartz&\hfill \ 4.9 -- \ 7.6\hfill&\hfill \ 5500\hfill&\hfill 
 14\hfill&\cr
\+\hskip 0.5cm S XV\hfill&\hfill \ 5.039\hfill&\hfill  16\hfill
 &Quartz&\hfill \ 3.6 -- \ 5.8\hfill&\hfill 10300\hfill&\hfill 
 13\hfill&\cr
\+\hskip 0.5cm Ca XIX** \hfill&\hfill \ 3.173\hfill&\hfill 35\hfill
 &Ge&\hfill \ 2.3 -- \ 3.6\hfill&\hfill \ 5170\hfill&\hfill 
 14\hfill&\cr
\+\hskip 0.5cm Fe XXV\hfill&\hfill \ 1.850\hfill&\hfill 50\hfill
 &Ge&\hfill \ 1.4 -- \ 2.1\hfill&\hfill 25100\hfill&\hfill 
 14\hfill&\cr
\vskip 0.1truecm\hrule\vskip 0.1truecm
\+&\quad * Channel not operational after February 1985\cr
\+&\quad ** Channel not operational after 1980\cr
\smallskip
\endinsert

FCS Channel 6 (Ca XIX) was misaligned with respect to the other detectors, so
that Ca XIX was offset from HP. After 1980, this channel no longer functioned.
After February 1985, engineering data was output into the telemetry 
for Channel 6. In early 1985, FCS Channel 2 (Ne~IX) was lost, so that coverage 
of the Ne~IX complex was available only at the short wavelength end of Channel
1. Soon thereafter, the Channel 2 telemetry was replaced with telemetry from
the FCS optical sensor \# 8 to allow higher spatial sampling of its output. By
1987, the remaining FCS thin-window detectors (Channels 1, 3, and 4) began to
run out of gas, so that they were used only intermittently in a ``campaign
mode''.  By May 1989, only the high-energy FCS channels remained, so that the
FCS became restricted to flare studies. After December 1987, the wavelength
drive experienced increasing problems. No FCS spectroscopic sequences were run
successfully after April 1988. 

For further details of the XRP instrument design and operational capabilities,
see Acton et al., Solar Physics, 65, 53-71, 1980. Instrumental considerations
such as calibration, sensitivity, alignment, fluorescence, and background are 
discussed by Bentley (Ph.D. thesis, Department of Physics and Astronomy,
University College London, 1986). 

\section{1.3 SUMMARY OF XRP DATA AND SOFTWARE}

Table 1-3 summarizes the different file types that are associated with the
reduction and analysis of XRP data. These files contain data ranging from
raw detector count rates, to processed images and spectra, to physical
parameters such as plasma temperature and emission measure. Table 1-4 gives an
alphabetical listing of the programs that operate on and produce these files. 

The BCSDA, BCSIX, FCSDA, FCSIX, ENG, and SPSUB files are  referred to as
reformatted files and are created by the REFORMAT program (\S~1.4), which
copies XRP data from Exabyte tape to disk. The files contain the raw data
(count rates) and associated detector and spacecraft attitude information 
for the two XRP instruments. These files are considered {\it old format}
files in the sense that the software to read them is no longer supported.
The naming convention of these files is BCSDAhhmm.doy, FCSDAhhmm.doy, etc.,
where: 

\verbatim

     hh  - start hour of data
     mm  - start minute of data (approx)
     doy - day of year of data

\endverbatim   

The BDA and FDA files are considered {\it new format} files and are created by
the programs BOTON (\S~2.1.1) and FOTON (\S~2.2.1), respectively. The naming
convention of these files is BDAyymm.hhmm and FDAyymmdd.hhmm where:

\verbatim 

     yy  - year of data
     mm  - month of data
     dd  - day of data 
     hh  - start hour of data 
     mm  - start minute of data (approx)

\endverbatim  

\goodbreak \topinsert
\centerline{\bf Table 1-3. XRP Data Files}
\bigskip
\begintable

{\bf DATA FILE} \vt {\bf DESCRIPTION} \eltt

{\bf BCSDA} \hfill | Raw data count rates for the eight BCS channels. \hfill \el

{\bf BCSIX} \hfill | Index file providing pointers to the data in the BCSDA file. \hfill \el

{\bf BDA}   \hfill | The BCSDA and BCSIX files combined. \hfill \el

{\bf BRR}   \hfill | Keyed-access file (VMS only) containing BCS spectra \hfill \el
      \hfill | that were selectively extracted from BDA files. \hfill  \el

{\bf FCSDA} \hfill | Raw data count rates for the eight FCS channels. \hfill \el

{\bf FCSIX} \hfill | Index file providing pointers to the data in the FCSDA file. \hfill\el

{\bf FDA}   \hfill | The FCSDA and FCSIX files combined. \hfill \el


{\bf FIS}   \hfill | Unformatted file containing image and/or spectra extracted \hfill \el
            \hfill | from FDA files. \hfill \el

{\bf FIT}   \hfill | ASCII file containing various physical parameters \hfill \el
      \hfill |(e.g., $T_e$, $EM$, $v_{turb}$) derived from fits to BRR spectra. \hfill\el 

{\bf FTE}   \hfill | IDL XDR saveset containing maps of flux, temperature, and \hfill \el
            \hfill | emission measure for selected images from FIS files. \hfill\el
            
{\bf ENG}   \hfill | Engineering file containing detector information needed for\hfill\el
            \hfill | analysis (e.g., FCS crystal address, detector status). \hfill\el

{\bf SPC}   \hfill | Keyed-access file consisting of model calcium and iron 
line \hfill \el 
            \hfill | spectra fitted to selected spectra from BRR
files.\hfill\el 

{\bf SPSUB} \hfill | Pointing file containing SMM spacecraft attitude
information.  \hfill 
\endtable


\endinsert

The BRR and FIS files are processed files that contain selected spectra (BRR) 
or images and spectra (FIS). These files are created from the BDA and FDA
files by the MKBRR (\S~2.1.2)  and MKFIS (\S~2.2.2) programs, respectively.
The bulk of the IDL software described in this manual operates on these
files. The FTE, SPC, and FIT files are summary files that contain physical
parameters (such as temperature and emission measure) that have been
derived from the FIS and BRR files. Figure 1-1 presents a flowchart of the
relationship between these files and their associated programs. 

\section{1.4 GETTING STARTED}

The first step in analyzing XRP observations is to read the raw data stored on
Exabyte tapes at the SDAC. There are 79 tapes each containing a month of data,
with each day saved as a separate file on the tape. The REFORMAT procedure 
(\S~1.4.1) is used to read and copy specific data sets from these tapes to
magnetic disk. Because the REFORMAT procedure can be extremely slow, it is
recommended that you first examine the XRP data that has already been processed
and archived in the Selected Data Archive (SDA) which resides on disk at the 
SDAC.

The SDA contains FIS and BDA files for approximately 400 FCS spectroscopic
observations and over 700 BCS observations for which the count rate in the
Ca~XIX channel exceeded a threshold of 250 counts/sec (equivalent to a GOES
mid-class C event, a few times $10^{-6}$ W m$^{-2}$).  There is a good chance
that FIS and BDA files pertaining to a strong flare (above C level) or to a
crystal scan will be in the SDA. 

To see whether processed XRP data already exist for a given date and start time
(encoded into the file name as discussed in \S~1.3), you can search the SDA
by using the VMS logicals (or UNIX environment variables) BCS\_DATA and
FCS\_DATA, as discussed in Appendix A, or by using the IDL/widget programs 
BCS and FCS, as discussed in Chapter 4. If the relevant files exist, then you
can skip the REFORMAT procedure and go directly to creating BRR files 
(\S~2.1.2). 


\goodbreak \topinsert
\centerline{\bf Table 1-4. XRP Programs}
\bigskip
\begintable

{\bf PROGRAM} \vt {\bf DESCRIPTION} \eltt

{\bf BCS} \hfill | A widget interface to BCS data and software. \hfill\el

{\bf BCSPRO} \hfill | Creates a command file to execute MKBRR + CALBRR + SPCFIT \hfill\el
{\bf BOTON} \hfill | Creates BDA files from BCSDA and BCSIX files. \hfill\el

{\bf CALBRR} \hfill| Wavelength calibrates channel 1 and 4 spectra in BRR 
files. \hfill\el

{\bf FCS} \hfill | A widget interface to FCS data and software. \hfill\el

{\bf FLUXCAL } \hfill | Flux calibrates FCS detector count rates.\hfill\el

 {\bf FOTON } \hfill | Creates FDA files from FCSDA and FCSIX files.\hfill\el

 {\bf FTEMAP } \hfill | Computes flux, temperature, and emission measure maps 
from FCS \hfill\el 
                      | line ratios maps and creates FTE files.\hfill\el

 {\bf LISTBRR } \hfill | Lists the contents of a BRR file.\hfill\el

{\bf LISTBCS} \hfill  | Lists the flares in the BCS event catalog. \hfill\el

 {\bf LISTFIS } \hfill | Lists the contents of a FIS file.\hfill\el

 {\bf MKBRR } \hfill | Creates BRR files from BDA files.\hfill\el

 {\bf MKFIS } \hfill | Creates FIS files from FDA files.\hfill\el

 {\bf PLOTBDA} \hfill | Plots spectra and lightcurves from BDA files.\hfill\el

 {\bf PLOTBRR } \hfill | Plots spectra and lightcurves from BRR files.\hfill\el

 {\bf PLOTFIS } \hfill | Plots images and spectra from FIS files.\hfill\el

 {\bf PLOTFIT } \hfill | Plots theoretical profiles and fitted parameters from SPC and FIT files.\hfill\el

 {\bf PLOTFTE} \hfill | Plots temperature and emission measure maps saved in 
FTE saveset \hfill\el
                      | files created by FTEMAP. \hfill \el

 {\bf RDFIS } \hfill | Extracts an image from a FIS file and returns it in a structure variable.\hfill\el

 {\bf RUST } \hfill | Reads and unpacks the image structure created by RDFIS.\hfill\el

 {\bf SPCFIT } \hfill | Fits theoretical profiles to channel 1 and 4 spectra 
in BRR files and  \hfill\el
                      | creates SPC and FIT files.\hfill\el

 {\bf TEMCAL } \hfill | Computes temperature and emission measure from FCS
count rate \hfill\el
                      | measurements.\hfill\endtable

\endinsert

\subsection{1.4.1 REFORMAT}

REFORMAT is an IDL procedure that invokes a command procedure to perform the 
copying and reformatting of FCS and BCS data from Exabyte tape to magnetic
disk. To run this procedure type: 

\verbatim
  IDL> REFORMAT
\endverbatim

\noindent

\noindent You will be prompted for a number of responses. (When available,
default choices given between square brackets are selected by hitting return.) 

First you will be asked if you require both FCS and BCS data:

\verbatim
  * do you require FCS data [def=y]?
  * do you require BCS data [def=y]?
\endverbatim

\noindent Then you must load the Exabyte tape corresponding to the month
containing the required data. You will be asked to enter the number
corresponding to the tape drive in which the Exabyte is loaded: 

\verbatim 
  * load tape and enter corresponding drive number from above (q to quit): 0
\endverbatim

\noindent Then you will be asked to enter start and stop times in the format
specified below. If the start and stop times have the same month and day,
the information on year, month, and day need not be repeated, as shown in
the example: 

\verbatim
  * enter start time to extract [yy/mm/dd, hhmm:ss.msec] 85/01/01, 0100
  * enter end time to extract [yy/mm/dd, hhmm:ss.msec] 0200
\endverbatim

\noindent The total time for a given interval must be less than two hours.
Longer times must be broken into subintervals which are reformatted one at
a time. 

You will be given status messages as blocks are copied, and asked at the
end whether you want to keep the old format files FCSDA, FCSIX, BCSDA,
BCSIX, ENG, and SPSUB, for which the default response is "n". (Answer "y" if
you require FCS Sit \& Stare data.) Recall that old format files have a
different convention than new format files for designating the time
incorporated into the filename, as discussed in \S~1.3. 


\goodbreak \topinsert
\centerline{\bf Table 1-5. XRP Analysis Quick Start}
\bigskip
\begintable

{\bf GOAL} \vt {\bf METHOD} \eltt

Instrument overview \hfill | See \S~1.2 (XRP), \S~1.2.1 (BCS), and \S~1.2.2
(FCS). \hfill \el 

\hfill | \hfill \el

Data file overview \hfill | See \S~1.3 and Table 1-3. \hfill \el

\hfill | \hfill \el

To access data	\hfill | For flares or FCS spectral scans, first check Selected
\hfill \el			
\hfill | Data Archive (SDA) to see if data online: \hfill \el
\hfill | use BCS\_DATA and FCS\_DATA (see Appendix A) \hfill \el
\hfill | or IDL/widgets BCS and FCS (\S\S~4.1 and 4.2) \hfill \el
\hfill | \hfill \el

\hfill | If data not in SDA, use IDL$>$ REFORMAT (\S~1.4.1) \hfill \el
\hfill | on Exabyte tape(s) to get BCS spectral (BDA) files    \hfill \el
\hfill | and FCS image and spectral (FIS) files. \hfill \el

\hfill | \hfill \el

To examine BCS \hfill | Use widget interface IDL$>$ LISTBCS (\S~4.3) \hfill \el
flare catalog  \hfill | \hfill \el

\hfill | \hfill \el

To convert old format \hfill | Use BOTON (\S~2.1.1) on BCSDA + BCSIX to make BDA
\hfill \el
file to new format \hfill | file; use FOTON (\S~2.2.1) on FCSDA + FCSIX + ENG 
\hfill \el
\hfill |	to make FDA file. \hfill \el

\hfill | \hfill \el

To reduce BCS \hfill | 	Use MKBRR (\S~2.1.2 and Table 2-1) on BDA files 
\hfill \el
spectral data \hfill |	to create BRR files of selected spectra, corrected for 
\hfill \el
\hfill | crystal curvature, for desired integration times. Then \hfill \el
\hfill | use CALBRR (\S~2.1.4) to wavelength calibrate spectra. \hfill \el

\hfill | \hfill \el

\hfill | Alternatively, use BCSPRO (\S~2.1.6) to run \hfill \el
\hfill | MKBRR and CALBRR as batch job. \hfill \el

\hfill | \hfill \el

To reduce FCS image \hfill | Use MKFIS (\S~2.2.2) to extract images and 
spectra \hfill \el
and spectral data \hfill | from FDA file into FIS file. (Also done 
automatically \hfill \el
\hfill | in REFORMAT process (\S~1.4.1). \hfill \el

\hfill | \hfill \el

\endtable
\endinsert

\vfill \eject

\goodbreak \topinsert
\centerline{\bf Table 1-5. XRP Analysis Quick Start}
\bigskip
\begintable

{\bf GOAL} \vt {\bf METHOD} \eltt

To create FCS \hfill | Use RDFIS (\S~3.2.2) to read images from FIS files
\hfill \el 
image structure \hfill | and create data structure variable for other
programs. \hfill \el 

\hfill | \hfill \el

To read FCS \hfill | Use RUST (\S~3.2.3) to read and unpack image data
\hfill \el 
image structure \hfill | structure created by RDFIS for other programs. \hfill 
\el

\hfill | \hfill \el

To list contents \hfill | Use LISTBRR (\S~2.1.3) to list BCS spectra in BRR
file; \hfill \el
of data files \hfill | use LISTFIS (\S~2.2.3) to list FCS modes, crystal
address, \hfill \el 
\hfill | spacecraft pointing, etc. in FIS file. \hfill \el

\hfill | \hfill \el

To plot BCS spectra \hfill | Use IDL$>$ PLOTBDA (\S~3.1.1) on BDA files,
\hfill \el
and lightcurves \hfill | or use IDL$>$ PLOTBRR (\S~3.1.2) on BRR files,
\hfill \el
\hfill | or use widget interface IDL$>$ BCS (\S~4.1). \hfill \el

\hfill | \hfill \el

To fit BCS spectra \hfill | Use SPCFIT (\S~2.1.5) on BRR files, or use
\hfill \el
\hfill | BCSPRO (= MKBRR + CALBRR + SPCFIT) on BDA files \hfill \el
\hfill | (\S\S~2.1.2 to 2.1.6). \hfill \el

\hfill | \hfill \el

To plot BCS fits or \hfill | Use PLOTFIT (\S~3.1.3) to plot results of BCS
\hfill \el 
time histories of \hfill | spectral analysis by SPCFIT. \hfill \el
plasma parameters   \hfill | \hfill \el

\hfill | \hfill \el

To plot FCS images \hfill | Use IDL$>$ PLOTFIS (\S~3.2.1) on FIS files,
\hfill \el 
and spectra \hfill | or use widget interface IDL$>$ FCS (section 4.2).
\hfill \el 

\hfill | \hfill \el

To get FCS fluxes \hfill | Use IDL$>$ FLUXCAL (\S~3.2.4) to convert FCS count \hfill \el
\hfill | rates to photon flux. \hfill \el

\hfill | \hfill \el

To get temperature \hfill | Use IDL$>$ TEMCAL (\S~3.2.7). \hfill \el
and emission measure \hfill | \hfill \el
from FCS line ratios \hfill | \hfill \el

\hfill | \hfill
\endtable
\endinsert

\vfill \eject

\goodbreak \topinsert
\centerline{\bf Table 1-5. XRP Analysis Quick Start}
\bigskip
\begintable

{\bf GOAL} \vt {\bf METHOD} \eltt

To get fluxes and \hfill | Use IDL$>$ FTEMAP (\S~3.2.5) on FIS file. \hfill \el
physical parameters \hfill | \hfill \el
from FCS maps \hfill | \hfill \el

\hfill | \hfill \el

To plot fluxes and \hfill | Use IDL$>$ PLOTFTE (\S~3.2.6) with FTE IDL save
\hfill \el 
physical parameters \hfill | files created by FTEMAP. \hfill \el
from FCS maps \hfill | \hfill \el

\hfill | \hfill

\endtable

\endinsert

\indent

\vfill 
\eject

\chapter{2}{FORTRAN DATA REDUCTION PROGRAMS}

This chapter describes the XRP fortran programs that were listed in Table 1-4.
The programs are described in the chronological order in which they are likely
to be used. The fortran programs are used primarily for the conversion of one
file type to another, or for the extraction of selected data products from
files. In general, they are executed by typing a DCL symbol that is defined in
the LOGIN.COM file for the XRP account.

\section{2.1 BCS PROGRAMS}

\subsection{2.1.1 BOTON}

BOTON creates a BDA file from BCSDA and BCSIX files. Although BOTON is run
automatically during the REFORMAT procedure, it can be executed manually by
typing: 

\verbatim

  $ BOTON filid

\endverbatim

\noindent where 'filid' is the hhmm.doy extension of the BCSDA and BCSIX files
produced by REFORMAT. If the reformatted files are not in the current
directory, then the full directory and filename must be entered on the command
line. BOTON will prompt for these inputs if 'filid' is not entered. Note that
the BDA file id is different from that of the BCSDA file. The BDA file contains
spectra (at the original observed time resolution) for all the available BCS
channels. These spectra can be examined with the IDL program PLOTBDA (\S~3.1.1)

\subsection{2.1.2 MKBRR}

MKBRR creates BRR files from BDA files.  The BRR files are
keyed-access ISAM files that contain selected spectra that have been
accumulated  for a specified time and corrected for crystal curvature effects. 
These files are the starting point for the derivation of flare parameters
(temperature, emission measure, velocity) from the BCS spectral data.

MKBRR can be run interactively or by using command line switches. To run
interactively, type:

\verbatim

  $ MKBRR

\endverbatim

\noindent The following prompts will appear:

\verbatim

  * Enter BDA File id or name [yymmdd.hhmm]

     In default mode :,
	-  Channels 1 & 4 are processed,
	-  20 sec is assumed for data gathering interval,
	-  Crystal curvature corrections applied.

  * Use default mode ? [def=y]

\endverbatim

\noindent Answering YES (after entering the file name) will invoke the default
mode.
In this mode, MKBRR extracts spectra for channels 1 (Ca~XVIII-XIX) and 4 
(Fe~XXII-XXV), and accumulates the data into approximately 20~s intervals.
Curvature corrections are also applied. These corrections essentially
straighten the spectra, and have been calibrated only for channels 1 and 4.
Answering NO  will allow you to override these defaults.

The non-interactive mode allows more control over the BRR output file.
There are six switches available, which may be included in any order.
An example of their usage is as follows:

\verbatim

  $ MKBRR /fil:800629.1810/chn:1/int:15/sta:18,25/end:18,30/cnt:4000,1

\endverbatim

\noindent

In this example, channel~1 Ca~XIX  data in the BDA file with file id
800629.1810 will be accumulated into  15~s (or greater)  intervals starting at
1825~UT and ending at 1830~UT. The accumulation interval for each spectrum 
will be increased until a 4000 total count level is reached in channel 1.  The
spectra within the BRR file can be examined by using the IDL program PLOTBRR
(\S~3.1.2).
In practice, you would use MKBRR to extract BCS channels 1 and/or 4 only.
The remaining fortran BCS analysis programs that are described in this section 
do not operate on any of the other channels.

\goodbreak \topinsert
\centerline{\bf Table 2-1. MKBRR Switches}
\bigskip
\begintable

{\bf SWITCH} \vt {\bf DESCRIPTION} \eltt

{\bf /fil:} \hfill 
       | This switch specifies the file id of the BDA file. If present, \hfill\el
       | then MKBRR will ask no questions (appropriate for running in \hfill\el
       | batch mode) and, by default, the crystal curvature corrections \hfill\el
       | will be applied. If not present, then the /chn:, /int:, /sta:, and \hfill\el
       | /end: switches will be ignored. \hfill\el
       |  \el

{\bf /chn:} \hfill 
       | Specifies which channel to process. If absent, then MKBRR extracts\hfill\el
       | channel 1 and 4 data. Can also specify multiple channels as /chn:1,4  \hfill\el
       | (no blanks). This switch is ignored if the /fil: switch is absent. \hfill\el
       | \el

{\bf /int:} \hfill  
       | Integration time (integer) in secs.  The default is to accumulate  \hfill\el
       | spectra with 20~s time resolution. This switch is ignored if the \hfill\el
       | /fil: switch is absent. \hfill\el
       | \el

{\bf /cnt:} \hfill
       | Sets the (total) count level (integer) which must be accumulated.  \hfill\el
       | The integration time will be the minimum specified with the /int: \hfill\el
       | switch.  If the specified count rate is not detected, then the integration \hfill\el
       | time is increased until the desired count rate is reached.  The format \hfill\el
       | is /cnt:level,chan such as /cnt:1000,1 (no blanks allowed). If the \hfill\el
       | channel number is omitted, then the lowest selected channel is used.\hfill\el
       | If the /cnt: switch is supplied, then /int:0 will be used. In this case,  \hfill\el
       | the shortest integration time which supplies the desired total count rate \hfill\el
       | in the specified channel will be used.  If multiple channels are \hfill\el
       | selected, then the same integration time will be used for the other \hfill\el
       | channels. This switch is ignored if the /fil: switch is absent. \hfill\el
       |  \el          

{\bf /sta:} \hfill
       | The start time in hh,mm,ss,dd,mm,yy format, (from minutes onward \hfill\el
       | the quantities are optional). The omission of this switch will cause  \hfill\el
       | MKBRR to begin with the earliest available data. \hfill\el
       | \el 
         
{\bf /end:} \hfill
       | The end time in hh,mm,ss,dd,mm,yy format. The omission of this \hfill\el 
       | switch will cause MKBRR to process until the end of the BDA file.  \hfill\el
       | \endtable        

\endinsert


\subsection{2.1.3 LISTBRR}

LISTBRR lists contents of a BRR file. It is executed by typing:

\verbatim

  $ LISTBRR filid                      

\endverbatim

\noindent where 'filid' is the BRR file id (which is inherited from the
original BDA file). A sample listing is as follows:

\verbatim

 Summary of BRR file: SYS$DATA:[XRP.DATA]BRR850123.0657;12              

 Total number of spectra:  292   146   0   0 146   0   0   0   0

 Chan      Mean time          sdgi    num     dw        w0     rate Corrected

   1    7 26 28  23  1 85    65.280     5  3.02E-04  3.24E+00    64    1 1
   1    7 27 15  23  1 85    30.720     7  3.11E-04  3.24E+00   141    1 1
   1    7 27 45  23  1 85    19.200     9  3.01E-04  3.24E+00   221    1 1
   1    7 28  9  23  1 85    15.360    11  3.02E-04  3.24E+00   279    1 1

\endverbatim


\noindent Such a listing will appear for each channel processed by MKBRR.
The listed parameters have the following definitions:

\item{} {\bf chan} -- the channel number.

\item{} {\bf mean time} -- the mean time of the accumulated interval.

\item{} {\bf sdgi} -- the actual accumulation time of the spectrum.

\item{} {\bf num} -- the spectrum number.

\item{} {\bf dw} -- the nominal wavelength dispersion (\AA\thinspace per
bin).

\item{} {\bf wo} -- the nominal wavelength of the first detector bin 
(number 0).

\item{} {\bf rate} -- the total accumulated count rate (summed over wavelength bin).

\subsection{2.1.4 CALBRR}

CALBRR wavelength calibrates the BCS channel~1 and/or
channel~4 spectra contained in a BRR file. Because of the nature
of a Bragg crystal spectrometer, the relationship between detector bin and 
wavelength scale is not absolute, and depends upon the relative  position of
the  emitting source within the spectrometer field of view
in the direction of dispersion. CALBRR calibrates
this scale within the rest frame of the observer by fitting key lines within
the spectra, and referencing their centroids to known laboratory wavelengths.
CALBRR is invoked by typing: 

\verbatim

 $ CALBRR filid [/vel] or [/novel]

\endverbatim

\noindent where 'filid' is the usual file id of the BRR file to be processed.
The {\it /vel} switch will implement the fitting of a secondary blueshifted
component to the Ca~XIX and Fe~XXV $w$ resonance lines in channels 1 and 4,
respectively. By default, this switch is on. In cases where a blueshifted
component is unlikely to be pronounced (such as in a limb flare), it is
recommended that blueshift fitting be turned off by using the 
{\it /novel} switch.
CALBRR automatically updates the wavelength scale  of individual spectra in the
BRR file. If 'filid' is not entered, then CALBRR will run interactively and
prompt for assorted inputs. The results of CALBRR are written in the summary
ASCII file  CALyymmdd.hhmm, which inherits the file id of the BRR file.

\subsection{2.1.5 SPCFIT}

SPCFIT fits theoretical profiles to  BCS channel~1 calcium
and/or channel~4 iron spectra contained in a BRR file. The electron
temperature, emission measure, nonthermal broadening, and line-of-sight upflow
velocity of the soft X-ray source are determined from these fits. As with
MKBRR, this program has several control switches. An example of its usage is
as follows:

\verbatim

  $ SPCFIT /fil:800628.1810 /chn:1 /vel:3

\endverbatim

\noindent The {\it /fil:} and {\it /chn:} switches refer, respectively, to
the BRR file id 
and the channel number to be fit. It is important that the spectra for the
requested channel be extracted first by MKBRR and wavelength calibrated by
CALBRR before being processed by SPCFIT. Note that SPCFIT (like CALBRR) will
process only channels 1 and/or 4. In addition, SPCFIT  will fit only spectra
with sufficiently good statistics. Hence, the program  is very likely to skip
spectra observed very early during the flare impulsive phase or late during the
decay phase.

The {\it /vel} switch is an optional input that controls how fitting of a secondary
blueshifted component will be handled. CALBRR will have already made a first
approximation at fitting this component if the {\it /vel} switch was used. A detailed
description of the velocity model used by SPCFIT is given in Fludra {\it et
al.} (1989, {\it Ap.J.}, {\bf 344}, 991). Basically, the model assumes that the
doppler broadening width of the secondary component is proportional to its
blueshift velocity from the primary  $w$ resonance line of Ca XIX (or Fe~XXV).
The following values can be entered for this switch:

\item{0 $\Rightarrow$} do not fit a blueshifted component. This is the
stationary model.

\item{1 $\Rightarrow$} use the blueshift results from CALBRR as final, and do not iterate
further.

\item{2 $\Rightarrow$} use the blueshift results from CALBRR. Iterate further on the 
intensity of the blueshifted component, but keep it's velocity fixed.

\item{3 $\Rightarrow$} use the blueshift velocity and intensity from CALBRR
as first guesses and iterate further. This is the default option.

The outputs of SPCFIT are written to two files that inherit the file id
of the BRR (and CAL) file:

\noindent  FITyymmdd.hhmm is an ASCII file that contains  the fitted
parameters (temperature, emission measure, doppler broadening, and blueshift)
derived from the theoretical profiles fitted to the Ca~XIX or Fe~XXV spectra.
These parameters can be examined by using the IDL program PLOTFIT (\S~3.1.3).

\noindent SPCyymmdd.hhmm is a keyed-access isam file
that contains the final synthesized theory spectra. These spectra can be
examined also by using PLOTFIT.

\subsection{2.1.6 BCSPRO}

BCSPRO facilitates the task of fitting BCS channel 1 and 4 spectra in BDA
files by creating a command file to run MKBRR, CALBRR, and SPCFIT in batch
mode. It can be run non-interactively by typing:

\verbatim

 $ BCSPRO filid int

\endverbatim

\noindent where 'filid' is the file id of the input BDA file, and 'int' is the
integration time in seconds. The default integration time is 20~s, which is
optimum for producing spectra of sufficiently high signal to noise to allow
good quality fits of theoretical models.  BCSPRO will then submit a batch job
to run the above three programs in succession. The name of the batch command file
is: BCSPROhhmm.dmp, where hhmm is the file extension of the input file id.

If the file id is omitted, then the program will run interactively 
and the following prompts will appear:

\verbatim

  *****  XRP BCSPRO PROGRAM  V2.1  Mar 1990        *****

  There are a possiblility of 3 operations performed:

  1) MKBRR         - Write BRR file (read BDA file)
  2) CALBRR        - Calculate DW,W0, write CAL file
  3) SPCFIT        - Fit Te,Td,EM     write FIT file

  Enter 1 or 1,3 for: 1+2+3
        2 or 2,3 for: 2+3
        1,1      for: 1, etc.

           [def=1,3]: 

\endverbatim

\noindent At this point, you can control which programs to run by entering the
appropriate number. For example, entering 1 will initiate all three programs in
succession. You will then be asked the following series of questions:

\verbatim

* Enter the BDA file id or filename:  
* Enter the integration time (sec) [def=20]: 
* Change the start or stop times ? [def=N]: 

The command file = BCSPROhhmm.dmp

The submit instruction looks like :
 $ SUBMIT/NOPRINT/ID/NOTIFY/NOLOG/RESTART BCSPROhhmm.DMP

* Submit BCSPROhhmm.dmp file as a batch job? [def = y]:

\endverbatim

\noindent Accordingly, you enter the BDA file id, the integration time,  and
whether or not you wish to change the start and end times for processing.  By
default, BCSPRO will adopt the start and end times of the data in the BDA file.
The final question asks whether you wish to submit the subsequent program
execution as a batch job. For both the interactive and non-interactive modes, 
the completion of the batch job will be signalled by an e-mail message sent to
your login account. 


\section{2.2 FCS PROGRAMS}


\subsection{2.2.1 FOTON}

FOTON creates an FDA file by combining the FCS count and index  data in FCSDA
and FCSIX files,  together with the engineering ENG file. It is run
automatically at the end of the reformat process. It can be also run manually
by typing:

\verbatim

$ FOTON filid

\endverbatim

\noindent where 'filid' is the hhmm.doy extension of the FCSDA and FCSIX files.
If the reformatted files are not in the current directory, then the full
directory and filename must be entered on the command line. FOTON will prompt
for these inputs if 'filid' is not entered.  It is very important that the ENG 
file exist for FOTON to create a complete and correct FDA file.  Although FOTON
will create an FDA  file without this file, the subsequent analysis software
may fail if the engineering data are missing from the FDA file. Note that the
FDA file id is different from that of the input FCSDA file. 


\subsection{2.2.2 MKFIS}

MKFIS extracts all available images and spectra from an FDA file and copies
them to a FIS file. It is run by typing:

\verbatim

$ MKFIS filid

\endverbatim

\noindent where 'filid' is the yymmdd.hhmm extension of the FDA file. If the
FDA file is not in the current directory, then the full directory and filename
must be entered on the command line. MKFIS will prompt for these inputs if
'filid' is not entered. Note that MKFIS may often not process incomplete image
or spectral modes (such as modes interrupted by spacecraft night of South
Atlantic Anomaly [SAA]). In addition to creating a FIS file, MKFIS will 
produce a log file: FISyymmdd\_E.hhmm. The latter  file can usually be ignored.
The data in the FIS file can be examined by using the IDL program PLOTFIS
(\S~3.2.1).

\subsection{2.2.3 LISTFIS}

LISTFIS lists the contents of a FIS file. The  program does not accept command
line parameters. Upon typing LISTFIS, you will be asked  whether you would like
the output information sent to a file.  The default is NO. You will then be
asked to enter 1 (for a brief listing), or 2 (for a full listing). A brief
listing is recommended over a full listing. The program will then prompt for
the file name. You must enter the full directory  specification of the file if
it is not in the current directory. A sample screen output is shown below. 

\verbatim

 Data    Time    Date   Mode    #Yx#Z(dY)   St. Add.  Exp.       Mode ID 
 Set                                       Add  Step (DGI) Pts.  Reg. 
   1  14:45:50  14/ 7/86  RAST 16x16( 3)   6353   0     4    1  1 182 1.0.24.0 
   2  14:50:17  14/ 7/86  RAST  5x 5( 1)   6353   0     4    1  1   2 1.0.24.0     
   3  14:51:41  14/ 7/86  SS    1x 1( 0)    528   3     1 3325  1   0 3.0.28.1     
   4  15:06:01  14/ 7/86  SS    1x 1( 0)    528   3     1 3325  1   0 3.0.28.1      


 Data         Initial    Spacecraft       #Samp #Bad  %           
      
 Set (c'ont)  Y    Z   Pitch  Yaw  Roll                          
   1         -23   23  -82 -970     0.0  256   0 100.0
   2           2   -5  -82 -970     0.0   25   0 100.0
   3           3   -7  -82 -970     0.0 3325   6  99.8
   4          -7   -7  -81 -970     0.0 3325   1 100.0


\endverbatim

\noindent

The listed information includes: the date, time, and type of FCS mode (e.g.,
RASTer or SpectroScopic), the mode id,  the spacecraft boresite pointing (pitch
and yaw), the number of data samples, the integration time per sample (in units
of .256~s [DGI]), and the percentage of good quality data in the mode. Since
the width of the screen output exceeds 80 columns, it is recommended that the
screen width be widened prior to executing LISTFIS by using the (DCL) SET
TERM/WIDTH command.

\vfill\eject

\chapter{3}{IDL DATA ANALYSIS PROGRAMS}

This chapter describes the IDL (version 2) programs that were listed in 
\hbox{Table~1-4}. 

\section{3.1 BCS PROGRAMS}

\subsection{3.1.1 PLOTBDA}

PLOTBDA plots BCS lightcurves and/or spectra contained in BDA files 
created by BOTON.   The program will first prompt for the
BDA filename and directory location. If you can't remember the full BDA file
name, you can use wild characters (e.g. BDA*.*) and a menu of all the available
BDA files on the current (default) disk  will be listed for you.

After selecting the file, you will be asked to enter the channel numbers to
extract. Because of IDL memory limitations, it is unwise to request more than
three channels. Typically, you would enter 1,4,7 to read the Ca~XIX, and the
Fe~XXV low and high resolution channel data (\S~1.2.1 Table 1-1), respectively.
You will then be asked for the maximum accumulation time over which to sum the
data. The default is 10~s, which means that the BCS data in the selected
channels will be summed until the total integration time per spectrum is
$\ge 10$~s. Note that, because the actual BCS integration times are
usually non-integer (e.g. 3.6~s around the flare peak, and 7.2~s during the
decay), the final accumulation time will rarely be exactly equal to the
requested accumulation time.

After reading and accumulating the requested channel data, PLOTBDA will ask you
to enter a channel number to plot. This question will be skipped if you
initially extracted only one channel. A lightcurve of the selected channel will
then appear. You will then be asked whether you wish to plot spectra. Answering
YES (or Y) will produce a vertical cursor (ignore the horizontal cursor). You
will be asked to mark the start and end times (on the lightcurve plot) during
which you would like to extract and accumulate spectra.   Hitting any key will
automatically select the spectrum nearest the time where the vertical cursor is
located. Hitting a key once, then moving the cursor to another position on the
lightcurve, and then hitting a key again will cause PLOTBDA to select all
spectra in between the start and end cursor positions and  plot an average of
the selected spectra. Of course, hitting a key twice without moving the cursor
will cause PLOTBDA to plot a single spectrum nearest the cursor position.
PLOTBDA will ask next whether you wish to make a hardcopy of the plotted
lightcurve and/or spectrum. Answering YES (or Y) will generate a Postscript
plot file (IDL.PS) that will be printed on the available output device.
Finally, PLOTBDA will ask whether you wish to repeat the whole plot process.

PLOTBDA has several optional command line arguments and keyword parameters that
provide  access to the plot arrays and more control over the plot. (N.B.
although most command line arguments are optional, they must be entered in the
correct order. Keywords can be entered in any order).

\goodbreak
\midinsert
\begintable
\hfill\el


  {\underbar{Calling Sequence:}} \hfill \el

\hfill\el

           PLOTBDA, {\it T, Y, W, Z, /LOG, /EBAR, BIN=BIN}  \hfill \el

\hfill\el

  {\underbar{Outputs:}}  \hfill \el

\hfill\el

 {\it T} -- the time array (in seconds since the start of day) for the 
plotted lightcurve. \hfill \el


 {\it Y} -- the count rate array for the plotted lightcurve. \hfill \el


 {\it W} -- the wavelength (\AA) array for the spectrum 
selected using the cursor. \hfill \el


 {\it Z} -- the corresponding spectrum array (counts per sec per bin).
\hfill \el

\hfill\el

  {\underbar{Keywords:}} \hfill \el

\hfill\el

 {\it LOG} -- plot lightcurve on a log$_{10}$ scale. \hfill \el

 {\it EBAR} -- overplot uncertainties on the lightcurve. \hfill \el

 {\it BIN} -- a value by which to rebin the spectrum (e.g., bin=2 to double
bin). \hfill \el

\endtable
\endinsert

\subsection{3.1.2 PLOTBRR}


PLOTBRR plots BCS lightcurves and/or spectra contained in BRR files 
created by MKBRR. The program is analogous to PLOTBDA
except that you will not be asked to enter the channels to extract nor the
accumulation time. The latter selections were made in MKBRR. The program
will first prompt for the BRR filename and directory location. After reading
the file, it will then list the available channels, their associated ions
(usually Ca~XIX and Fe~XXV),  and the total number of spectra in each channel.
You will then be asked to select a channel to plot.

PLOTBRR will first plot the lightcurve for the selected channel. It will then
ask whether you wish to plot spectra. From this point on, the program will 
proceed exactly as PLOTBDA. In addition, PLOTBRR has the same optional command
line arguments and keyword parameters as PLOTBDA.

\bigskip
\begintable
\hfill\el
{\underbar {Calling Sequence:}} \hfill\el

\hfill\el

PLOTBRR, {\it T, Y, W, Z, /LOG, /EBAR, BIN=BIN}  \hfill\el
\endtable
\bigskip

\subsection{3.1.3 PLOTFIT}

PLOTFIT plots the results of the BCS analysis program SPCFIT. In particular, it
will read the FIT and SPC files created by SPCFIT and provide time history
plots of the electron temperature, emission measure, nonthermal broadening, and
upflow velocity deduced from fits of theoretical profiles to the BCS Ca~XIX
(Ch~1) and Fe~XXV (Ch~4) detectors. PLOTFIT commences with the following menu
of available items to plot:

\verbatim

* enter:
     1 : for electron temperature
     2 : for primary component emission measure
     3 : for primary component nonthermal broadening
     4 : for secondary component blueshift velocity
     5 : for secondary/primary component emission measure ratio
---->

\endverbatim

\noindent After you have entered the item number, you will be prompted for the
name of the FIT file and it's directory location.  After reading the selected
FIT file, PLOTFIT will print the start and end times of the file. The default
action is to plot the time history of the selected parameter between these
start and end times. You can override these defaults by entering your own start
and end times explicitly in the format: hhmm:ss.msec, where 'hhmm' is the hour
and minute (e.g. 0750), and 'ss.msec' is the second and millisecond (e.g.
23.123). The latter two time elements are optional. You will then be asked to
enter the channel number. The default is channel 1. If you enter channel 4 and
you did not process channel 4 data with SPCFIT, then you will be later asked to
re-enter the appropriate channel number.

After the selected time plot appears, you will be asked whether you wish to
examine the fitted spectra that were computed by SPCFIT during the derivation
of the fitted parameters. Answering YES (or Y) will invoke a cursor that you
can use to mark the time on the plot  when you wish to view the fitted BCS
spectrum.  PLOTFIT will read the observed and fitted spectra nearest the time
of the cursor from the BRR and SPC files, respectively,  associated with the
FIT file. The BRR and SPC files must be in the same directory as the FIT file
for this feature to work. A plot of the observed BCS spectrum with the
corresponding fitted spectrum superposed will appear. The final two questions
asked by PLOTFIT are whether you desire a hardcopy of the screen plots that you
have generated, and whether you wish to repeat the program.

\goodbreak
\midinsert
\begintable
\hfill\el
{\underbar{Calling Sequence:}} \hfill\el
\hfill\el
PLOTFIT, {\it T, Y, E, W, Z, ZF, /LOG} \hfill\el
\hfill\el

{\underbar{Outputs:}} \hfill\el
\hfill\el

{\it T} -- the time array (in seconds since the start of day) for the 
plotted lightcurve. \hfill\el

\noindent{\it Y} -- the selected fitted parameter. \hfill\el

\noindent{\it E} -- the uncertainty of the fitted parameter. \hfill\el

\noindent{\it W} -- the wavelength array for the 
spectrum selected using the cursor. \hfill\el

\noindent{\it Z} -- the observed spectrum array nearest the time of the 
cursor. \hfill\el

\noindent{\it ZF} -- the fitted spectrum array nearest the time of the 
cursor. \hfill\el

\hfill\el

\noindent {\underbar{Keywords:}} \hfill\el
\hfill\el

\noindent{\it LOG} -- plot the fitted parameter on a log$_{10}$ scale. \hfill\el

\endtable
\endinsert


\section{3.2 FCS PROGRAMS}

\subsection{3.2.1 PLOTFIS}

PLOTFIS plots images and/or spectra from FIS files  created by the program
MKFIS. The program will first  prompt you to enter I or S according to whether
you to wish to plot images or spectra. The default is  to plot images. You will
then be asked to enter the FIS file name and it's directory location. If you
selected images, then PLOTFIS will read all the image modes from the selected
FIS file and present a menu of the times of each mode. You can choose a time by
using a mouse in X-windows, or entering the number of the mode on a regular
terminal. You will then be presented with a menu of available channels for the
selected mode time. PLOTFIS will plot a color image  of the selected channel
ion data. You will then be asked whether you wish to make a hard copy plot, and 
whether you wish to repeat the program. It is not necessary to read the FIS
file again if you wish to plot a different image -- all the available images
are saved in memory after the initial read. However, you must read the file
again if you wish to plot spectra.

If you selected spectra, then (after entering the FIS file name)
you will be presented with the following menu:

\verbatim
     Display Data Blocks
     Select ALL Data Blocks
     Enter a List of Blocks to Extract
     Enter a Range of Blocks to Extract
     Enter a Type of Block to Extract
     Quit
\endverbatim

\noindent Because of memory limitations, it is recommended that you do not read
all the FIS spectral modes at one time.  Hence, you should begin by displaying
all the available modes and then selecting a particular mode to plot. After
making a mode selection, PLOTFIS will list the available channels and proceed
as described earlier for images. If you choose to repeat the program after
making a hard copy (and you wish to plot a different spectral mode) then you
must remember to read the FIS file again. Unlike images, all the available
spectra in the FIS file are not saved in memory -- only the most recent
spectrum is saved.

\goodbreak
\midinsert
\begintable
\hfill\el

\noindent {\underbar{Calling Sequence:}} \hfill\el

\hfill\el
 PLOTFIS, {\it X, Y, IMG, /NOBKG, /CONT, BIN=BIN, /FLUX} \hfill\el
\hfill\el

\noindent {\underbar{Outputs:}} \hfill\el
\hfill\el

\noindent{\it X} -- the wavelength array of the selected FCS spectrum.
\hfill\el

\noindent{\it Y} -- the count rate (per address bin) array of the selected FCS 
spectrum. \hfill\el

\noindent{\it IMG} -- the selected FCS image returned in a structure (see RDFIS).
\hfill\el

\hfill\el
\noindent {\underbar{Keywords:}} \hfill\el
\hfill\el

\noindent{\it BIN} -- a value by which to rebin the spectrum or image data.
\hfill\el

\noindent{\it NOBKG} -- inhibit background subtraction of FCS 
image (default is to subtract). \hfill\el

\noindent{\it CONT} -- plot image as a contour (default is to image). \hfill\el

\noindent{\it FLUX} -- flux calibrate spectrum 
[photons~cm$^{-2}$~s$^{-1}$~\AA$^{-1}$]. \hfill\el

\endtable
\endinsert

\subsection{3.2.2 RDFIS}

RDFIS reads images from FIS files and returns the data in a structure variable that
can be used by other programs. The program prompts first for the 
name and directory location of the FIS file.
It will then read all the image modes from the
selected FIS file and present a menu of the times of each mode.  You can choose
a time by using a mouse in X-windows, or entering the number of the mode on a
regular terminal. You will then be presented with a menu of available channels
for the selected mode time.  The selected image will be returned in a structure
variable  IMG which contains the following tags:

\verbatim

  IMG.DATA  = a 1-d float array containing the image count rates
  IMG.NX    = the number of columns in the image
  IMG.NY    = the number of rows in the image
  IMG.XP    = 1-d float array with the x-coordinates of the data pixels
  IMG.YP    = 1-d float array with the y-coordinates of the data pixels
  IMG.ID    = string name identifying the image
  IMG.TIME  = string time of data in UT format (e.g. 87/11/12, 0300:12) 
  IMG.EXPS  = exposure time per pixel (secs)
  IMG.PITCH = = spacecraft pitch (arcsecs)
  IMG.YAW   = spacecraft yaw (arcsecs)
  IMG.ROLL  = spacecraft roll (degrees clockwise from solar north)
  IMG.ADD   = detector address or wavelength of image

\endverbatim

The pitch and yaw variables  are the pointing  coordinates of the spacecraft
boresite. Positive pitch and yaw are measured in arcsecs  south and east,
respectively,  relative to the center of the solar disk.  The cartesian
coordinates of the FCS images are also in arcsecs  relative to the solar
origin, however their sense is reversed such that solar north  and west are
positive. To avoid structure size conflicts in IDL, it became necessary  to
store the 2-d images as a 1-d array. 

\goodbreak
\midinsert
\begintable
\hfill\el
\noindent {\underbar{Calling Sequence:}}\hfill\el
\hfill\el

   RDFIS, {\it IMG, CHNUM, BACK, /NOBKG}\hfill\el
\hfill\el
\noindent {\underbar{Outputs:}}\hfill\el
\hfill\el

\noindent{\it IMG} -- a structure with the selected FCS image. \hfill\el
                      
\noindent{\it CHNUM} -- the FCS channel number of the selected image.\hfill\el

\hfill\el
\noindent {\underbar{Optional Outputs:}}\hfill\el
\hfill\el

\noindent{\it BACK} -- corresponding structure with image background data. \hfill\el
                       
\hfill\el
\noindent {\underbar{Keywords:}}\hfill\el
\hfill\el

\noindent{\it NOBKG} -- inhibit background subtraction of FCS 
image (default is to subtract). \hfill\el

\endtable
\endinsert
                    
\subsection{3.2.3 RUST}

RUST reads and upacks the data and pixel  coordinate arrays for an  FCS image
saved in a structure variable created by RDFIS. This is a useful procedure that
provides easy access to the FCS data arrays.

\goodbreak\midinsert
\begintable
\hfill\el
\noindent {\underbar{Calling Sequence:}} \hfill\el
\hfill\el

             RUST, {\it IMG, DATA, XP, YP, DX, DY, XC, YC} \hfill\el
\hfill\el

\noindent {\underbar{ Inputs:}}   \hfill\el
\hfill\el

\noindent{\it IMG} -- structure created by RDFIS. \hfill\el
\hfill\el

\noindent {\underbar{Outputs:}} \hfill\el
\hfill\el

\noindent{\it DATA} -- 2-d data array (counts per sec). \hfill\el

\noindent{\it XP}   -- cartesian coordinates of image pixels in x-direction (+ W). \hfill\el

\noindent{\it YP}   -- cartesian coordinates of image pixels in y-direction (+ N). \hfill\el

\noindent{\it DX}   -- average spacing (arcsecs) between pixels in x-direction. \hfill\el

\noindent{\it DY}   -- average spacing (arcsecs) between pixels in y-direction. \hfill\el
\hfill\el


\noindent {\underbar{Optional Outputs:}} \hfill\el \hfill\el

\noindent{\it XC}   -- x-coordinate of center of image (relative to Sun
center). \hfill\el

\noindent{\it YC}   -- y-coordinate of center of image (relative to Sun
center). \hfill\el

\endtable
\endinsert

\subsection{3.2.4 FLUXCAL}

FLUXCAL converts FCS count rates  to photon number flux
\hbox{(photons~cm$^{-2}$~s$^{-1}$)}. The procedure approximates the FCS line  profile
by a symmetric Voigt function and converts the input count rate (which 
normally corresponds to the intensity at the peak of the line) to a total
intensity  by integrating the area beneath the Voigt profile.  To compute this
integral,  the program requires the total (thermal plus nonthermal) line
doppler width. You will be prompted for this width in velocity units of
km~s$^{-1}$, or you can enter it via the keyword DOPP (see below). The default
value is 100~km~s$^{-1}$.  A  typical value is somewhere between 50 and
100~km~s$^{-1}$ in active regions, and  above 200~km~s$^{-1}$ in flares. In
some cases, you may already have available  the total integrated line intensity
(e.g., from actually fitting a line  profile). Under these circumstances, it is
not necessary to use the Voigt  profile approximation. To inform the program of
this case, simply use the TOTAL keyword  and the input rate will be treated as
a total  (wavelength-integrated) intensity -- the DOPP keyword will be ignored
in this case. Note that the FCS profile often sits on a ``pedestal'' 
fluorescence background that is dependent upon peak intensities in other FCS 
detectors. The pedestal correction is {\it not} applied in this program. Except 
in the case of a strong (high C-level) flare, this background is generally 
negligible.

The following is a sample session with FLUXCAL:

\verbatim

IDL> fluxcal
* enter FCS line counts per second: 100
* enter FCS channel no [1-7]: 1
* enter FCS XTAL address of observation [def=6563]: 6563
% FLUXCAL: count rate is assumed to be at line peak
* enter total line doppler width [def = 50 km/s]: 100
* line flux (ph cm-2 s-1) =   9.86e+04

\endverbatim

\noindent In this example, FLUXCAL computes the FCS line flux 
for an observed count rate of 100~counts~per~sec in channel~1, with
the crystal positioned at address 6563 (i.e. the home position).
A doppler velocity of 50~km~s~$^{-1}$ is assumed for the line width.

\goodbreak\midinsert
\begintable

\hfill\el
\noindent{\underbar{Calling Sequence:}} \hfill\el

\hfill\el
FLUXCAL, {\it RATE, CHAN, ADD, FLUX, DOPP=DOPP, /TOTAL} \hfill\el
\hfill\el

\noindent{\underbar{Inputs:}} \hfill\el
\hfill\el

\noindent{\it RATE} -- FCS counts per sec at line peak (i.e., line center).
\hfill\el 

\noindent{\it CHAN} -- FCS channel (between 1 and 7) of the observed line.
\hfill\el

\noindent{\it ADD} -- FCS crystal address (e.g., 6563 for the home position).
\hfill\el \hfill\el 


\noindent{\underbar{Outputs:}} \hfill\el
\hfill\el

\noindent{\it FLUX} -- total line flux (photons~cm$^{-2}$~s$^{-1}$). \hfill\el
\hfill\el

\noindent{\underbar{Keywords:}} \hfill\el
\hfill\el

\noindent{\it DOPP} --  total line doppler width (thermal plus nonthermal) in 
km~s$^{-1}$. \hfill\el

\noindent{\it TOTAL} -- informs FLUXCAL that RATE is a total count rate.
\hfill\el
\endtable
\endinsert

\subsection{3.2.5 FTEMAP}

FTEMAP computes isothermal temperature and  column emission measure maps from
pairs of FCS images. The program begins by  prompting for the FIS file which
contains the FCS images in different channels. It will read all the available
images from the FIS file and list their corresponding times, ion
identifications, and mode characteristics (e.g., number of pixels, pixel size,
exposure time, spacecraft pointing, etc). To compute a temperature map, you
must choose  images observed in two different ions (e.g. Mg~XI and O~VIII) and
as close as possible in time (preferably the same time). FTEMAP uses the
FLUXCAL procedure to compute the flux for each pixel in the two ion maps, and
derives a temperature (in MK) and column emission measure  ($\int {n_e}^2
dl$~cm$^{-5}$) by  interpolating the ratios of these fluxes onto the ratio of
corresponding ion emissivity functions obtained from the Mewe tabulations (see
Mewe, Gronenschild,  and van den Oord, 1985, {\it Astron. Astrophys. Suppl.
Ser.}, {\bf 62}, 197). The column emission measure is computed from the total
volume emission measure (deduced from the total line flux) divided by the FCS
pixel area size.

After selecting an ion pair, the following menu will appear:

\verbatim

-------------------------------------------------------------
* DEFAULT MODE IS TO RUN ASSUMING:
-------------------------------------------------------------
1: Meyer coronal abundances
2: Nonthermal line doppler width = 50 km/s
3: Range of temperatures searched = 2 - 10 MK
4: Pixels with count rates below half sigma rejected
5: Adjacent pixels not averaged
6: Calculation results saved in XDR SAVE file: FTEyymmdd.hhmm
--------------------------------------------------------------
* do you wish to modify any of these assumptions [def=n]?


\endverbatim

\noindent These options have the following explanations:

\item{(1)} the Meyer (1985, {\it Ap.J. Supp.}, {\bf 57}, 173) coronal
abundances will be used to rescale the Mewe emissivity-temperature functions
for the selected ion pair. You can enter your own abundances (relative to atomic
hydrogen) via this option.

\item{(2)} a nonthermal doppler velocity width of 50~km~s$^{-1}$ will be 
assumed to reconstruct the line profile when FLUXCAL computes the total line
flux. You can enter a different velocity with this option. Note that FTEMAP
will add (in quadrature) the nonthermal width to the thermal  width (from the
derived temperature) to produce a total line width.

\item{(3)} in some cases, the temperature solution obtained from line ratios
can be multivalued. You can ``window'' single-temperature solutions by varying
the temperature range with this option.

\item{(4)} in some cases, the ratio of two noisy low signal-to-noise pixels can
result in a seemingly valid temperature value. To correct for this effect,
FTEMAP will compute the standard deviation of the count rates in the two
selected maps and reject all data values that fall below half a sigma. You
can change this cutoff threshhold via this option.

\item{(5)} by default, FTEMAP will not smooth or average ion maps. With this
option, you can choose to rebin the FCS count rates in order to improve
signal-to-noise at the expense of degraded spatial resolution.

\item{(6)} the temperature and column emission measure maps (together with the
corresponding flux maps for the two ions used  to derive them) will be saved as
structures in a portable XDR IDL save file: FTEyymmdd.hhmm, where the file name
is created from the file id of the original input FIS file. You can choose a
different output file name with this option.

After FTEMAP has completed it's calculations, it will 
print the following menu:

\verbatim

ENTER:

  1) to QUIT FTEMAP
  2) to REPEAT calculation
  3) to PLOT ION1 flux map
  4) to PLOT ION2 flux map
  5) to PLOT TEMPERATURE map
  6) to PLOT COLUMN EMISSION MEASURE map
  7) to SAVE results in FTExxxxxx.xxxx
  8) to HARD COPY latest map

\endverbatim

\noindent The required responses to these choices are obvious. Note that, if no valid
temperatures are found for any of the pixels in the selected ion pair then
options 5--8 will not appear.

\goodbreak\midinsert
\begintable
\hfill\el
\noindent{\underbar{Calling Sequence:}} \hfill\el\hfill\el

FTEMAP, {\it TEMP, EMISS, FLUX1, FLUX2} \hfill\el\hfill\el


\noindent{\underbar{Optional Outputs:}} \hfill\el\hfill\el

\noindent{\it TEMP} -- temperature (10$^6$~K) array. \hfill\el

\noindent{\it EMISS} -- column emission measure (cm$^{-5}$) array. \hfill\el

\noindent{\it FLUX1} -- flux (photons~cm$^{-2}$~s$^{-1}$) 
array for the first selected ion. \hfill\el


\noindent{\it FLUX2} -- flux (photons~cm$^{-2}$~s$^{-1}$) array for the second selected
ion. \hfill\el
\endtable
\endinsert


\subsection{3.2.6 PLOTFTE}

PLOTFTE plots maps of temperature, emission measure, and fluxes saved in FTE
saveset files created by FTEMAP. The program commences by asking for the name
and directory location of the FTE file. It restores the contents of the file
and presents the following (sample) menu:

\verbatim

* following images are available in:
FTE850123.0657
-----------------------------------------------------
 1) TEMP (MK)
 2) EM (10^28 CM-5)
 3) Mg XI (PH CM-2 S-1)
 4) O VIII (PH CM-2 S-1)
-----------------------------------------------------
* enter image number to plot [def = 1]: 

* hardcopy [def=n]? 
* another plot [def=n]? 

\endverbatim

\noindent In this example, you have the choice of plotting maps of
temperature, emission measure,  and Mg~XI and O~VIII fluxes that are saved in
the file FTE850123.0657. After plotting the selected map, PLOTFTE
will give you the options of making a hardcopy and returning to the
above menu for a new plot. PLOTFTE has 
output parameters that are indentical to those
of FTEMAP, with the following additional keywords.

\goodbreak
\midinsert
\begintable
\hfill\el
\noindent{\underbar{Calling Sequence:}} \hfill\el\hfill\el

PLOTFTE, {\it TEMP, EMISS, FLUX1, FLUX2, COLOR=COLOR, /CONT} \hfill\el\hfill\el

\noindent {\underbar{Keywords:}} \hfill\el\hfill\el

\noindent{\it COLOR} -- color table value (e.g. 0 for B/W [def], 3 
for red-temperature). \hfill\el

\noindent{\it CONT} -- plot maps as contours (user is prompted for 
contour level values). \hfill\el

\endtable
\endinsert

\subsection{3.2.7 TEMCAL}

TEMCAL calculates temperature (isothermal) and emission measure from
intensity ratios of two FCS lines. The following sample session
illustrates the usage of this program. 

\verbatim

IDL> temcal

* enter two FCS detector nos [def =  1, 3]
---> 1, 3

* enter corresponding line IDs from Mewe list [H for help; def =  752, 306]
---> 752, 306

* ion = O VIII
* central wavelength =  18.97
* O VIII MEYER abundance used = 2.47e-04
* ion = MG XI
* central wavelength =   9.17
* MG XI MEYER abundance used = 3.73e-05

* change ion abundances [def=n]? n
* enter corresponding observed counts/sec: 100,200
* are these integrated line rates [def = n]? n
* enter non-thermal Doppler velocity in km/s [def = 50]: 50
* enter range for temperature solution [def = 2, 10]:

% TEMCAL: -- temperature iterations in progress ---

-----------------------------------------
          Te       Log10(EM)
       (10^6 K)     (cm-3)
-----------------------------------------
         4.9        47.4
-----------------------------------------

* do you wish to plot G(T) ratios [def=y]? y
* enter temperature range (in MK) for plot [def=2,20]: 2,20
* hardcopy [def=n]?
* another calculation [def=n]?

\endverbatim

In the above example, TEMCAL computes temperature and emission measure using an
O~VIII count rate of 100 in FCS channel 1, and a Mg~XI count rate of 200 in FCS
channel 3. The numbers 752 and 306 correspond to the identifications of the
O~VIII and Mg~XI emissivity functions in the Mewe line tabulations. By default,
TEMCAL will normalize these functions to the Meyer coronal abundances. You  can
override this default by answering YES (or Y) to the change ion abundances 
question. By default, TEMCAL assumes that  the input count rates are peak line
center values and will use FLUXCAL to compute an integrated line intensity. If
the input rates are integrated values, then you can skip the integration step
by answering YES (or Y) to the next question. If the rates are peak values,
then  TEMCAL needs the nonthermal Doppler width (km~s$^{-1}$)  in order to
reconstruct the line profiles.  Lastly, TEMCAL requires a temperature range
within which to  confine its calculation. Such a range is necessary in case of
multiple solutions.

TEMCAL iterates the line flux ratios until the emission measures deduced from
the individual line fluxes are identical. If a converged solution is not
achieved, you will be given the option of varying the temperature range for the
calculation. After printing the converged solution, TEMCAL provides  options
for plotting the ratio of the ion emissivity functions, producing a hard copy,
and finally repeating the calculations.

\goodbreak\midinsert
\begintable
\hfill\el
\noindent{\underbar{Calling Sequence:}} \hfill\el\hfill\el

TEMCAL, {\it TEMP, EMISS} \hfill\el\hfill\el


\noindent{\underbar{Optional Outputs:}}  \hfill\el\hfill\el


\noindent{\it TEMP} -- temperature (10$^6$~K). \hfill\el\hfill\el


\noindent{\it EMISS} -- volume emission measure (cm$^{-3}$). \hfill\el

\endtable
\endinsert

\vfill\eject


\chapter{4}{IDL/WIDGET PROGRAMS}

This chapter describes the IDL/widget programs that 
enable reading and displaying of BCS and FCS data. These programs
provide the user with a Windows graphical user interface (GUI) to
many of the programs described previously.

\section{4.1 BCS}

The IDL/widget interface to BCS lightcurves and spectra is
invoked by typing:

\verbatim

IDL> BCS

\endverbatim

\noindent The program accepts BDA files as input and assumes that the logical
BCS\_DATA points to the directory  location of the BDA files. If this logical
is not defined, then you will be asked initially to  enter the directory
location of the BDA files that you wish to plot. Figure 4-1 
shows the main widget display produced by BCS. A listing of the BDA files in the
current  working directory appears under the listing: 
\smallskip\centerline{\it SELECT FROM THE FOLLOWING FILES}
\noindent You can select from this list by using the    
mouse (and hitting the leftmost button). By default, BCS will read channel~1
spectra, integrating  with 10~s time resolution. These values  can be changed
at any time by clicking on the desired channels in the 
\hbox{\it CHANNEL BUTTONS}
menu, and sliding the \hbox{\it ACCUMULATION TIME} slide bar to the desired
integration time value (where 0 corresponds to the minimum available time
resolution).  Because of memory limitations, it is not recommended that you
read more than two channels at a time.

The main widget display contains additional buttons which have the following
functions:

\bigskip

\item{$\bullet$}{\it Spawn To OS} -- will temporarily suspend the main IDL widget
program and spawn to the current operating system (VMS or UNIX).

\smallskip

\item{$\bullet$}{\it Change Directory} -- will permit the user to switch
to another working directory, and also to select files from the 
Selected Data Archive (\S~1.4) by choosing a date.

\smallskip

\item{$\bullet$}{\it Help} -- will print some very brief help information.

\smallskip

\item{$\bullet$}{\it Replot Latest File} -- will replot the lightcurve from
the latest file that has been read into memory.

\smallskip

\item{$\bullet$}{\it Quit} -- quit and exit BCS.

\bigskip

Upon reading the selected BDA file, BCS will plot
lightcurves for each of the selected channels. Recall that the 
lightcurves are derived by summing individual spectra over address bin.
The lightcurve plot will appear in a separate widget window.

Figure 4-2 shows a sample BCS lightcurve window
with the following application buttons:
                              
\bigskip

\item{$\bullet$}{\it Log Scale} -- if set, then plot the lightcurve using a 
log$_{10}$ scale. 

\smallskip

\item{$\bullet$}{\it Oplot Errors} -- if set, then plot the lightcurve with 
square root uncertainties for each data point.

\smallskip

\item{$\bullet$}{\it Hard Copy} -- make a hardcopy of the current plot.

\smallskip

\item{$\bullet$}{\it Integrate Spectra} -- integrate BCS 
spectra during the time interval defined by the two 
most recent cursor positions on the lightcurve plot.

\smallskip
           
\item{$\bullet$}{\it Write Data} -- write the BCS count rate and universal time arrays
to a data file (ASCII or IDL/XDR saveset).

\smallskip

\item{$\bullet$}{\it Zoom Lightcurve} -- zoom in on lightcurve 
during the time interval defined by the two 
most recent cursor positions on the lightcurve plot.

\smallskip

\item{$\bullet$}{\it Done} -- exit the lightcurve application and return to main calling widget.
              
\bigskip

\noindent After the lightcurve is plotted, the message:
\smallskip\centerline{\it USE CURSOR TO SELECT TIME OF SPECTRUM}
\noindent
will flash. At this point, you can view a BCS spectrum for a 
particular time by clicking the mouse button at the corresponding time position
on the lightcurve. The selected spectrum will be plotted
in a new widget window.
Figure 4-3 shows a sample BCS spectrum window with 
the following application buttons:
                              
\item{$\bullet$}{\it Double Bin} -- if set, then spectrum will be plotted
with double binning
(i.e. count rates in two adjacent address bins averaged into a single bin).

\smallskip

\item{$\bullet$}{\it Wavelength Axis} -- if set, then the spectrum 
will be plotted using a nominal wavelength (\AA) axis 
(i.e., uncorrected for position of the source relative to the dispersion axis).

\smallskip 

\item{$\bullet$}{\it Fit Options} -- opens a sub-menu of functions (Gaussian,
Voigt) to fit to a zoomed portion of the spectrum. (This facility
is still under development at time of writing). 

\item{$\bullet$}{\it Write Data} -- write the BCS count rate and address/wavelength
arrays
to a data file (ASCII or IDL/XDR saveset).

\smallskip \item{$\bullet$}{\it Zoom Spectrum} -- zoom in on a portion of spectrum
between address/wavelength values defined by the two most recent cursor
positions on the spectrum plot. Zooming must be performed prior to fitting.

\smallskip

\item{$\bullet$}{\it Done} -- exit the spectrum application and return to main calling widget.

\section{4.2 FCS}

The IDL/widget interface to FCS images and spectra is a direct analog
of the BCS widget program.
It is invoked by typing:

\verbatim

IDL> FCS

\endverbatim

\noindent The program accepts FIS files as input and assumes that the logical
FCS\_DATA points to the directory  location of the FIS files. If this logical
is not defined, then you will be asked initially to  enter the directory
location of the FIS files that you wish to plot. Figure 4-4 
shows the main widget display produced by FCS.  The main widget
contains application buttons ({\it Spawn To OS, Change Directory, Help, Quit})
that have the same
functions as in the BCS main widget program. A listing of the FIS files in the
current  working directory appears under the heading:  
\smallskip\centerline{\it SELECT FROM THE FOLLOWING FILES} \noindent You can
select from this list by using the mouse (and hitting the leftmost button).  

The FCS instrument operated in two modes: imaging and spectral. You must first
select between these two modes by clicking on the corresponding buttons
({\it IMAGE} and {\it SPECTRA}) that
are adjacent to the FIS file selection window. The program will read the header
of the selected FIS file and list the times of the selected mode, with imaging
and spectral modes identified by the labels RAST and SS, respectively,  under
the heading: \smallskip\centerline{\it SELECT FROM THESE FCS TIMES} \noindent
(The labels: IS, MSS, and MSSR denote spectral modes  corresponding to integral
scans, multiple spectroscopic scans, and multiple spectroscopic scans in a
raster, respectively). After you select a mode time, the program  will list
the channel information for the FCS detectors that were switched on during the
time of the mode. This information will appear under the \hbox{\it CHANNEL
BUTTONS} menu in the form of channel number and corresponding ion transition.
Detectors that were off during the selected time are not selectable. Clicking
on a valid channel will produce an image or spectrum window plot depending on
the selected mode type. 

Figure 4-5 shows a sample FCS image window.
The image is plotted as a contour with
a solar heliographic grid. The application buttons: {\it Hard Copy, Write Data}, 
and {\it Done}
have the same functions as in the BCS program. The remaining buttons have the
following definitions:
                              
\bigskip

\item{$\bullet$}{\it Double Bin Image } -- if set, then image will be plotted
with double binning
(i.e. count rates in two adjacent pixels averaged into a single bin).
                                               
\smallskip

\item{$\bullet$}{\it Contour Image} -- if set, then plot the image as a contour.
Otherwise, plot as color image.

\smallskip

\item{$\bullet$}{\it Gang Images} -- if set, then divide the plot window into
four quadrants and plot successive images in separate quadrants.

\smallskip

\item{$\bullet$}{\it Heliographic Grid} -- if set, then overplot a solar 
heliographic grid coordinate system.

\smallskip

\item{$\bullet$}{\it Log Scale Image} -- if set, then plot the image
using log$_{10}$ scaling.

\smallskip
\item{$\bullet$}{\it Overplot Images} -- if set, then successive images will
be overplotted as contours on the first image.

\smallskip
\item{$\bullet$}{\it Subtract Background} -- if set, then subtract detector background
from image.

\smallskip
\item{$\bullet$}{\it Tools} -- opens a submenu of tools to customize the color table;
check and correct the spacecraft pointing. (These tools are still under
development at the time of writing).

\bigskip

Figure 4-6 shows a sample FCS spectrum window.
The application
buttons in this window have the same functions as those described 
previously, with the following additional button:

\bigskip
\item{$\bullet$}{\it Flux Axis} -- plot spectrum in units of
photons~cm$^{-2}$~s$^{-1}$~\AA$^{-1}$ at the detector.
           
\section{4.3 LISTBCS}

LISTBCS provides a simple widget interface to the BCS catalog of flares in
which the total count rate in the Ca~XIX channel exceeded 18 counts~per~sec.
The catalog is approximately 90\% complete at the time of writing.
The program is invoked by:

\verbatim

IDL> LISTBCS

\endverbatim

Figure 4-7 shows a sample display produced by LISTBCS. The events are
listed by start and stop time (as determined by Ca~XIX count rates), as well as
peak Ca~XIX and Fe~XXV count rates (and corresponding times). 
The application buttons in this display have the following definitions:
\bigskip
\item{$\bullet$}{\it Select Date} -- permits the user to
choose the year, month, and day for which to search the BCS catalog.

\smallskip

\item{$\bullet$}{\it print Listing} -- print the listing on a hardcopy device.

\smallskip

\item{$\bullet$}{\it Quit} -- exit the program.


\indent
\vfill \eject

\bye

\verbatim

\section{APPENDIX A. DEVICE-DEPENDENT INFORMATION}


\indent
\vfill \eject

\goodbreak \topinsert
\section{APPENDIX B. GLOSSARY OF TERMS*}
\bigskip
\begintable
{TERM} \vt {MEANING} \eltt

BCS \hfill | The Bent Crystal Spectrometer on SMM. (See \S~1.2.1) \hfill \el
    \hfill | Also, an IDL widget interface to BCS data and software (\S~4.1). 
\hfill \el

DCL \hfill | DEC (Digital Equipment Corporation) Control language. \hfill \el

FCS \hfill | The Flat Crystal Spectrometer on SMM. (See \S~1.2.2) \hfill \el
    \hfill | Also, an IDL widget interface to FCS data and software (\S~4.2). 
\hfill \el

Filid \hfill | ``File id" or naming convention which uses start time of XRP data
files. \hfill \el 

\hfill | \indent The ``new format" XRP data files are specified by three
letters \hfill \el 
\hfill | which give file type (BDA, BRR, FDA, FIS), followed by the filid
\hfill \el 
\hfill | ``yymmdd.hhmm," giving year, month, day of month, start hour, and
\hfill \el 
\hfill | approx. start minute of data. \hfill \el
\hfill | \indent The ``old format" XRP data files are specified by file
type \hfill \el 
\hfill | (BCSDA, BCSIX, FCSDA, FCSIX, SPSUB, or ENG), followed by the \hfill \el 
\hfill | filid ``hhmm.doy," giving start hour, approx. start minute, and
day of year. \hfill \el
\hfill |  The year is not specified in the old format filid.\hfill \el

GOES \hfill | Geostationary Orbiting Environmental Satellite, a NOAA spacecraft.
\hfill \el

HP \hfill | ``Home Position" of the FCS wavelength drive. An address on the
drive \hfill \el 
\hfill | corresponding to the location of a prominent soft X-ray line in
each \hfill \el 
\hfill | each detector (see Table 1-2), the default position used for
imaging. \hfill \el 

IDL \hfill | Interactive Data Language. A computer language designed by
\hfill \el 
\hfill | Reseach Systems, Inc. for interactive analysis and visualization
\hfill \el 
\hfill | of data, particularly suited to array manipulation. \hfill \el

ISAM \hfill | Indexed Sequential Access Method for keyed-access files.
\hfill \el

NASA \hfill | National Aeronautics and Space Administration. \hfill \el

NOAA \hfill | National Oceanic and Atmospheric Administration. \hfill \el

New format \hfill | Format of BCS and FCS data files (BDA and FDA) in which raw 
\hfill \el
\hfill | count rate data, pointers to the data, detector information
essential \hfill \el 
\hfill | for interpreting the data, and spacecraft attitude are merged.
\hfill \el 
\hfill | (See \S~1.3 and Table 1-3). \hfill \el
\hfill | \indent New format files are created from old format BCS and FCS files
\hfill \el 
\hfill | by the Fortran programs BOTON and FOTON (\S~2.1.1 and \S~2.2.1), 
\hfill \el
\hfill | or automatically in the REFORMAT process (\S~1.4.1). \hfill 

\endtable

* (For names of XRP software programs and data files, see Tables 1-3 and 1-4.)
\endinsert

\vfill \eject

\goodbreak \topinsert
\noindent \bf APPENDIX B. GLOSSARY OF TERMS* (continued)}
\bigskip
\begintable
{TERM} \vt {MEANING} \eltt

Old format \hfill | Original format for reformatted BCS and FCS files, 
in which \hfill \el
\hfill | raw count rate data (BCSDA and FCSDA), the pointers to the data 
\hfill \el
\hfill | (BCSIX and FCSIX), and associated detector (ENG) and spacecraft 
\hfill \el
\hfill | attitude (SPSUB) information are all kept in separate files. 
\hfill \el
\hfill | (See \S~1.3 and Table 1-3.) \hfill \el
\hfill | \indent Old format files are created as the first step in the 
REFORMAT \hfill \el
\hfill | program (\S~1.4.1) which copies XRP data from Exabyte tape to disk.
\hfill \el
\hfill | Software to read old format files is no longer supported. \hfill \el
	
SDA \hfill | Selected Data Archive. An online subset of the XRP data, 
consisting \hfill \el
\hfill | of BCS and FCS data taken during flares and FCS spectral scans. \hfill \el
\hfill | (See \S~1.4) \hfill \el

SDAC \hfill | Solar Data Analysis Center, located at Code 682.2, \hfill \el
\hfill | NASA/Goddard Space Flight Center, Greenbelt, Maryland 20771. \hfill \el

Sit \& Stare \hfill | Name for FCS observing mode in which count rate data 
were taken \hfill \el
\hfill | at one wavelength address and one spatial location (the spacecraft 
\hfill \el
\hfill | (the spacecraft bore sight or the brightest pixel in a survey
map). \hfill \el 
\hfill | Sit \& Stare data are not kept in the new format FCS data files. \hfill \el 

SMM \hfill | Solar Maximum Mission. A NASA mission designed primarily \hfill \el
\hfill | to study the Sun. \hfill \el

XRP \hfill | The X-Ray Polychromator on SMM, comprising the BCS and FCS. \hfill 

\endtable
* (For names of XRP software programs and data files, see Tables 1-3 and 1-4.)
\endinsert

\indent

\vfill \eject


Figure 1-1       Flow Chart for XRP Data Reduction and Analysis


                      ---------REFORMAT(f/i)---------
                     |                               |
                     |                               |
             bcsda---|---bcsix               fscda---|---fcsix
                     |                               |
                     |                         eng---|---spsub
                     |                               |
                     |                               |
                   BOTON(f)                        FOTON(f)
                     |                               |
                     |                               |
               bda---|                               |---fda
                     |                               |
                     |                               |
                 ---------                           |
                |         |                          |
                |         |                          |
            MKBRR(f)  PLOTBDA(i)                  MKFIS(f)
                |                                    |
                |                                    |
          brr---|                                    |---fis
                |                                    |
                |                                    |
       -------------------                ----------------------
      |         |         |              |           |          | 
      |         |         |              |           |          |  
   CALBRR(f) PLOTBRR(i) LISTBRR(f)   LISTFIS(f)  PLOTFIS(i)  FTEMAP(i) 
      |                                                         |
      |                                                         |
cal---|                                                         |---fte
      |                                                         |
      |                                                         |
   SPCFIT(f)                                                  PLOTFTE(i)
      |            
      |                
spc---|---fit                                  
      |
      |
  PLOTFIT(i)


  Input/output files are shown in lower case; programs in upper case.
  BCS programs are listed on the left; FCS programs are listed on the right.
  Fortran programs are denoted by (f); IDL programs are denoted by (i).



\endverbatim

     
