\section{Introduction to the Yohkoh Data and Software}
\index{software tree}
\index{directories, software}

\subsection{YS, YDB, and YDn Directories}

The Yohkoh data are organized into three general parts.  
\begin{itemize}
\item [YS] The software, 
documentation, and some calibration data files are located in the 
Yohkoh Software (YS) tree.
There is a separate branch for each instrument, and one for general software
which holds software and data that can be used by all instruments.
\item [YDB] The secondary database files are contained in the Yohkoh Database
(YDB) tree.  The secondary database files include S/C attitude information,
observing logs, event logs, detailed calibration files, summary data files,
and several ground-based database files.
\item [YD] The raw reformatted Yohkoh data (YD) are placed in the YD directories.
At ISAS, there are twenty one Yohkoh data directories (/yd0, /yd1, /yd2, .... /yd20).
The standard method for putting data on-line is to create a directory with
the week number, for example /yd10/93\_41a and put all the data for week
93\_41 into that directory (except for the weekly files).
\end{itemize}

\subsection{Yohkoh Software Organization}

It is assumed that you have successfully installed the Yohkoh software on
your system or you are using a machine that has the Yohkoh software.  In
addition to having made the software installation, it is necessary to have
executed the Yohkoh initialization routine (`/ys/gen/script/idl\_setup' or
`.yslogin' for the Unix machines).  If you have not done this yet, 
see the Appendix of the Yohkoh Reference Guide.

The Yohkoh software is organized under one tree.  The top directory is \$ys
for Unix systems, and is the logical YS: for the VMS systems.  Under that
tree are the following branches:

\vspace{0.2in}\begin{tabular}{|l|l|} \hline
{\sl Branch} & {\sl Description} \\ \hline
SITE & {Site specific software} \\
GEN  & {General software and documents that all instruments can use} \\
BCS\_F77  & {BCS FORTRAN specific software and documentation} \\
BCS  & {BCS specific software and documentation} \\
HXT  & {HXT specific software and documentation} \\
HXT\_F77  & {HXT FORTRAN specific software and documentation} \\
SXT  & {SXT specific software and documentation} \\
WBS  & {WBS specific software and documentation} \\
ATEST  & {Newly created or modified software and documentation} \\
UCON  & {User Contributed software and documentation} \\ 
IDLFIX & {Work-arounds for systems using older IDL versions} \\ \hline
\end{tabular}\vspace{0.2in}

Under each of the above instrument directories, there are the following 
directories (for example, `/ys/sxt/doc')

\vspace{0.2in}\begin{tabular}{|l|l|} \hline
{\sl Branch} & {\sl Description} \\ \hline
DOC & {Documentation} \\
RESPONSE & {Instrument calibration and response data files} \\
SOFT & {Software} \\
STATUS & {Instrument status information} \\ \hline
\end{tabular}\vspace{0.2in}

Software that has been thoroughly tested is put into the instrument release 
directory `soft'.\footnote{The previous organization had an `atest', `rel', and `usercontrib' branch
under each `soft' directory.}
Software which has just been written, or software that is modified is put into the
`atest' area for a period of a few weeks.  Certain privileged users have write privilege to 
those directories.  If problems develop with modified
software, it is possible to recover the old version by copying it from the
`soft' directory.   The software developed by general users is placed online under
the `ucon' (user contributed) branch.  Generally each user who is contributing has a directory
of their own.  The directories under the `soft' branch are broken up by function for
the `gen' and instrument branchs, but by person under the `ucon' branch.
If a user cannot remember the name of a function, he/she can do a listing on
the different directories and will probably recognize it.  A list of the
directories that currently exist for the instrument teams is:

% LIST_REL.TEX input starts here -------------------------------

\vspace{0.1in}
\input list_rel.tex

% LIST_REL.TEX input ends here -------------------------------

\subsection{How to Contribute Software to the Yohkoh Tree}

See the appendix of the Reference Guide.

\input rguide_file_fig.tex

\subsection{Yohkoh Data File Format}
\index{data files, reformatted}
\index{reformatted data files}
\index{file format, archive data}
\index{format, archive data file}
\index{archive data, format of files}
\index{roadmap}

For a full description of the Yohkoh database and all the different data
structures, see the File Control Document.

Each file is logically divided into the following six sections.  Some
files will not use all the sections described below, but all will
have a Pointer and File Header Section.

\EEnumerate
\item File Information and Pointer Section
\item File Header Section
\item Quasi-Static Index Section
\item Index and Data Section
\item Optional Data Section
\item Road Map Section
\end{enumerate}

The program which reads the file learns from the Pointer Section how
to read the rest of the file and where to go to get certain data.  

The File Header Section provides information on what data are contained in
the file, generally the extent of the time covered by the contents. 

The Quasi-Static Section of the file contains index information that
does not vary during the course of an orbit, or varies slowly.  

The Index and Data section contains `data sets'.  A data set is a single \index{data sets}
image for SXT, single spectrum for BCS, a single major frame of data for
HXT, and two major frames of data for WBS (it takes two major frames for
a complete set of WBS data).  For each data set there is an index which
describes the date and time that the data were taken, the
mode and position of the instrument's peripherals (e.g., filters, HV), and
information on temperature and gain information.
\index{index structure}

The Optional Data Section is only used by the BCS data (BDA) files and the
spacecraft attitude (ADA) files.  The BDA files hold the `DP\_SYNC' information,
which is information that is coming down every major frame.  Since the BCS
spectra are asynchronous to the major frames, it is stored separately.  The
ADA file holds the full 2048 point HXA scans.

The Roadmap Section allows a user to access a brief summary of the contents of 
the file and to perform searches on that summary to select what data should be 
extracted.
\index{roadmap structure}

\subsection{Yohkoh Data File Names}

\subsubsection{Yohkoh Directory Logicals/Environment Variables}
\index{directories, database}
\index{environment variables, database}
\index{database, environment variables}

\begin{sloppy}
There is a set of VMS logicals and Unix environment variables which point to 
the database directories.  By using these logicals in all of the access routines
(along with the routine \mbox{CONCAT\_DIR)} it is possible for software to be directly
portable between VMS and Unix machines.  The following is a list of the logicals 
that exist for the Yohkoh database.
\end{sloppy}

\newpage

% LIST_DIR.TEX input starts --------------------------
\input list_dir.tex
% LIST_DIR.TEX input ends --------------------------

\subsubsection{Yohkoh Prefixes}
\index{YDB files}\index{Yohkoh file prefixes}\index{prefixes}
\index{file prefixes}\index{secondary database files}\index{SFD images}

% MK_PREFIX_TABLE input file start ------------------------

\input mk_prefix_table.tex
 
% MK_PREFIX_TABLE input file end ------------------------
 
\subsubsection{Yohkoh File IDs}\index{file IDs}\index{file names, IDs}

The orbit file ID's are 11 characters long in the format shown below:

\begin{verbatim}
        YYMMDD.HHMM

        where YY - Year of data
              MM - Month of data
              DD - Day of data
              HH - Hours
              MM - Minutes
\end{verbatim}

\subsubsection{Yohkoh Week IDs}\index{week IDs}\index{file names, week IDs}

The Yohkoh week starts on Sunday and ends on Saturday.  CAUTION: Yohkoh
data taken at 00:01 (one minute after midnight) on Sunday morning is
most likely in a file and tape for the previous week since the orbit
started on Saturday and the first full orbit for Sunday has not started. 
Up to the first 90 minutes of data taken on Sunday could be stored in
the previous week, depending on when the spacecraft day begins. 

The weekly IDs are of the form:

\begin{verbatim}

        YY_WWa.NN

        where YY - Year of data
              WW - Week number of the data (1 to 53)
               a - is fixed (reserved for future use)
              NN - is the program version number which created the file

\end{verbatim}

A list of the dates covered by each of the weeks is given in Appendix xxx.
%%The following are the dates covered by each of the weeks for 1991--1995:
%%
%%% MK_WEEKID.TEX input starts here ---------------------
%%
%%{\small
%%\input mk_weekid.tex }
%%\normalsize
%%
%%% MK_WEEKID.TEX input ends here ---------------------

\subsubsection{Yohkoh Carrington IDs}\index{carrington IDs}

The Carrington IDs are of the form:

\begin{verbatim}
        _crRRRRa.NN

      where cr   - signifies a Carrington Rotation ID
            RRRR - is the rotation number
             a   - is fixed (reserved for future use)
            NN   - is the program version number which created the file
\end{verbatim}
%
\noindent The dates for the Carrington Rotations are defined in the
table.

%[tbp]
\begin{figure}[tp]
\input mk_carr_id.tex
\end{figure}

\subsection{Interactive Data Language (IDL)}
\index{IDL}

Most of the Yohkoh software is written in the programming language IDL of
Research Systems, Inc (RSI).
If certain rules are followed, then the same IDL software can be run on
a wide variety of computers.

\subsubsection{Some Comments about IDL}

In using IDL it is very easy to create too many variables to the point where
the computer memory capacity is exceeded.
It is possible to delete old
variables by using the DELVAR command.  For example, if you wanted to delete
the variable DATA, you would type:
%
\idlinputa{delvar, data} \index{DELVAR}
%
There is a peculiarity about using the IDL routine FINDFILE and using the
Unix symbol $\sim$ for the user's home directory.  FINDFILE does not return any
files when using the command:
%
\idlinputa{ff = findfile('$\sim$/*')} \index{FINDFILE}
%
It is recommended to use the full path (for example `/2p/morrison/*') instead
of $\sim$.

%\newpage
It is possible to change the default directory from within IDL by using
the IDL command ``cd''.  Some sample commands are:
%
\idlinputa{cd, '$\sim$'}\index{CD}\index{setting default directory}
\idlinputb{cd, '/yd3'}
%
The following will NOT work since it sets the default for the sub-process
and then exits that process.
%
\idlinputA{1.5}{\$ cd /yd3}{;WILL NOT WORK}

For Unix machines, it is possible to press {\it control-z} to place an
IDL session in the background so that you can do some work from the Unix
system.  When you are ready to go back to the IDL session, type:
%
\ultrixinputa{fg}
%
Be careful to remember that you have an IDL session hidden in the background
since you can waste memory and corrupt the color table settings if you 
have multiple IDL sessions going.

\subsubsection{Programs, Procedures, and Functions}

An IDL main program requires a .RUN command to run, and the code within that
file starts executing after successful compilation.

An IDL procedure is a kind of subroutine and has something like \\
\mbox{\hspace{1.in}{\tt PRO PROCEDURE\_NAME, PARAM1, PARAM2}} \\
at the top of the file.  The variables in the procedure definition can be input
or output.  It is possible to have keywords with a command like \\
\mbox{\hspace{1.in}{\tt PRO PROCEDURE\_NAME, KEY1=KEY1, KEY2=KEY2}} \\
It can be executed with a command like:
%
\idlinputa{procedure\_name, a, b}
\idlinputb{procedure\_name, a, b, key1=c}
%
An IDL function is another kind of subroutine and has something like \\
\mbox{\hspace{1.in}{\tt FUNCTION FUNCTION\_NAME, PARAM1, PARAM2}} \\
at the top of the file.  The primary output is passed to {\it result}
but it is possible to have parameters in the call which can receive output.
It is executed with a command like:
%
\idlinputd{result = function\_name(a,b)}
%

\subsubsection{Running IDL programs}

When running on a Unix system, it is important to use lower case when using
the .RUN command because Unix is case sensitive.  This is not necessary when
doing an `implied' compilation when accessing procedures or functions since
IDL will convert to lower case for you.  You cannot use upper case for a
procedure to do an explicit compilation (.RUN PROCEDURE\_NAME) to recompile 
a procedure.

