pshare update procedure -- interim document -- dmc 3 Feb 2002
=============================================================

This document describes how to update the new pshare: the unix-based 
TRANSP run production system.  It is intended for use at PPPL by those
responsible for the Fusion Collaboratory TRANSP production system.

tshare
======
The pshare account also contains the sources for "tshare" which can be
updated separately from the regular pshare production system.  To update
tshare,
  - source ~/tshare_setup.csh
  - follow the instructions for updating pshare but instead execute the
    scripts,
      tshare_update_prep
      tshare_update_execute

These scripts verify that $TRANSPROOT points to the expected location of
the sources to prevent the accidental update with the wrong environment.
The tshare update will also update the NTCC libraries from xshare.


Step-by-step Instructions.
==========================

0.  Verify last night's xshare build had no errors. 


1.  Logon as "pshare" onto portal. [ for tshare, source ~/tshare_setup.csh]


2.  Execute the command:

    > pshare_update_prep    [ or tshare_update_prep ]

    This will verify that the update script is being run on a sunfire, RHEL4 64 bit
    machine.  It also checks whether the file "~/pshare_update.in_progress" exists.
    This file along with "~/tshare_update.in_progress" act as lock files to prevent
    the simultaneous update of pshare and tshare as the pbs queues must be held
    at the beginning and released at the end of the updates.

    It will also post a message to the Fusion Grid Monitor (FGM) 
    announcing that a "PPPL TRANSP rebuild" is running.  Finally it will 
    SHUT DOWN the TRANSP production queue in such a way that old runs 
    continue to run, but new runs are prevented from starting.


3.  By hand:
    > cd $TRANSPROOT       # don't use cdroot (it might point to the wrong place)
    > pwd                  # verify you are updating the right cvs sources
    > cvs -q update -dPA   # update quietly, add directories, prune empties, ignore sticky tags
        check and fix conflicts
        look for modified files under pshare and 'cvs commit' them
    
    make sure that "pshare" & "xshare" represent the same version of 
    the TRANSP source code.
    > cvs -nq update

4.  Execute the command

    > pshare_update_execute  [ or tshare_update_execute ]

    which will do the following:

       a) run the makefile generator ("code_daemon nolink").
       b) run a code_daemon nolink to check the build, run the code
          generators and build the makefiles
       c) run a code update ("linkcheck everything") on portal.
          if UPDATE_DOMAINS was defined start linking on the 
          external domains 
       d) if JCODESYSDIR is defined, build java code and deploy
          to /p/beast/java/jcodesys (deployment not done for tshare)
       e) when (d) finishes, verify that a core set of executables
          exist: {transp, dbtran, pretr, trdat, plabel, mdsplot}.
       f) if not all executables are present: exit with error message.
       g) if all executables exist:
            1) send the note "PPPL TRANSP rebuild completed" to FGM.
            2) restart the production queue.
            3) delete the lock file ~/p(t)share_update.in_progress

4a. Be patient.  With "viz" in UPDATE_DOMAINS the portal process will finish
    and show "%linkcheck - normal completion" while waiting for viz to
    complete.

5.  If (4) was successful, and users' queued runs have been held, these
    will all commence when the queue is restarted.  Since a new version
    of the TRANSP system is now operating, new failures could happen, and
    they may show up very quickly, so, be alert.

5b. If (4) was not successful (tested by checking for the executables transp,
    dbtran, pretr, trdat, plabel, mdsplot) then the production queue is not
    restarted.  The pshare distribution must be fixed by hand so that linkcheck
    succeeds.  When this has been completed execute,
      
      >pshare_update_finish  [ or tshare_update_finish ]

    to restart the production queue and delete the lock file.