--- loncom/lonnet/perl/lonnet.pm	2012/04/25 21:22:15	1.1166
+++ loncom/lonnet/perl/lonnet.pm	2012/05/18 15:31:40	1.1168
@@ -1,7 +1,7 @@
 # The LearningOnline Network
 # TCP networking package
 #
-# $Id: lonnet.pm,v 1.1166 2012/04/25 21:22:15 raeburn Exp $
+# $Id: lonnet.pm,v 1.1168 2012/05/18 15:31:40 www Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -97,6 +97,7 @@ use File::MMagic;
 use LONCAPA qw(:DEFAULT :match);
 use LONCAPA::Configuration;
 use LONCAPA::lonmetadata;
+use LONCAPA::Lond;
 
 use File::Copy;
 
@@ -4673,7 +4674,9 @@ sub rolesinit {
             my ($area,$role)=split(/=/,$entry);
 	    $area=~s/\_\w\w$//;
             my ($trole,$tend,$tstart,$group_privs);
-	    if ($role=~/^cr/) { 
+	    if ($role=~/^cr/) {
+# Custom role, defined by a user 
+# e.g., user.role.cr/msu/smith/mynewrole
 		if ($role=~m|^(cr/$match_domain/$match_username/[a-zA-Z0-9]+)_(.*)$|) {
 		    ($trole,my $trest)=($role=~m|^(cr/$match_domain/$match_username/[a-zA-Z0-9]+)_(.*)$|);
 		    ($tend,$tstart)=split('_',$trest);
@@ -4681,11 +4684,14 @@ sub rolesinit {
 		    $trole=$role;
 		}
             } elsif ($role =~ m|^gr/|) {
+# Role of member in a group, defined within a course/community
+# e.g., user.role.gr/msu/04935610a19ee4a5fmsul1/leopards
                 ($trole,$tend,$tstart) = split(/_/,$role);
                 next if ($tstart eq '-1');
                 ($trole,$group_privs) = split(/\//,$trole);
                 $group_privs = &unescape($group_privs);
 	    } else {
+# Just a normal role, defined in roles.tab
 		($trole,$tend,$tstart)=split(/_/,$role);
 	    }
 	    my %new_role = &set_arearole($trole,$area,$tstart,$tend,$domain,
@@ -4697,10 +4703,13 @@ sub rolesinit {
 		my $spec=$trole.'.'.$area;
 		my ($tdummy,$tdomain,$trest)=split(/\//,$area);
 		if ($trole =~ /^cr\//) {
+# Custom role, defined by a user
                     &custom_roleprivs(\%allroles,$trole,$tdomain,$trest,$spec,$area);
                 } elsif ($trole eq 'gr') {
+# Role of a member in a group, defined within a course/community
                     &group_roleprivs(\%allgroups,$area,$group_privs,$tend,$tstart);
 		} else {
+# Normal role, defined in roles.tab
                     &standard_roleprivs(\%allroles,$trole,$tdomain,$spec,$trest,$area);
 		}
                 if ($trole ne 'gr') {
@@ -5071,6 +5080,7 @@ sub dump {
     if (!$udomain) { $udomain=$env{'user.domain'}; }
     if (!$uname) { $uname=$env{'user.name'}; }
     my $uhome=&homeserver($uname,$udomain);
+
     if ($regexp) {
 	$regexp=&escape($regexp);
     } else {
@@ -8099,13 +8109,16 @@ sub generate_coursenum {
 }
 
 sub is_course {
-    my ($cdom,$cnum) = @_;
-    my %courses = &courseiddump($cdom,'.',1,'.','.',$cnum,undef,
-				undef,'.');
-    if (exists($courses{$cdom.'_'.$cnum})) {
-        return 1;
-    }
-    return 0;
+    my ($cdom, $cnum) = scalar(@_) == 1 ? 
+         ($_[0] =~ /^($match_domain)_($match_courseid)$/)  :  @_;
+
+    return unless $cdom and $cnum;
+
+    my %courses = &courseiddump($cdom, '.', 1, '.', '.', $cnum, undef, undef,
+        '.');
+
+    return unless exists($courses{$cdom.'_'.$cnum});
+    return wantarray ? ($cdom, $cnum) : $cdom.'_'.$cnum;
 }
 
 sub store_userdata {
@@ -11976,6 +11989,19 @@ createcourse($udom,$description,$url,$co
 
 generate_coursenum($udom,$crstype) : get a unique (unused) course number in domain $udom for course type $crstype (Course or Community).
 
+=item *
+
+is_course($courseid), is_course($cdom, $cnum)
+
+Accepts either a combined $courseid (in the form of domain_courseid) or the
+two component version $cdom, $cnum. It checks if the specified course exists.
+
+Returns:
+    undef if the course doesn't exist, otherwise
+    in scalar context the combined courseid.
+    in list context the two components of the course identifier, domain and 
+    courseid.    
+
 =back
 
 =head2 Resource Subroutines