--- loncom/enrollment/localenroll.pm	2004/07/03 18:37:20	1.10
+++ loncom/enrollment/localenroll.pm	2006/02/07 04:54:17	1.11
@@ -1,6 +1,6 @@
 # functions to glue school database system into Lon-CAPA for 
 # automated enrollment
-# $Id: localenroll.pm,v 1.10 2004/07/03 18:37:20 raeburn Exp $
+# $Id: localenroll.pm,v 1.11 2006/02/07 04:54:17 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -165,9 +165,9 @@ sub fetch_enrollment {
 # official sections and provides a checkbox to use to
 # select enrollment in the LON-CAPA course from each official section.  
 #
-# get_sections requires one argument - the institutional coursecode
+# get_sections takes two arguments - (a) the institutional coursecode
 # (in the MSU case this is a concatenation of semester code, department
-# and course number). 
+# and course number), and (b) the LON-CAPA domain that contains the course. 
 # 
 # If there is no access to official course sections at your institution,
 # then an empty array is returned, and the Automated Enrollment Manager
@@ -200,12 +200,13 @@ sub get_sections {
 # The course section or crosslisted course will only be added to the list of
 # affiliates if 'ok' is returned.
 #
-# new_course requires two arguments -
-# the institutional courseID (in the MSU case this is a concatenation of 
+# new_course takes three arguments -
+# (a) the institutional courseID (in the MSU case this is a concatenation of 
 # semester code, department code, course number, and section number
 # e.g., fs03nop590001).
-# the course owner. This is the LON-CAPA username of the course coordinator 
+# (b) the course owner. This is the LON-CAPA username of the course coordinator 
 # assigned to the course when it is first created.
+# (c) the LON-CAPA domain that contains the course
 #
 #################################
 
@@ -227,10 +228,11 @@ sub new_course  {
 #
 # A valid courseID is confirmed by returning 'ok'
 #
-# validate_courseID requires one argument -
-# the institutional courseID (in the MSU case this is a concatenation of
+# validate_courseID takes two arguments -
+# (a) the institutional courseID (in the MSU case this is a concatenation of
 # semester code, department code, course number, and section number
 # e.g., fs03nop590001).
+# (b) the LON-CAPA domain that contains the course
 #
 ###############################  
 
@@ -249,13 +251,15 @@ sub validate_courseID {
 # for the <authtype> tag from the classlist.xml files, or if this is blank,
 # the default authtype, set by the domain coordinator when creating the course
 # with loncreatecourse.pm.
-# 
-# create_password requires one argument -
-# the value of <autharg> from the classlist.xml files, or if this is blank,
-# the default autharg, set by the domain coordinator when creating the course
-# with loncreatecourse.pm.  
+#  
+# create_password takes three arguments -
+# (a) $authparam - the value of <autharg> from the classlist.xml files,
+# or if this blank, the default autharg, set by the domain coordinator when 
+# creating the course with loncreatecourse.pm
+# (b) $username - the username of the new user
+# (b) $dom - the domain of the new user.
 #
-# Three values are returned:
+# Four values are returned:
 # (a) the value of $authparam - which might have been changed
 # (b) a flag to indicate whether a password had been created
 # 0 means no password created
@@ -268,14 +272,25 @@ sub validate_courseID {
 # (c) a flag to indicate that the authentication method is correct - 'ok'.
 # If $authchk is not set to 'ok' then account creation and enrollment of the 
 # new user will not occur.
-#    
+# (d) if a password was created it can be sent along.  This is the password 
+# which will be included in the e-mail sent to the new user, or made available    
+# to the course owner/course coordinator if no e-mail address is provided. If
+# you do not wish to send a password, but want to give instructions on obtaining
+# one, you could set $newpasswd as those instructions. (e.g.,
+# $newpasswd = '(Please visit room 212, ACNS Bldg. to obtain your password)';
+# The value of $newpasswd is NOT written in the user's LON-CAPA passwd file in
+# /home/httpd/lonUsers/$dom/a/b/c/abcuser/passwd, which in the case of a user
+# employing localauth will contain 'localauth:$authparam'.  If you need to include
+# a parameter in the user's passwd file, you should return it as $authparam,
+# i.e., the first of the variables returned by create_password().             
 ###############################
 
 sub create_password {
-    my ($authparam,$dom) = @_;
+    my ($authparam,$username,$dom) = @_;
     my $authchk = 'ok';
+    my $newpasswd = '';
     my $create_passwd = 0;
-    return ($authparam,$create_passwd,$authchk);
+    return ($authparam,$create_passwd,$authchk,$newpasswd);
 }
 
 ###############################
@@ -288,7 +303,7 @@ sub create_password {
 #
 # Incoming data:
 # $dom (domain)
-# $$courseIDs{'43551dedcd43febmsul1'} = 'Title of course' (hash of courseIDs)
+# $$instcodes{'43551dedcd43febmsul1'} = 'Title of course' (hash of courseIDs)
 # 
 # fs03nop590 would be split as follows
 # @{$codetitles} = ("year","semester","department","number")
@@ -297,7 +312,7 @@ sub create_password {
 # $$codes{'department'} = 'nop'
 # $$codes{'number'} = '590'
 #
-# requires five arguments:
+# requires six arguments:
 # domain ($dom)
 # reference to hash of institutional course IDs ($instcodes)  
 # reference to hash of codes ($codes)