------------------------------------
SCRIPT MAINTENANCE - Stephen Randall
------------------------------------

WARNING - Unless explicitly advised by this document, changes to the script and its
    infrastructure [file/folder layout, website implementation, etc.] should be avoided.

1. OVERVIEW

    20DayAuto.app lives in /Applications, and is run by cron every morning at 11AM.

    To edit the application, edit 20DayAuto.scpt. This file lives in
    ~/local_chems_files. When you edit the script, make sure to not only save
    it as a script, but as 20DayAuto.app in /Applications [with no options checked].

    When run, the script calls a Python script that checks a remote server for new data
    files. If it finds any, the main script then runs a couple IDL routines on the 20
    day periods that include those files. Both spectrograms [& flux files] and mass per
    charge vs. time plots [& .xdr files] are created in a temporary folder. The plots
    are then converted to PDF files, and all the files are uploaded to the appropriate
    place on the Cassini server. The script finishes by cleaning up after itself, moving
    all local files to the right spot and deleting the remnants of the temporary folder.
    
    In addition, the website is written so that once the new files are pushed to the
    server, they will immediately be accessible from the drop-down menus on the page.
    
    [For additional information, check the notes at the head of the script. It may also
    be helpful to consult the event log of script 20DayAuto_events.log, although that
    should only be consulted in case of error.]
    
2. STAYING UP TO DATE
    
    The website plots include ephemeris data. To access that data, they read in two
    ephemeris files listed in /Volumes/HD 2/local_chems_files/defaults.txt. However,
    these files will need to be updated every year.
    
    First, go to http://www-pw.physics.uiowa.edu/~jbg/cas.html. In the time range fields
    enter 2004//001 00:00:00 in the first and 20XX//001 00:00:00 in the second, where
    XX represents the maximum year. So if you're updating this at the end of 2014, then
    the second box would have 2016//001 00:00:00 so that you'd have all the data you
    needed for the upcoming year.
    
    Then set the time interval to 1800 seconds [30 minutes]. Leave the origin as Saturn
    Barycentric and the observer as Cassini. Don't change Saturn's radius either.
    
    To get the first file, change the coordinate system to Equatorial and click Submit.
    This will [slowly] load a text file for you. When it's done, save it as a text file
    with a name like 2004-20XX_EQU_30min.txt [again substituting your year for XX].
    Then do the same for the Geographic coordinate system [naming your file with a
    GEO instead of an EQU]. Now move both of these files to /Volumes/HD 2/Program Files
    and delete the ones that you're replacing. Be careful to delete the right ones!
    
    The final step is to change the name of the files in
    ~/local_chems_files/defaults.txt to the files you just created. This is
    very important; this is how the script knows which ephemeris files to use!
    
3. ISSUES

    Sometimes, the script will crash without getting very far into the IDL portion. There
    is an issue with the IDL license server crashing on the PowerMac, so to check if this
    is your issue simply open a new Terminal window and type in IDL. If you get a warning
    about IDL not able to connect to a license server and instead entering demo mode, then
    this is your error. To fix it, ssh into the PowerMac (there's a sshpm alias to do this;
    the password is 'dione'), open a Terminal window, enter 'ridl', and when prompted for a
    password, 'dione'. Using IDL should now be back to normal.

    All other possible issues are addressed at the head of the script. If issues persist,
    consult the event log. The most probable cause is that the files referenced don't exist,
    although it is possible that the undefined behavior of the script in the event of early
    termination is having unexpected consequences. In that case, manual cleanup may be
    required and a CAREFUL revision of the script may be necessary.
    
    Note: It's assumed that your error isn't an out of date ephemeris file list. If that's
    the case, please read section 2.
    
---------------------
Stephen Randall, 2012
---------------------