--- loncom/lond	2012/03/26 11:03:34	1.487
+++ loncom/lond	2012/04/11 01:07:18	1.488
@@ -2,7 +2,7 @@
 # The LearningOnline Network
 # lond "LON Daemon" Server (port "LOND" 5663)
 #
-# $Id: lond,v 1.487 2012/03/26 11:03:34 foxr Exp $
+# $Id: lond,v 1.488 2012/04/11 01:07:18 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -60,7 +60,7 @@ my $DEBUG = 0;		       # Non zero to ena
 my $status='';
 my $lastlog='';
 
-my $VERSION='$Revision: 1.487 $'; #' stupid emacs
+my $VERSION='$Revision: 1.488 $'; #' stupid emacs
 my $remoteVERSION;
 my $currenthostid="default";
 my $currentdomainid;
@@ -3245,6 +3245,12 @@ sub dump_profile_database {
 #                                             that is matched against
 #                                             database keywords to do
 #                                             selective dumps.
+#                               range       - optional range of entries
+#                                             e.g., 10-20 would return the
+#                                             10th to 19th items, etc.  
+#                               extra       - optional ref to hash of
+#                                             additional args. currently
+#                                             skipcheck is only key used.   
 #   $client                   - Channel open on the client.
 # Returns:
 #    1    - Continue processing.
@@ -3279,12 +3285,26 @@ sub dump_with_regexp {
     if ($hashref) {
         my $qresult='';
 	my $count=0;
+#
+# When dump is for roles.db, determine if LON-CAPA version checking is needed.
+# Sessions on 2.10 and later will include skipcheck => 1 in extra args ref,
+# to indicate no version checking is needed (in this case, checking occurs
+# on the server hosting the user session, when constructing the roles/courses 
+# screen).
+# 
         if ($extra ne '') {
             $extra = &Apache::lonnet::thaw_unescape($extra);
             $skipcheck = $extra->{'skipcheck'};
         }
         my @ids = &Apache::lonnet::current_machine_ids();
         my (%homecourses,$major,$minor,$now);
+# 
+# If dump is for roles.db from a pre-2.10 server, determine the LON-CAPA   
+# version on the server which requested the data. For LON-CAPA 2.9, the  
+# client session will have sent its LON-CAPA version when initiating the
+# connection. For LON-CAPA 2.8 and older, the version is retrieved from
+# the global %loncaparevs in lonnet.pm.
+# 
         if (($namespace eq 'roles') && (!$skipcheck)) {
             my $loncaparev = $clientversion;
             if ($loncaparev eq '') {
@@ -3302,8 +3322,18 @@ sub dump_with_regexp {
                     my $cdom = $1;
                     my $cnum = $2;
                     unless ($skipcheck) {
-                        my ($role,$end,$start) = split(/\_/,$value);
-                        if (!$end || $end > $now) {
+                        my ($role,$roleend,$rolestart) = split(/\_/,$value);
+                        if (!$roleend || $roleend > $now) {
+#
+# For active course roles, check that requesting server is running a LON-CAPA
+# version which meets any version requirements for the course. Do not include
+# the role amongst the results returned if the requesting server's version is
+# too old.
+#
+# This determination is handled differently depending on whether the course's 
+# homeserver is the current server, or whether it is a different server.
+# In both cases, the course's version requirement needs to be retrieved.
+# 
                             next unless (&releasereqd_check($cnum,$cdom,$key,$value,$major,
                                                             $minor,\%homecourses,\@ids));
                         }
@@ -3326,6 +3356,13 @@ sub dump_with_regexp {
 	    }
 	}
 	if (&untie_user_hash($hashref)) {
+#
+# If dump is for roles.db from a pre-2.10 server, check if the LON-CAPA
+# version requirements for courses for which the current server is the home
+# server permit course roles to be usable on the client server hosting the
+# user's session. If so, include those role results in the data returned to  
+# the client server.
+#
             if (($namespace eq 'roles') && (!$skipcheck)) {
                 if (keys(%homecourses) > 0) {
                     $qresult .= &check_homecourses(\%homecourses,$udom,$regexp,$count,
@@ -7437,6 +7474,20 @@ sub get_usersession_config {
     return;
 }
 
+#
+# releasereqd_check() will determine if a LON-CAPA version (defined in the
+# $major,$minor args passed) is not too old to allow use of a role in a 
+# course ($cnum,$cdom args passed), if at least one of the following applies: 
+# (a) the course is a Community, (b) the course's home server is *not* the
+# current server, or (c) cached course information is not stale. 
+#
+# For the case where none of these apply, the course is added to the 
+# $homecourse hash ref (keys = courseIDs, values = array of a hash of roles).
+# The $homecourse hash ref is for courses for which the current server is the 
+# home server.  LON-CAPA version requirements are checked elsewhere for the
+# items in $homecourse.
+#
+
 sub releasereqd_check {
     my ($cnum,$cdom,$key,$value,$major,$minor,$homecourses,$ids) = @_;
     my $home = &Apache::lonnet::homeserver($cnum,$cdom);
@@ -7488,6 +7539,17 @@ sub releasereqd_check {
     return 1;
 }
 
+# 
+# get_courseinfo_hash() is used to retrieve course information from the db
+# file: nohist_courseids.db for a course for which the current server is *not*
+# the home server.
+#
+# A hash of a hash will be retrieved. The outer hash contains a single key --
+# courseID -- for the course for which the data are being requested.
+# The contents of the inner hash, for that single item in the outer hash
+# are returned (and cached in memcache for 10 minutes).
+# 
+
 sub get_courseinfo_hash {
     my ($cnum,$cdom,$home) = @_;
     my %info;
@@ -7513,6 +7575,25 @@ sub get_courseinfo_hash {
     return;
 }
 
+#
+# check_homecourses() will retrieve course information for those courses which
+# are keys of the $homecourses hash ref (first arg). The nohist_courseids.db 
+# GDBM file is tied and course information for each course retrieved. Last   
+# visit (lasttime key) is also retrieved for each, and cached values updated  
+# for any courses last visited less than 24 hours ago. Cached values are also
+# updated for any courses included in the $homecourses hash ref.
+#
+# The reason for the 24 hours constraint is that the cron entry in 
+# /etc/cron.d/loncapa for /home/httpd/perl/refresh_courseids_db.pl causes 
+# cached course information to be updated nightly for courses with activity
+# within the past 24 hours.
+#
+# Role information for the user (included in a ref to an array of hashes as the
+# value for each key in $homecourses) is appended to the result returned by the
+# routine, which will in turn be appended to the string returned to the client
+# hosting the user's session.
+# 
+
 sub check_homecourses {
     my ($homecourses,$udom,$regexp,$count,$range,$start,$end,$major,$minor) = @_;
     my ($result,%addtocache);
@@ -7589,6 +7670,12 @@ sub check_homecourses {
     return $result;
 }
 
+#
+# useable_role() will compare the LON-CAPA version required by a course with 
+# the version available on the client server.  If the client server's version
+# is compatible, 1 will be returned.
+#
+
 sub useable_role {
     my ($reqdmajor,$reqdminor,$major,$minor) = @_; 
     if ($reqdmajor ne '' && $reqdminor ne '') {