
		        AutoFtp Version 3.0
			 (Previously GET21)

		     	     FreeWare

	 		    Mingqi Deng
			    July 6, 1989


			     Contents
	1) .......................................... Description
	2) .............................. Contents of Version 3.0
	3) ............................................... Set Up
	4) ............................................ Execution
	5) .............................................. History
	

   AutoFtp is a UNIX Bourne shell program that automates the ftp processes
to get a number of files from a site that allows ftp file transfer. It 
will repeatedly try for a good connection until all the files requested
are transferred.  A user need not baby-sit the ftp process, thus is 
relieved from the frustration of numerous unsuccessful ftp attempts. 

   The program is based on GET20 ftp script by Ferd Boundick, and was 
originally written for my own use after a long suffering from ftp into 
SIMTEL20.  It has been fully tested. This release has the following new
features:

   1) A bug that allows a request for a non-existing file to go on
      forever has been fixed.
   2) Users now can run a process of name [*]sleep[*] while running the
      autoftp without having any interferences in between. This is
      because the new version of autoftp uses process ID in its actions
      instead of their names as in the old version.
   3) Changing local directory during ftp and getting directory list are
      supported now.
   4) This versio will not affect the .netrc file. It simply avoids
      using it.
   5) A randomized retry timing sequence has been implemented. In the 
      previous version, there is a chance that several copies of the 
      auto-ftp can get into synchrony. Consequently, none of them can get 
      logged into SIMTEL20. This release minimizes this possibility and
      also smoothes the load at SIMTEL20 thus all users will have a better
      chance to login to SIMTEL20 on the average.
   6) More and better error handlings are implemented. In particular, 
      it will complain if the ALARM is too small for a large file. 
   7) The awkward run.sh file in release 2.1 has been replaced by a 
      simpler input file.
   8) The number of working files is reduced to 5 for the entire run
      from 5 for each file requested. Moreover, there is just one
      file for the entire ftp history instead one for each file
      requested.

   This release is a complete rewriting of the previous version, as 
a result of my discussion with Keith Peterson at SIMTEL20. The major 
part of the shell script has been replaced by three C programs. This 
provides a more natural and better program structure, thus more freedom
in analyzing each ftp session.

   This is a freeware, meaning that it can be copied and used freely. 
But the programs must NOT be sold for profit.

   Problems, improvements, comments and suggestions can be sent to the
author at:

E-mail:				Postal Mail:

  deng@shire.cs.psu.edu	          333 Whitmore Lab
  deng@psuvaxs.bitnet		  Computer Science Department
  deng@psuvaxs.uucp		  The Pennsylvania State University
				  University Park, PA 16802
========================================================================

All of the files contained in version 3.0 are:

   	README        this file
   	autoftp30.sh  the main program
   	nextfile.c    used by autoftp30.sh to prepare for an ftp attempt
   	ftpget.c      used by autoftp30.sh for one ftp attempt
   	checkout.c    used by autoftp30.sh to analyze an ftp's result
        sample.dat    a sample input data file for autoftp30.sh,
		      consisting of a name list of the requested files
		      to be transferred from WSMR-SIMTEL20.ARMY.MIL.

========================================================================

Set Up:

  1. Do a "man ftp" to see if the constant TENEX defined on line 49 in 
     nextfile.c needs to be adjusted. Refer to Note #2 in the head 
     comment block in nextfile.c for more instructions.

  2. Compile the three C programs by typing:

           cc -o checkout checkout.c
           cc -o ftpget   ftpget.c
           cc -o nextfile nextfile.c

     This will produce three executable files named "checkout", "ftpget"
     and "nextfile".

     *NOTE*: Each of the programs has a "Note" section in their head
	     comment block that provides information about the pre-
	     defined constants used in the program. If anything goes
	     suspiciously, adjust them properly.

  3. Place the three compiled C programs in a directory of your choice.
     However, if the directory is not named "bin" and in your home 
     directory, you will have to adjust the shell variable FtpLibDir
     in autoftp30.sh (cf. autoftp30.sh). The default is $HOME/bin. For
     example, if your home directory is "/usr/usr/deng", then the 
     default directory is "/usr/usr/deng/bin".

  4. Adjust the following three shell variables in autoftp30.sh:

     		RemoteHost, ALARM, FtpLibDir

     Instructions and examples are given in autoftp30.sh.
   
     *NOTE*: You may have to change LocalHost in autoftp30.sh (on the
	     lines next to RemoteHost) from "guest" to your machine's
	     address, if login to SIMTEL20 is always denied. Refer
	     to autoftp30.sh.

  5. If you have any executable files of your own of the following names:

         cat chmod cp echo expr grep mv rm sed sh sleep test

     then rename them using different names. These are UNIX commands'
     names, thus should not be taken over by a user's own executables.

========================================================================

Execution:

  1. Prepare an input file that contains a name list of files you want
     to get from a remote host (cf. sample.dat). The file consists of 
     two types of lines: device-directory line (DDL) and file-line (FL).

     a) Device-directory line (DDL):
        Format:   
		  -d|c|l  device_directory_name [dir_file]
	   where 
	      d,c,l are flags indicating a DDL line:
	        "-d" :- the name on that line is a device_directory_name
			that defines the directory where a subsequently
			requested file resides, at the remote host.
			This flag requires one name after the option.
	        "-c" :- a request to change the local directory so that
			requested files will be put into that directory.
			The name on that line is an existing local
			directory. This flag requires zero or one name 
			after the option. If no name is followed, then
			a change to the home directory is performed.
	        "-l" :- a request to obtain a directory listing for the
			remote directory named on that line. This flag
			requires two names after the option: the name
			of the remote directory, and the name of the
			file to which the listing is to be stored.
        Example:
		-d PD1:<MSDOS.DSKUTL>
		-l PD:<ANONYMOUS> root.dirlst
 		-c download
        Function:
            A "-d" DDL line defines the directory from which all files 
	        on the subsequent file-lines, up to a new "-d" DDL line,
		are to be fetched.
            A "-l" DDL line gets a directory listing to aid the download.
	    A "-c" DDL line changes the local directory PERMANENTLY upto
		the next "-c" DDL line to help organize the downloaded 
		file.
 
      *NOTE*: PS:<ANONYMOUS> directory contains general information
	      and many directory lists at SIMTEL20. New users are
	      particularly encouraged to look into this directory.

     b) File lines (FL):
         Format:
 	          [-a|b|8|t] RemoteFile [LocalFile]
             where:
                a,b,8,t are flags:
   	  	   "-a" :- a file is to be transferred in ASCII mode 
   		   "-b" :- a file is to be transferred in binary mode 
   		   "-t" or "-8" 
		        :- a file is to be transferred in tenex mode
		 	   (32->8 bits conversion, which is the mode
			    you should use if you are ftp'ing into
			    SIMTEL20 from a DEC VAX or a SUN)
		   The option can be omitted (indicated by the bracket
		   "[","]".) If it is omitted, the default is "-t" 
		   (identical to "-8").
 	        RemoteFile is the requested file's name at the remote host
 	        LocalFile (optional) is the file name under which the 
		   RemoteFile is to be received at the local machine.
                   If it is omitted, the default is RemoteFile.
         Examples:
		-a 	00-INDEX.TXT  DSKUTL.IDX
		-8 	BACKEZ.ARC
		DISCACHE.ARC	CACHE.ARC
		TIMEPARK.ARC
		-a	VDSK.ASM
	 Functions:
	      An FL line specifies the name of a requested file (whose
	      directory is specified by a preceding DDL line), and the
	      transfer mode for the file.

      *NOTE* 1) An option on an FL line must NOT be omitted if the 
		RemoteFile starts with a "-". And only the first letter
		of an option is effective.
             2) Options and names are separated by blanks or TABs.
		No other delimiters can be used. 
	     3) There can be more than one blank or TAB between the 
		options and names. 
	     4) There can be blanks or TABs before an option. But 
		nothing should be inserted between "-" and a flag.
	     5) A DDL or FL line can appear anywhere in an input file
		though some sequence may not be meaningful.
	     6) The input file may contain any number of blank line
		anywhere. They are simply ignored.
	     7) The file name on an FL line, and directory names on a 
		"-d" or "-l" DDL line can be either in lower or upper 
		case. This makes no difference as far as autoftp30.sh is
		concerned. However, all options must be in lower case.
	
  2. Run the program: 
     There are two ways:
        i) run as a background job (strongly recommended) by typing:
	  	sh autoftp30.sh in_file &
        ii) run as a foreground job (not recommended) by typing: 
	  	sh autoftp30.sh in_file 
     where in_file is the name of the input file prepared as above.

     If the program is run as a background job (indicated by "&" at the
     end of the line, do a "man sh" for more information), then the 
     terminal on which this command is issued is freed right away. Thus
     the user can immediately issue whatever other commands he may want.
     Otherwise, the terminal is taken by the autoftp process, and the 
     user has to wait until its completion (upto several hours) before 
     he can issue any other command.

     While the program is running background, its status can be checked
     by issuing "ps -xg" (do a "man ps" for more information). It can
     be terminated, if the user wishes, by "kill -9 pid" where "pid" is
     the process id, shown by "ps", of the very process to be terminated
     (do a "man kill" for more information.)

  3. The results are a number of files: the files received, and 6 working
     files created by the execution. Among the 6 files, 5 of them only
     exist during the execution.

     a) XXXXXmsg :-   (XXXXX is a process ID number, as shown by a "ps"
		       command in UNIX.)
          This is the only working file that is usually left after the
       execution and the only working file the user should be concerned
       with. It contains the history of the ftp attempts. Check this file
       to see if each requested file is successfully transferred. A file
       transfer fails only when it is too large or has a wrong name,
       which will be reported in this file. (If your local system goes
       down, or the process is killed by a "kill" command, the transfer
       will of course be interrupted and no message will be reported in
       these cases.)

     b) XXXXXstdout, XXXXXstderr, XXXXXftp.script, XXXXXtmp :-   
		(XXXXX is again a process ID number, as shown by a "ps"
		 command in UNIX.)
          These files are temporary working files. XXXXXtmp only exists
        momentarily. If the autoftp30.sh terminates gracefully, they will
        all be erased upon its completion. Otherwise, the user can always
        delete them manually (this happens if the autoftp30.sh is killed
        by a kill command of UNIX, the local machine went down in the
        middle of the execution, or due to a situation unanticipated by
        the AutoFtp.)

========================================================================

History:

  Version 2.1 (GET21), by Mingqi Deng, Jan. 12, 1989
  --------------------------------------------------

     1. Unlike Get20, Get21 will not give up when connection is refused
        or disrupted. Therefore the users will be relieved from the
        frustration of running it over and over again for a good
        connection.
     2. To get out from a silent connection, there is a time out for 
	each connection. The default is one hour. For large files or 
	slow communication lines, the user is advised to increase the 
	value.
     3. A separate shell program sample is included for transferring
        multiple files from SIMTEL20. 

-----------------------------------------------------------------------

Version 2.0 (GET20) by  : Ferd Boundick
---------------------------------------

   date written: some time in 1983
   modification: 22 March 84

     1. ftp modes are referred to as "ascii, binary, and tenex"
     2. The option -8 is identical to -t for tenex (36->8) transfers.
     3. Remote host name now is stored in the variable "RemoteHost".
     4. Local host name now is stored in the variable "LocalHost" for
	  remote login usage.
