\section{Installation and Maintenance of the Yohkoh Software}\index{installation of Yohkoh package}\label{install_sec}

\subsection{Network Installation}\index{network installation}

This section describes the network installation of compressed tar files on Unix
systems\footnote{If you have already installed Yohkoh Software in the past and do not need to
   relocate it, skip to section~\ref{network_upgrades}. (Upgrades) instructions.}.
Current disk allocation requirements: Approximately 100 MBytes which includes the 
Software and several supporting databases (35 Mbytes for only IDL and FORTRAN software
or 25 Mbytes for only IDL software).

\EEnumerate
\item  Determine which user will own the Yohkoh software and database area.  Some 
      sites prefer to create a special ``Yohkoh'' account for management but this 
      is not an installation requirement.  Log into the appropriate account.

\item Determine the path where you want to locate the Yohkoh Software.
     Let's call this path {\it yparent}.  This pathname should be an nfs name per
     /etc/fstab if the software is to be shared among machines.  Of course, the
     owner of the Yohkoh Software (determined in preceding step) requires write access
     to {\it yparent}.

\item Transfer the boot-up script via anonymous FTP.  
 ~
\ultrixinputA{3.5}{mkdir -p  {\it yparent}/ysw/swmaint/tar	}{\# local directory for tar files}
\ultrixinputB{3.5}{cd {\it yparent}/ysw/swmaint/tar		}{\# move there}
\ultrixinputB{3.5}{ftp 133.74.8.100				}{\# user=ftp, passwd=name@node}
\ftpinputB{3.5}{cd pub/swmaint/tar				}{\# remote location (isass0)}
\ftpinputB{3.5}{get ys\_install					}{\# boot up script}
\ftpinputc{quit}

\item Install the software and standard database using the script {\it ys\_install}.
      The defaults are usually ok, but see script header for available options.
      Use the {\it /HELP} switch to get updated instructions and the latest
      Yohkoh Software and Database descriptions without installing anything.
      (current directory is still = {\it yparent}/ysw/swmaint/tar).
%
\ultrixinputA{3.5}{csh ys\_install 		}{\# INSTALL, take defaults}
\ultrixinputB{3.5}{csh ys\_install [OPTIONS]	}{\# INSTALL, use 1 or more options}
\ultrixinputC{3.5}{csh ys\_install /HELP 	}{\# No installation, Help Information}
   
\end{enumerate}
Section \ref{newuser} describes the procedure for setting up the Yohkoh
environment for new accounts.  

\subsection{Network Upgrades}\label{network_upgrades}\index{upgrades}\index{network upgrades}
   
This section is applicable if you have previously installed the Yohkoh
Software on your Unix workstation.  It will upgrade the latest version of the
software and database files using the existing locations.

NOTE: beginning with Yohkoh Software Version\# 931107.02, auto-upgrade scripts
are included in the distribution. Once you have upgraded to this level,
all FTP  commands are automatically issued. For older Versions (before 930513.01)
you must first retrieve the installation ``boot'' script -- other files will
be auto-FTPed as required.
%
\ultrixinputD{3.5}{tail -1 \$ys/gen/setup/ys.version	}{\# determine current version number}
%
\subsubsection{New Versions (starting with 931107.02)}

\begin{sloppy}
Log in as owner of the Yohkoh Software tree; verify that \$ys is defined.
For possible options see header of \mbox{\$ys/gen/script/ys\_install}.  Next, 
\footnote{this command may be placed in a daily ``cronjob'' to provide automatic
upgrades -- see discussion on page~\pageref{auto_updates}.}
\end{sloppy}
%
\ultrixinputa{csh \$ys/gen/script/ys\_install}
\ultrixinputc{csh \$ys/gen/script/ys\_install [OPTIONS]}
%
\subsubsection{Old Versions ( Before 930513.01 )}

Log in as owner of the Yohkoh Software tree; verify that \$ys is defined
%
\ultrixinputA{3.5}{cd \$ys/swmaint/tar		}{\# local tar site}
\ultrixinputB{3.5}{ftp 133.74.8.100		}{\# user=ftp, passwd=name@node}
\ftpinputB{3.5}{cd pub/swmaint/tar		}{\# remote location (isass0)}
\ftpinputB{3.5}{get ys\_install			}{\# boot up script}
\ftpinputb{quit}
%
see header of \$ys/swmaint/tar/ys\_install for options, then:
%
\ultrixinputa{csh \$ys/swmaint/tar/ys\_install}
\ultrixinputc{csh \$ys/swmaint/tar/ys\_install [OPTIONS]}

\subsection{Automatic Upgrades of Yohkoh Software}\label{auto_updates}\index{automatic software upgrades}
\index{upgrades}\index{software upgrades}\index{batch jobs}\index{cron jobs}

The command to automatically upgrade the Yohkoh software on a periodic basis
may be inserted into a ``cron job'' at remote 
sites\footnote{Requires Yohkoh Software Version: 931108.02 or higher}.  If you are not familiar
with function and operation of cron jobs on your particular machine, you 
should consult with your system manager.  Although there may be some system 
dependencies not covered here we present some sample implementations here.
Notes: {\it ys} is the path assigned to \$ys ; {\it ysowner} is the username of the Yohkoh Software owner.

\newpage
\begin{center} {SUN/Mips/SGI/OSF} \end{center}

\EEnumerate
\item Log on as the owner of the Yohkoh Software
\item Edit the ``crontab'' file with the command:
	\ultrixinputd{crontab -e} \\
	and add a line with the format: \\
	{\tt MM HH * * * setenv ys {\it ys};csh \$ys/gen/script/ys\_install }
\item A specific example which upgrades the software daily at 23:00 local time is: \\
	{\tt 00 23 * * * setenv ys /user1/ysw; csh \$ys/gen/script/ys\_install}
\end{enumerate}
     
\begin{center} {Ultrix}  \end{center}

\EEnumerate
\item Log on root
\item Add the following line to /etc/crontab via editor \\
	{\tt MM HH * * * rsh -l {\it ysowner} "setenv ys {\it ys};csh \$ys/gen/script/ys\_install"}
\item A specific example which upgrades the software daily at 2:00 local time is: \\
	{\tt 00 02 * * * rsh -l ysoft "setenv ys /user1/ysw; csh \$ys/gen/script/ys\_install"}
\end{enumerate}

For Ultrix systems that wish to use the root account to run the batch job, you
can exclude the ``rsh -l {\it ysowner}'' portion of the command.  If you do not run
as the root user, then you will also need to edit the {\tt $\sim$/.rhost} file for
the account which will be used to execute the ``ys\_install'' script, and
add a line similar to the following line, except with your node name.

\begin{verbatim}
         isass0.solar.isas.ac.jp         root
\end{verbatim}

\subsection{Site Specific Cleanup Script}\index{site cleanup script}

Sites may choose to execute a customized cleanup script following a Yohkoh 
installation.  Common uses for this could be to set file protections,
ownerships, group access etc. (chmod, chown, chgrp).  It is possible to have 
such a script run automatically as part of the installation/upgrade procedure 
by naming the script \$ys/site/script/ys\_install.local.   If this file exists,
the Yohkoh Installation scripts will source it following the successful 
completion of an upgrade and/or installation.  It is up to the local manager
to verify that all commands within this script have the correct syntax.  For example,
if {\it chown} commands are issued, then the Yohkoh installation procedure would
have to be run from the root account to have these take effect.

\subsection{DATA\_PATHS}\index{DATA\_PATHS}

Remote sites have many differences in available disk space, physical disk
names and path names.  To allow seemless software access to Yohkoh data and database
files, we make use of Unix environmentals and VMS logicals within the routines.
This allows relocation of existing data areas and addition of new data areas with no
changes required to the access software. 

Reformatted data access routines use logicals or environmentals which are 
named ``ydNN'' where ``yd'' stands for Yohkoh data and NN is an integer.
Every site should define at least one data area (usually yd0); there is no
upper limit on the number.  The most common scheme is to have one area
(and one environmental) per physical disk available for Yohkoh reformatted data.

To add a new area (ie, add a new environmental), a line should be added to the 
file \$ys/site/setup/setup\_paths.  This script file is one of a few which are 
automatically executed during the Yohkoh IDL setup to configure the local and 
Yohkoh environment.  

\begin{verbatim}
Each line is a Unix 'setenv' command of the form:

           setenv  yd<N>  <pathname>  
WHERE:
<N>        = integer = disk area number (traditional to start at zero (0) )
<pathname> = pathname of data area to add 
             If the area is to be shared via NFS, this should include the 
             mount name as found in /etc/fstab
\end{verbatim}

For example, appending the following lines to \$ys/site/setup/setup\_paths 
would add 3 reformatted data areas.

\begin{verbatim}
        #....
        #..... current contents of file: $ys/site/setup/setup_paths
        #.....
        # add 3 data areas for Yohkoh reformatted data
        setenv yd0     /user1/yohkoh
        setenv yd1     /data_disk2/yohkoh
        setenv yd2     /machine_mount2/scratch/yohkoh
        #..................................................
\end{verbatim}

These areas will then be searched by the Yohkoh Software for reformatted data files.
(creating the directories and placing data there is not covered here).

\subsection{Receiving and Installing Secondary Yohkoh Database Files}\index{secondary database files}\index{database files}
\index{YDB files}

A summary of supporting and secondary databases and the approximate size
is provided in the following table.  Certain database sets are
automatically included when a Software installation or full upgrade is performed
(described in previous section).   All database files are also available 
on Exabyte tape (``ydb tape'')  To receive a tape containing the  mission-long 
Yohkoh database and to be placed on the distribution list for future 
releases, send e-mail:

\begin{verbatim}
      TO: software@isass0.solar.isas.ac.jp
    SUBJ: ydb tape request
\end{verbatim}

The IDL routine RD\_YDBTAP (described in the User's Guide) can be
\index{RD\_YDBTAP}\index{YDB tapes}\index{database tapes, reading}
used to extract and install user specified portions (or all) of the Yohkoh 
database from the ydb tape.  That routine will optionally provide assistance 
in setting up and customizing the local environment prior to extraction and 
installation.  The physical disk locations where each database resides at 
any given site are flexible since all software references are through the use 
of environmentals (Unix) or logicals (VMS).  The IDL routine HELP\_PREFIX
provides some additional information about the specific database contents.

This table can be used to estimate current and future disk space requirements
for the Yohkoh database.  Unless otherwise noted, the distributed files
contain one week of data.  Column one (PFX) indicates the three letter prefix
associated with each database set.  Items marked with an asterisk are included
in the automatic software installation procedure described in the preceding sections.

% \newpage
\begin{verbatim}
PFX   Contents                                   Avg File Size     Mission Size
                                                                   (Thru 1/94)
ATR   Raw S/C Attitude Database                      2684 Kb          314.6 Mb
ATT   Processed S/C Attitude Database                2024 Kb          237.2 Mb
EVN*  Yohkoh Event Log                                 14 Kb            1.8 Mb
FEM*  Yohkoh Orbital Ephemeris                          7 Kb            1.2 Mb
G6D   GOES 3 Sec Light Curve for S/C 6               2725 Kb          181.0 Mb
G7D   GOES 3 Sec Light Curve for S/C 7               2742 Kb          182.2 Mb
GBE   GRO BATSE Event Log                           19525 Kb [1]       19.1 Mb
GBL*  GRO BATSE Light Curves                          143 Kb           19.1 Mb
GEV*  GOES Event Log                                    5 Kb            0.7 Mb
GXD   GOES Derived One Minute Light Curve Data          5 Kb            0.0 Mb
GXT*  GOES One Minute Light Curve Data                330 Kb           40.0 Mb
NAR*  NOAA Active Region                                3 Kb            0.4 Mb
OBD   BCS Observing Log                               690 Kb           81.7 Mb
OSF   SXT Full Frame Observing Log                     52 Kb            6.3 Mb
OSP   SXT Partial Frame Observing Log                 385 Kb           45.6 Mb
OWH   WBS/HXT Observing Log                          1266 Kb          150.9 Mb
SDC   SXT Dark Current Images                        1827 Kb          201.7 Mb
SDW   SXT Dark Current Images for Warm CCD           5196 Kb           81.2 Mb
SFC   SXT FFI Calibration (Leak) Image                528 Kb            4.2 Mb
SFM   SXT FFI Monthly File (daily SFD image)         6506 Kb  [M]     158.9 Mb
SSC   SXT Synoptic Images (centered)                  697 Kb           77.6 Mb
SSE   SXT Synoptic Images (east of center)            703 Kb           (inc)
SSW   SXT Synoptic Images (west of center)            703 Kb           (inc)
XAD*  Exabyte ASCII Directory for Archive Tape         10 Kb            2.1 Mb
XBD*  Exabyte Binary Directory for Archive Tape         7 Kb            1.5 Mb

[1] - only 1 file for mission
[M] - each file contains one month of data
\end{verbatim}

% \newpage
The following table indicates which datasets are important for various purposes.

\vspace{0.2in}\begin{tabular}{|l|l|} \hline
Description					& Datasets \\ \hline
Critical general datasets			& FEM \\
Critical datasets for SXT calibration		& SDC, SFC \\
Nice SXT datasets to have			& SSC/E/W, SFM \\
Critical datasets for alignment			& ATT \\
Non-necessary datasets for alignment		& PNT, ATR \\
Observing log and event logs -- nice to have	& OBD, OSP, OSF, OHW, EVN \\
Sets that make reading Exabytes easier		& XBD, XAD \\
Nice sets to have (don't take much space)	& GEV, GXT, GBE, GBL \\
Nice sets to have (take much space)		& NAR, G6D, G7D \\ \hline
\end{tabular}

\subsection{Customizing the Overall Yohkoh Environment}\index{customizing the Yohkoh environment}

The Yohkoh Software system allows customization of both site and user level
IDL and operating system environments .  These features are optional, and 
many users may work effectively without any knowledge or implementation of 
these features.  On the other hand, as the Yohkoh system evolves at a given 
site, some of these features may be required to allow the Yohkoh system 
manager to tailor the system for the given site resources.  For example, the 
multitude of Yohkoh ancillary databases may be divided among multiple 
disks or machines to match local disk resources.  Sophisticated users may
use some of these features to further customize the IDL environment while 
still remaining within the Yohkoh framework.

\subsubsection{Use of Environmentals/Logicals for Yohkoh Software and Database}

All supported Yohkoh Software uses Unix environmentals and VMS logicals for 
data and database files.  The Yohkoh Software tree is also defined in terms of
environmental variables.  This allows relocation of Yohkoh Software and/or database
files to different paths, disks, or machines without any changes required 
in the source code and may occur transparently to the Yohkoh Software user.  It 
also minimizes restrictions on disk space allocation as different sites may 
organize the Yohkoh databases to suit the local resources.  

\subsubsection{Yohkoh environmental configuration files}

The Yohkoh OS and IDL environment is established through the execution of
several Unix script (or VMS command) files and IDL startup files.  A single
script acts to control the flow of script and setup execution.  In some cases,
multiple versions of scripts may exist in a general, site, and personal
areas to allow customization according to the following execution order.

\newpage
\begin{verbatim}
   Type         Path                    Function
1) GEN      $ys/gen/setup       setup default Yohkoh environment
2) SITE     $ys/site/setup      allow site modifications to the above
3) PERS     $HOME               allow personal modifications to the above
\end{verbatim}

The files described below are used to configure the Yohkoh environment.  
Files for which a SITE version is maintained may be used by the site Yohkoh 
Software manager to customize the site environment.  If no site version currently
exists, the corresponding file from gen (\$ys/gen/setup) may be used as 
an example or template (ie, copy to \$ys/site/setup and edit).  Note that
files in SITE are not overwritten by a Yohkoh Software upgrade so site changes
are not clobbered (unless requested).

\begin{verbatim}
File                    Function                         GEN    SITE    PERS

idl_setup       control flow of setup execution         yes     no      no
setup_paths     set top level database locations        yes(1)  yes     no
setup_dirs      define specific database paths          yes     yes     no
setup_alias     define OS symbols / aliases             yes     yes     no
setup_mail      define mailing list env                 yes     yes     no
setup_ysenv     other env/alias customization           yes     yes     yes
IDL_STARTUP     define Yohkoh IDL environment           yes     yes(2)  yes(3)
\end{verbatim}

\EEnumerate
\item the version in gen is not executed -- it is provided as a template 
      for site managers (some internal documentation)
\item The file \$ys/site/setup/IDL\_STARTUP (maintained by the site manager)
      is executed if it exists.
\item If user has the \$IDL\_STARTUP environmental defined, it will be executed
      following the Yohkoh-wide IDL\_STARTUP.  See the IDL manual for a description
      of IDL\_STARTUP.
\end{enumerate}

\subsubsection{setup\_paths -- Yohkoh Database and Reformatted Data Locations}\index{setup\_path}

The site version of setup\_paths may be used to split the Yohkoh database
across multiple disks or machines.  It is also used to define the areas
where the software will search for reformatted files.  It resolves top
level environmentals with site specific path names.  Local pathnames should
include NFS names (per fstab) if database or reformatted files are shared
among machines.  The file: \$ys/gen/setup/setup\_paths may be used as a template
if \$ys/site/setup/setup\_paths does not already exist.  It includes some 
internal documentation and examples.

\subsubsection{setup\_dirs}\index{setup\_dirs}
This script defines specific database environmentals
in terms of the top level environmentals defined in setup\_paths.  The
site version of this file is only required if the Yohkoh database is split.
As with setup\_paths, this is just a series of Unix setenv commands (or
VMS DEFINE commands). We recommend not including path references in this
file -- instead, the definitions should be in terms of the environmentals
(or logicals) defined in setup\_paths.

\subsubsection{setup\_alias}\index{setup\_alias}

This script provides a convenient method to define 
aliases or symbols which can be used by all site users.  This can provide a 
common OS environment at the site.

\subsubsection{setup\_ysenv}\index{setup\_ysenv}

The intended use of this script is to set up several Yohkoh environmentals
which control IDL startup.  These include setting defaults for X windows 
startup, message of the day display, fast startup, etc. Use the ``gen'' version
of the file (\$ys/gen/setup/setup\_ysenv) as a template and for some 
discussion of options.  The site manager may use the site version of this
file to change the distributed defaults.  If a user has a file with this
name in the HOME directory, it will be executed to supercede or supplement
the default and site environment.  Since it is just a script file which 
gets automatically executed during the Yohkoh startup, sophisticated users
may discover additional uses.  

\subsubsection{Multiple Software Host and Software Relocation}\label{multi_host}\index{multiple SW hosts}

Large, multi-user Yohkoh sites may consider maintaining multiple sets of 
the Yohkoh Software on different machines.  The main purpose of such a system is 
to allow software access from a backup system(s) in the event that the 
primary system is off-line (e.g., for maintenance, repairs, etc).  The 
Yohkoh Software distribution includes scripts which allow automatic selection
of a host.  The file: \$ys/site/setup/yspaths.config is 
a data file which is used by the Yohkoh startup script to dynamically
assign the location of the Yohkoh Software system.  This file is created 
during the installation procedure and initially just includes an entry for 
the machine and path where the Yohkoh Software is located. The script 
{\it ys\_newuser} (see Section~\ref{newuser}) copies this to the home directory of 
Yohkoh users to allow access to the Yohkoh setup scripts.  To define
additional hosts at a given site, the Yohkoh site manager can edit
the file: \$ys/site/setup/yspaths.config.  One line containing two fields
should be added.  The file is of the form:
\begin{verbatim}
        host1    path1          # original contents
        host2    path2          # second host added
        (host3)  (path3)
\end{verbatim}
Where {\it hostN} is the hostname and {\it pathN} is the path location of 
Yohkoh Software.  An example of this file is
\begin{verbatim}
        isass0  /0p/yohkoh
        isass2  /2p/yohkoh_sw
\end{verbatim}

	
\subsection{Initial Installation Using Exabyte Tapes}\index{Exabyte installations}

The large majority of users are currently performing initial Yohkoh Software 
installation via the network {install}.
If a network installation is not practical, send e-mail:
\begin{verbatim}
      TO:   software@isass0.solar.isas.ac.jp  
      SUBJ: tape installation procedure
\end{verbatim}
We offer an Exabyte ``boot up'' tape and installation instructions.

\subsection{VMS Installations}\index{VMS installations}

The Yohkoh Software System is designed to be compatible with the VMS
operating system and is currently running under VMS at several
locations, however, we recommend that Unix be selected for analysis of
Yohkoh data if possible. 

Currently, the VMS installation and upgrade process is not as automated 
as the Unix procedure.  At the time of publication, the BCS team was the
main user of the Yohkoh package under VMS, and it appears that they
will transition completely to Unix in the future.

The BCS team may be able to offer some guidance and VMS command files to 
assist in installing the Yohkoh system under VMS, however we can make no
promises that future Yohkoh software releases will be supported on VMS systems.
For more information, send e-mail and it will be forwarded appropriately.
\begin{verbatim}
      TO:   software@isass0.solar.isas.ac.jp  
      SUBJ: VMS installation procedure
\end{verbatim}

\subsection{Explanation of Software Release Version Numbers}\index{software releases}

Yohkoh Software version numbers are used for system maintenance and to facilitate
problem reporting and tracking.  The version numbers consist of two fields
of the form:

\begin{verbatim}
          YYMMDD.NN         Where:  YYMMDD = Date of Release
                                        NN = Major Release Number
\end{verbatim}

There are two types of ``Releases'', both of which are accompanied by an 
update to the date field.  A ``Major Release'', accompanied by an increment
of ``NN'', is generated when there is a major restructuring (deletions, 
renaming, moves) of the Yohkoh tree.   A ``Major Release'' requires that remote
sites execute a full upgrade (which copies over all of the {\it ys} tar files except {\it site}).
A ``Minor Release'' is generated when there are
a large number of additions to the tree, but not other restructuring.
Remote sites can upgrade to new minor release levels with an incremental
file -- a minor release is a method of maintaining the incremental files
at reasonable sizes.  Upgrades to new major and minor release levels are
both automatically accomplished by the upgrade scripts {\it ys\_install}.  Version 
numbers at remote sites are compared to the version numbers on the master 
copy (currently isass0) and the appropriate files are transferred and  
installed.
To determine the Yohkoh Software version you are running type:
%
\ultrixinputa{tail -1 \$ys/gen/setup/ys.version}
%
When reporting problems, please include the Software version number within
the message.
