Spin Utility Documentation -------------------------- Revision: 11/10/99 Purpose of the Spin utility: ---------------------------- Create or update a trigger documentation file by placing a copy of the file - onto the main trigger documentation ftp/http server at MSU (which is the primary source for Run II trigger documentation) - and onto the (separate) arhival ftp site at MSU (with a modified file name for versioning purpose) - and onto the mirror fnal ftp directory (not yet implemented) (to guarantee access to the documentation at all times while at DZero) - while automatically placing the file in its correct directory location (the proper target directory is deduced from the file name alone) An additional goal of the Spin utility is to allow the user to update the trigger documentation from any PC or Sun Workstation (or other platform) located at MSU or Dzero (or elswhere). The Spin utility is written using the Python scripting language which is implemented on a variety of operating systems including Windows NT and Solaris (available for free from www.python.org). The user would typically view and get a copy of the latest version of a particular documentation file with a Web Browser (e.g. Netscape) accessing http://www.pa.msu.edu/hep/d0, then, after locally modifying the file, use Spin to automatically put this updated version back in the directory where the original version came from. If necessary the user can obtain the spin python script from the /hep/d0/ftp/spin directory on the same web server. To remember the assigned target location of each trigger documentation file as well as its last modification date and version number, Spin uses a Spin$Map file also located on the primary home ftp site. Spin retrieves, updates and replaces this Spin$Map file every time a documentation file is being updated. The files are indexed in the Spin$Map by their file name only. The target directory name is part of a file entry but cannot be used in the key name since any file can be updated from any local directory. It is thus strongly recommended (but not required) to use distinct file names for all trigger documentation files. Ambiguities will be pointed out by spin and the user will be ask to decide which of the possible destinations is the correct one, which somewhat defeats the purpose of this utility. Detailed steps of the Spin script: - get a listing of the default or specified directory - if no target file was specified on the command line find the most recently modified file in the default or specified directory then ask the user for confirmation or for a different file name - verify that the file name corresponds to an existing file - if the file name is not all lowercase, notify the user it will be made so - open an ftp connection to the home ftp site ask user for password to access the trigger account on this machine - open an ftp connection to the archival ftp site ask user for password to access the trigger account on this machine offers if password is identical as previous one. - If either one of these two connection attempts fails, abort. - Retrieve the spin$map file from the home ftp site and parse its records looking for entries for (1) the target file (2) the spin pyhton script and (3) the spin$map itself - abort if no record is found for the spin script or the spin$map - compare the version number defined in the first line of the running spin script to the version number for the spin script found in the spin$map and warn that a more recent script exists if necessary with the recommended option to bail out and obtain the newest spin script. - It is a special case if it is the spin script itself that is being updated in order to insure that the internal version number recorded in a variable of the spin python script matches the version number it will be archived as and tagged as in the spin$map. A temporary local copy of spin.py will be created where the first line is overriden to specify the desired version number. - If no record was found for the target file in the spin$map, offer the option to create a new one - Summarize and display all the known information about the file to update and ask for final confirmation - Send the target file to the home ftp site, but first verify that the target directory exists and recursively create each subdirectory level if necessary asking for confirmation each time. - Send the target file to the archival ftp site using the same subdirectory path while creating subdirectories as needed without asking, but append the version number to the file name in order not to overwrite older versions of the same file (e.g. file_name.file_ext.0006) - send the updated spin$map file to the home ftp site - send the updated spin$map file to the archival ftp site, also with its updated version number appended to the spin$map file name Misc Notes: - spin forces all file names and directory to lowercase before saving them - a file entry in the spin$map consists of the file's name used as the key to locate the record the file's target directory a Y/N flag specifying the file was successfully archived the last time it was updated with spin (not yet used) a Y/N flag specifying the file was successfully copied to fermilab the last time it was updated with spin (not yet used) the file version number as recorded on the archival site the date and time of the last time it was updated with spin - it seems like the getpass python module used to ask for user password without echoing the password entered on the keyboard does not work properly on Solaris - there is a special command line option spin -generate_map to create a new spin$map file on the local node just by scanning the file on the ftp home site. All files are currently registered with version 0000, and this option will later be upgraded to query the archival ftp site and find the proper latest version number. Spin Usage: ----------- Type the following command from a directory containing the source file to update and the spin script or specify explicit path names python spin.py for an explicit filename or python spin.py will find the last modified file in the current directory and ask for source file name python spin.py -binary|-b [filename] will force binary ftp transfer mode python spin.py -ascii|-a [filename] will force ascii ftp transfer mode python spin.py -new|-n [filename] will force a new spin$map entry python spin.py -help|-h|-?|? will display this information python spin.py -doc|-d will display the spin documentation The spin.py python script can be downloaded from http://www.pa.msu.edu/hep/d0/ftp/spin/spin.py or ftp://www.pa.msu.edu/pub/d0/spin/spin.py On a machine with the DZero NT software installed first type the following setup commands bash at the MS-DOS command prompt then setup python at the bash prompt then python spin.py... Depending on the version of python installed on the local machine, you may need to also copy the getpass.pyc file from the same area of the trigger documentation home ftp site and place this file in the same directory as the spin python script. Example: -------- C:\users\Python\spin> python spin.py c:/users/python/spin/Spin_Documentation.Txt . DZero Trigger Run II Spin Command File ------------- Web Documentation Update Utility V0003 ------------- . Spin> Warning: By convention we only use lowercase letters in file names. All files on the FTP sites have lowercase file names. Your file name will be converted to lowercase during transfer. . Connecting to Home FTP Server Enter Password for trigger on www.pa.msu.edu : ftp/opening as 220 kepler FTP server (SunOS 5.7) ready. . Connecting to Archival FTP Server (Enter for same pwd as previous) Enter Password for trigger on ribbit.pa.msu.edu : ftp/opening as 220 FTP server (Hummingbird Communications Ltd. (HCLFTPD) Version 5.1) ready. . ftp/from _getting . Spin> Attention Please: . Could not find an entry for in spin$map Would you like to create a new Entry? . Spin New Entry [Y]/N : . What is the Desired Target Directory for Note: if it is NOT an HTML document, it should probably start with ftp/ Example: . Enter Target Directory : ftp/spin . Spin> Confirmation Please: . Ready to Update : c:/users/python/spin/Spin_Documentation.Txt On FTP Server : www.pa.msu.edu using ftp Transfer Mode : ascii To Directory : www/ftp/spin/ To File Name : spin_documentation.txt Last Registered Version : 0000 Last Registered on : Mon-26-Jul-1999-18:01:23 WWW Access will be on : http://www.pa.msu.edu with File Name : /hep/d0/ftp/spin/spin_documentation.txt . Spin Go [Y]/N : . Updating Home FTP Server ftp/onto _putting . Updating Archival FTP Server ftp/onto _putting . Now Updating the spin$map ftp/onto _putting ftp/onto _putting . . Done.