--- loncom/enrollment/localenroll.pm	2004/06/17 18:31:25	1.9
+++ 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.9 2004/06/17 18:31:25 raeburn Exp $
+# $Id: localenroll.pm,v 1.11 2006/02/07 04:54:17 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -165,16 +165,16 @@ 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
 # interface will allow the course coordinator to enter section numbers
 # in text boxes.
 # 
-################################ 
+###############################
 
 sub get_sections {
     my ($coursecode,$dom) = @_;
@@ -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,67 @@ 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);
+}
+
+###############################
+# sub instcode_format 
+#
+# Split coursecodes into constituent parts.   
+# e.g., INSTITUTIONALCODE = fs03nop590, LON-CAPA COURSEID: 43551dedcd43febmsul1
+# (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
+# department name, 590 = course number)
+#
+# Incoming data:
+# $dom (domain)
+# $$instcodes{'43551dedcd43febmsul1'} = 'Title of course' (hash of courseIDs)
+# 
+# fs03nop590 would be split as follows
+# @{$codetitles} = ("year","semester","department","number")
+# $$codes{{'year'} = '2003'
+# $$codes{'semester'} = 'Fall'
+# $$codes{'department'} = 'nop'
+# $$codes{'number'} = '590'
+#
+# requires six arguments:
+# domain ($dom)
+# reference to hash of institutional course IDs ($instcodes)  
+# reference to hash of codes ($codes)
+# reference to array of titles ($codetitles)
+# reference to hash of abbreviations used in categories
+# reference to hash of arrays specifying sort order used in category titles   
+#
+# e.g.,     %{$$cat_titles{'Semester'}} = (
+#                   fs => 'Fall',
+#                   ss => 'Spring',
+#                   us => 'Summer');
+#
+# e.g., @{$$cat_order{'Semester'}} = ('ss','us','fs'); 
+# returns 1 parameter: 'ok' if no processing errors.  
+###############################
+
+sub instcode_format () {
+    my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;
+    my $outcome = 'ok';
+    return $outcome;
 }
 
 1;