--- loncom/enrollment/localenroll.pm	2007/02/26 20:52:55	1.18
+++ loncom/enrollment/localenroll.pm	2007/11/10 03:10:49	1.27
@@ -1,6 +1,6 @@
 # functions to glue school database system into Lon-CAPA for 
 # automated enrollment
-# $Id: localenroll.pm,v 1.18 2007/02/26 20:52:55 raeburn Exp $
+# $Id: localenroll.pm,v 1.27 2007/11/10 03:10:49 raeburn Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -31,6 +31,11 @@ use strict;
 ################################
 # sub run
 # set this to return 1 if you want the auto enrollment to run
+#
+# Beginning with LON-CAPA version 2.4, use of this routine is
+# deprecated.  Whether or not Autoenroll.pl should run is set
+# by the Domain Coordinator via "Set domain configuration",
+# provided in the Domain Management section of the Main menu. 
 ################################
 
 sub run() {
@@ -491,7 +496,8 @@ sub instcode_defaults {
 #                keys will be unique IDs (student or faculty/staff ID)
 #                values will be either: scalar (username) or an array 
 #                if a single ID matches multiple usernames.
-# returns 1 parameter - ('ok' or other value).
+# returns 1 parameter - 'ok' if no processing error, or other value 
+#                       if an error occurred.
 # side effects - populates the $instusers and $instids refs to hashes.
 #                with information for all users from all available 
 #                institutional datafeeds.
@@ -507,10 +513,16 @@ sub allusers_info {
 ###############################
 # sub get_userinfo
 #
-# Incoming data: four required arguments and two optional arguments
-# Retrieves institutional data for a single user either by username
-# if $uname is included as second argument, or by ID if $id is 
-# included as a third argument.  Either (b) or (c) must be provided. 
+# Incoming data: four required arguments and additional optional arguments
+# Two modes of operation:
+# (1) Retrieves institutional data for a single user either by username
+#     if $uname is included as second argument, or by ID if $id is 
+#     included as a third argument.  Either (b) or (c) must be provided.
+#     (g), (h) and (i) will be undefined.
+# (2) Retrieves institutional user data from search of an institutional
+#     directory based on a search. (g) and (h) are required.
+#     (i) is optional. (b) and (c) will be undefined. 
+#
 # (a) $dom - domain
 # (b) $uname - username of user
 # (c) $id - student/faculty ID of user
@@ -526,18 +538,35 @@ sub allusers_info {
 #                 if a single ID matches multiple usernames.
 # (f) $types - optional reference to array which contains 
 #              institutional types to check.
+# (g) $srchby - optional if $uname or $id defined, otherwise required.
+#               Allowed values include: 1. lastfirst, 2. last, 3. uname
+#               corresponding to searches by 1. lastname,firstname;
+#               2. lastname; 3. username
+# (h) $srchterm - optional if $uname or $id defined, otherwise required
+#                String to search for.
+# (i) $srchtype - optional. Allowed values: contains, begins (defaults
+#                to exact match otherwise).
 #
-# returns 1 parameter - ('ok' or other value).
+# returns 1 parameter - 'ok' if no processing error, or other value 
+#                       if an error occurred.
 # side effects - populates the $instusers and $instids refs to hashes.
 #                with information for specified username, or specified
 #                id, if fifth argument provided, from all available, or 
 #                specified (e.g., faculty only) institutional datafeeds,
 #                if sixth argument provided.
+#
+# WARNING: You need to set $outcome to 'ok' once you have customized
+#          this routine to communicate with an instititional 
+#          directory data source, otherwise institutional directory 
+#          searches will always be reported as being unavailable
+#          in domain $dom.
+#
 ###############################
 
 sub get_userinfo {
-    my ($dom,$uname,$id,$instusers,$instids,$types) = @_;
-    my $outcome = 'ok';
+    my ($dom,$uname,$id,$instusers,$instids,$types,
+        $srchby,$srchterm,$srchtype) = @_;
+    my $outcome = 'unavailable';
     return $outcome;
 }
 
@@ -554,16 +583,124 @@ sub get_userinfo {
 #              which institutional types should be shown
 #              when displaying data tables (e.g., default quotas    
 #              or updateable user fields (see domainprefs.pm) 
-# returns 1 parameter - ('ok' or other value).
+# returns 1 parameter - 'ok' if no processing error, or other value 
+#                        if an error occurred.
 #
 ###############################
 
 sub inst_usertypes {
     my ($dom,$usertypes,$order) = @_;
+    @{$order} = ();
+    %{$usertypes} = ();
     my $outcome = 'ok';
     return $outcome;
 }
 
+###############################
+# sub username_rules
+#
+# Incoming data: three arguments 
+# (a) $dom - domain
+# (b) $ruleshash - reference to hash containing rules
+#                  (a hash of a hash)
+#                  keys of top level hash are short names  
+#                   (e.g., netid, noncredit) 
+#                  for each key, value is a hash
+#                      desc => long name for rule  
+#                      rule => description of rule
+#                      authtype => (krb5,krb4,int, or loc)
+#                                 authentication type for rule 
+#                      authparm => authentication parameter for rule
+#                      authparmfixed => 1 if authparm used when
+#                          creating user for rule must be authparm  
+#                      authmsg => Message to display describing 
+#                                 authentication to use for this rule
+#
+# (c) $rulesorder - reference to array containing rule names 
+#                   in order to be displayed
+
+#
+#  returns 'ok' if no processing error.
+#
+############################### 
+
+sub username_rules {
+    my ($dom,$ruleshash,$rulesorder) = @_;
+    my $outcome;
+    return $outcome;
+}
+
+###############################
+# sub id_rules
+#
+# Incoming data: three arguments
+# (a) $dom - domain
+# (b) $ruleshash - reference to hash containing rules
+#                  (a hash of a hash)
+#                  keys of top level hash are short names
+#                   (e.g., netid, noncredit)
+#                  for each key, value is a hash
+#                      desc => long name for rule
+#                      rule => description of rule
+#
+# (c) $rulesorder - reference to array containing rule names
+#                   in order to be displayed
+
+#
+#  returns 'ok' if no processing error.
+#
+###############################
+
+sub id_rules {
+    my ($dom,$ruleshash,$rulesorder) = @_;
+    my $outcome;
+    return $outcome;
+}
+
+###############################
+# sub username_check 
+#
+# Incoming data: four arguments
+# (a) $dom - domain (scalar) 
+# (b) $uname - username to compare against rules (scalar)
+# (c) $to_check (reference to array of rule names to check)
+# (d) $resultshash (reference to hash of results)
+#                    hash of results for rule checked
+#                   - keys are rule names
+#                   - values are: 1 or 0 (for matched or unmatched) 
+#
+# returns 'ok' if no processing error.
+#
+###############################
+
+sub username_check {
+    my ($dom,$uname,$to_check,$resultshash) = @_;
+    my $outcome;
+    return $outcome; 
+}
+
+###############################
+# sub id_check
+#
+# Incoming data: four arguments
+# (a) $dom - domain (scalar)
+# (b) $id - ID to compare against rules (scalar)
+# (c) $to_check (reference to array of rule names to check)
+# (d) $resultshash (reference to hash of results)
+#                    hash of results for rule checked
+#                   - keys are rule names
+#                   - values are: 1 or 0 (for matched or unmatched)
+#
+# returns 'ok' if no processing error.
+#
+###############################
+
+sub id_check {
+    my ($dom,$id,$to_check,$resultshash) = @_;
+    my $outcome;
+    return $outcome;
+}
+
 ###############################
 # sub AUTOLOAD
 #