--- loncom/build/Attic/CHECKRPMS.default	2002/09/05 17:36:39	1.4
+++ loncom/build/Attic/CHECKRPMS.default	2002/09/05 18:09:54	1.5
@@ -70,19 +70,20 @@ else
 
 # =================================================== GENERAL INITIAL VARIABLES
 # ---------------- The FTP servers (and their directory paths) to check against
-my @serverpaths_to_try=(
-   'mirror.pa.msu.edu/linux/redhat/linux/updates/',
-   'rufus.w3.org/linux/redhat/linux/updates/',
-   'distro.ibiblio.org/pub/linux/distributions/redhat/updates/',
-   'limestone.uoregon.edu/redhat/updates/',
-   'opnsrc.support.compaq.com/linux/redhat/updates.redhat.com/',
-);
+my @serverpaths_to_try = 
+  (
+    'mirror.pa.msu.edu/linux/redhat/linux/updates/',
+    'rufus.w3.org/linux/redhat/linux/updates/',
+    'distro.ibiblio.org/pub/linux/distributions/redhat/updates/',
+    'limestone.uoregon.edu/redhat/updates/',
+    'opnsrc.support.compaq.com/linux/redhat/updates.redhat.com/',
+  );
 
 # --------------------------------------------------- Determine RedHat version.
 my $RHversion = (split /\s/, `cat /etc/redhat-release`)[4]; # - 6.2 or 7.3 or ?
 
  # ------------------------------------------- Use check-rpms command this way.
-my $checkcommand='check-rpms '.$download.' --rpmuser www -ftp';
+my $checkcommand = 'check-rpms '.$download.' --rpmuser www -ftp';
 
 my $FTPSERVER; # ------------------------- the server portion of the serverpath
 my $FTPUPDATES; # ----------------------------- the actual update root location
@@ -91,82 +92,118 @@ my $goodoutput; # ----------------------
 my $reallygoodoutput; # ------------------------------- you are 100% up-to-date
 
 # ----------------------------------------- Find the check-rpms script location
-if (-e './check-rpms') {
-    $commandpre='perl ./';
-}
-elsif (-e 'loncom/build/check-rpms') {
-    $commandpre='perl loncom/build/';
-}
-else {
+if (-e './check-rpms')
+  {
+    $commandpre='perl ./'; # Use the check-rpms in the current directory.
+  }
+elsif (-e 'loncom/build/check-rpms')
+  {
+    $commandpre='perl loncom/build/'; # Use check-rpms int he loncom/build dir.
+  }
+else # Cannot find check-rpms, so abort.
+  {
     die("**** ERROR **** CANNOT FIND THE check-rpms SCRIPT\n");
-}
+  }
 
-$checkcommand=$commandpre.$checkcommand;
+# Define the overall check-rpms invocation based on the path to the check-rpms
+# command.
+$checkcommand = $commandpre.$checkcommand;
 
-# =============== Go through all the servers until a decent connection is found
+# ============== Go through all the servers until a decent connection is found.
+# Notify user of current action.
 print(<<END);
 THIS SCRIPT IS NOW PROBING SEVERAL FTP SERVERS....
 PLEASE BE PATIENT, THIS MAY TAKE A FEW MINUTES.
 END
 
-SERVERLOOP: foreach my $serverpath (@serverpaths_to_try) {
-    $serverpath=~/^(.*?)\//;
-    $FTPSERVER=$1;
-    print "Trying $FTPSERVER...\n";
-    `ping -c 1 $FTPSERVER 2>/dev/null`;
-    if ($?==0) {
-	print "$FTPSERVER found...\n";
-	`ncftpls ftp://$FTPSERVER`;
-	if ($?==0) {
-	    $FTPUPDATES="$serverpath$RHversion/en/os";
-	    print "$checkcommand $FTPUPDATES\n";
-	    if ($download) {
-		$|=1;
-		print `$checkcommand $FTPUPDATES 2>\&1`;
-		exit(0);
-	    }
-	    @rpms=`$checkcommand $FTPUPDATES 2>\&1`;
+SERVERLOOP: foreach my $serverpath (@serverpaths_to_try)
+  {
+    $serverpath=~/^(.*?)\//; # Pattern match the ip name.
+    $FTPSERVER=$1; # Set to the ip name.
+    print "Trying $FTPSERVER...\n"; # Notify user of attempts with the ip name.
+    `ping -c 1 $FTPSERVER 2>/dev/null`; # Ping ftp server (are you out there?).
+    if ($?==0) # If the ftp server can be pinged.
+      {
+	print "$FTPSERVER found...\n"; # Tell user the ftp server is found.
+	`ncftpls ftp://$FTPSERVER`; # Try to access server with ftp protocol.
+	if ($?==0) # If the ftp server can be accessed with the ftp protocol.
+          {
+	    $FTPUPDATES="$serverpath$RHversion/en/os"; # The full update path.
+	    # Print the check-rpms command that will be executed.
+	    print($checkcommand.' '.$FTPUPDATES."\n");
+	    if ($download) # Was CHECKRPMS run in download mode?
+              {
+		$|=1; # Try to send things immediately to stdout; err umm....
+		# Tell the user about the /tmp/loncapa_rpm_updates directory.
+		print('**** NOTE ****'.
+		      'To check the status of the download, you can '.
+		      'periodically inspect the contents of the '.
+		      '/tmp/loncapa_rpm_updates directory.  '.
+		      'Please be patient; this download may take a while.'.
+		      "\n");
+		# Do the download.
+		print(`$checkcommand $FTPUPDATES 2>\&1`);
+		# Tell the user about what action they need to take with the
+		# downloaded RPMs.
+		print('You may now wish to visit the /tmp/loncapa_rpm_updates'.
+		      ' directory and upgrade the RPMs.  '."\n".
+		      'If this is a critical server (it is currently being'.
+		      ' used for classes) and you do not know how to upgrade'.
+		      ' RPMs, you should consult someone who has experience '.
+		      'with the "rpm" command.'."\n");
+		exit(0); # Assume everything is okay and exit.
+	      }
+	    @rpms=`$checkcommand $FTPUPDATES 2>\&1`; # Read in list of RPMs.
+	    # Create a text string that can be pattern matched.
 	    my $rpmtext=join('',@rpms);
-	    if ($rpmtext=~/You do not seem to have a/) {
+	    if ($rpmtext=~/You do not seem to have a/) # No www?
+              {
 		print "You do not have a 'www' user on your system.\n".
 		    "Please add this user and try this command again.\n";
 		exit(1);
-	    }
-	    if ($rpmtext=~/This account is currently not/) { # ---------- uh-oh
+	      }
+	    if ($rpmtext=~/This account is currently not/) # ------------ uh-oh
+	      {
 		print "...strange error, moving on ($FTPSERVER)\n";
-	    }
-	    else { # ------------------------------------- the output is "good"
+	      }
+	    else # --------------------------------------- the output is "good"
+	      {
 		$goodoutput=$rpmtext;
-		unless (@rpms) {
+		unless (@rpms) # If there are no RPMs to update.
+		  {
 		    $reallygoodoutput=<<END;
 **** NOTE **** All RPMS on your system appear to be up to date.
 END
-		}
+		  }
 		last SERVERLOOP;
-	    }
-	}
-	print "...cannot establish an ftp session with $FTPSERVER\n";
-    }
-    else {
+	      }
+	  }
+	print('...cannot establish an ftp session with '.$FTPSERVER."\n");
+      }
+    else
+      {
 	print "...cannot find $FTPSERVER on the network\n";
-    }
-}
-if (!$goodoutput) {
+      }
+  }
+if (!$goodoutput) # If never received any useable output, assume "no server".
+  {
     print "**** ERROR **** Cannot find a working ftp server.\n";
     exit(1);
-}
-elsif ($reallygoodoutput) {
+  }
+elsif ($reallygoodoutput) # Everything is peachy keen and up-to-date already.
+  {
     print $reallygoodoutput;
-}
-else {
-    my $rpmcount=scalar(@rpms);
-    print(<<END);
+  }
+else # There are RPMs that need to be updated; show list to user.
+  {
+    my $rpmcount=scalar(@rpms); # Count up size of RPM list.
+    print(<<END); # Print out an advisory warning to user.
 **** WARNING **** You need to update at least $rpmcount RPMS shown in
 the list below.  THIS IS IMPORTANT FOR SECURITY.
 
 END
-    print $goodoutput;
-    print(<<END);
+    print $goodoutput; # Output the RPM list.
+    print(<<END); # Output instructions to user about taking action.
 
 Please visit ftp://$FTPUPDATES
 and download the RPMS you need.
@@ -175,4 +212,4 @@ visit http://www.rpm.org/max-rpm/.
 To automatically download these RPMs to /tmp/loncapa_rpm_updates/,
 run the CHECKRPMS command as "./CHECKRPMS --download"
 END
-}
+  }