[LON-CAPA-cvs] cvs: loncom /enrollment localenroll.pm /homework inputtags.pm lonhomework.pm randomlabel.pm response.pm structuretags.pm
jms
lon-capa-cvs-allow@mail.lon-capa.org
Tue, 25 Nov 2008 13:16:27 -0000
This is a MIME encoded message
--jms1227618987
Content-Type: text/plain
jms Tue Nov 25 13:16:27 2008 EDT
Modified files:
/loncom/homework inputtags.pm randomlabel.pm response.pm
lonhomework.pm structuretags.pm
/loncom/enrollment localenroll.pm
Log:
POD documentation changes
--jms1227618987
Content-Type: text/plain
Content-Disposition: attachment; filename="jms-20081125131627.txt"
Index: loncom/homework/inputtags.pm
diff -u loncom/homework/inputtags.pm:1.248 loncom/homework/inputtags.pm:1.249
--- loncom/homework/inputtags.pm:1.248 Sun Nov 16 02:46:25 2008
+++ loncom/homework/inputtags.pm Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# input definitons
#
-# $Id: inputtags.pm,v 1.248 2008/11/16 02:46:25 raeburn Exp $
+# $Id: inputtags.pm,v 1.249 2008/11/25 13:16:17 jms Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -25,6 +25,30 @@
#
# http://www.lon-capa.org/
+=pod
+
+=head1 NAME
+
+Apache::inputtags
+
+=head1 SYNOPSIS
+
+
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item
+
+=back
+
+=cut
+
package Apache::inputtags;
use HTML::Entities();
use strict;
@@ -38,41 +62,47 @@
&Apache::lonxml::register('Apache::inputtags',('hiddenline','textfield','textline'));
}
-# Initializes a set of global variables used during the parse of the problem.
-#
-# @Apache::inputtags::input - List of current input ids.
-# @Apache::inputtags::inputlist - List of all input ids seen this problem.
-# @Apache::inputtags::response - List of all current resopnse ids.
-# @Apache::inputtags::responselist - List of all response ids seen this
-# problem.
-# @Apache::inputtags::hint - List of all hint ids.
-# @Apache::inputtags::hintlist - List of all hint ids seen this problem.
-# @Apache::inputtags::previous - List describing if specific responseds
-# have been used
-# @Apache::inputtags::previous_version - Submission responses were used in.
-# $Apache::inputtags::part - Current part id (valid only in
-# <problem>)
-# 0 if not in a part.
-# @Apache::inputtags::partlist - List of part ids seen in the current
-# <problem>
-# @Apache::inputtags::status - List of problem statuses. First
-# element is the status of the <problem>
-# the remainder are for individual <part>s.
-# %Apache::inputtags::params - Hash of defined parameters for the
-# current response.
-# @Apache::inputtags::import - List of all ids for <import> thes get
-# join()ed and prepended.
-# @Apache::inputtags::importlist - List of all import ids seen.
-# $Apache::inputtags::response_with_no_part
-# - Flag set true if we have seen a response
-# that is not inside a <part>
-# %Apache::inputtags::answertxt - <*response> tags store correct
-# answer strings for display by <textline/>
-# in this hash.
-# %Apache::inputtags::submission_display
-# - <*response> tags store improved display
-# of submission strings for display by part
-# end.
+=pod
+
+=item initialize_inputtags()
+
+Initializes a set of global variables used during the parse of the problem.
+
+@Apache::inputtags::input - List of current input ids.
+@Apache::inputtags::inputlist - List of all input ids seen this problem.
+@Apache::inputtags::response - List of all current resopnse ids.
+@Apache::inputtags::responselist - List of all response ids seen this
+ problem.
+@Apache::inputtags::hint - List of all hint ids.
+@Apache::inputtags::hintlist - List of all hint ids seen this problem.
+@Apache::inputtags::previous - List describing if specific responseds
+ have been used
+@Apache::inputtags::previous_version - Submission responses were used in.
+$Apache::inputtags::part - Current part id (valid only in
+ <problem>)
+ 0 if not in a part.
+@Apache::inputtags::partlist - List of part ids seen in the current
+ <problem>
+@Apache::inputtags::status - List of problem statuses. First
+ element is the status of the <problem>
+ the remainder are for individual <part>s.
+%Apache::inputtags::params - Hash of defined parameters for the
+ current response.
+@Apache::inputtags::import - List of all ids for <import> thes get
+ join()ed and prepended.
+@Apache::inputtags::importlist - List of all import ids seen.
+$Apache::inputtags::response_with_no_part
+ - Flag set true if we have seen a response
+ that is not inside a <part>
+%Apache::inputtags::answertxt - <*response> tags store correct
+ answer strings for display by <textline/>
+ in this hash.
+%Apache::inputtags::submission_display
+ - <*response> tags store improved display
+ of submission strings for display by part
+ end.
+
+=cut
sub initialize_inputtags {
@Apache::inputtags::input=();
@@ -424,14 +454,21 @@
return "";
}
-# $part -> partid
-# $id -> responseid
-# $uploadefiletypes -> comma seperated list of extensions allowed or * for any
-# $which -> 'uploadedonly' -> only newly uploaded files
-# 'portfolioonly' -> only allow files from portfolio
-# 'both' -> allow files from either location
-# $extratext -> additional text to go between the link and the input box
-# returns a table row <tr>
+=pod
+
+=item file_selector()
+
+$part -> partid
+$id -> responseid
+$uploadefiletypes -> comma seperated list of extensions allowed or * for any
+$which -> 'uploadedonly' -> only newly uploaded files
+ 'portfolioonly' -> only allow files from portfolio
+ 'both' -> allow files from either location
+$extratext -> additional text to go between the link and the input box
+returns a table row <tr>
+
+=cut
+
sub file_selector {
my ($part,$id,$uploadedfiletypes,$which,$extratext)=@_;
if (!$uploadedfiletypes) { return ''; }
@@ -1346,4 +1383,10 @@
1;
__END__
+
+=pod
+
+=back
+
+=cut
Index: loncom/homework/randomlabel.pm
diff -u loncom/homework/randomlabel.pm:1.92 loncom/homework/randomlabel.pm:1.93
--- loncom/homework/randomlabel.pm:1.92 Tue Nov 18 19:14:28 2008
+++ loncom/homework/randomlabel.pm Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# random labelling tool
#
-# $Id: randomlabel.pm,v 1.92 2008/11/18 19:14:28 jms Exp $
+# $Id: randomlabel.pm,v 1.93 2008/11/25 13:16:17 jms Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -24,35 +24,83 @@
# /home/httpd/html/adm/gpl.txt
#
# http://www.lon-capa.org/
-#
-# SYNTAX:
-# <randomlabel bgimg="URL" width="12" height="45" texwidth="50">
-# <labelgroup name="GroupOne" type="image">
-# <location x="123" y="456" />
-# <location x="321" y="654" />
-# <location x="213" y="546" />
-# <label description="TEXT-1">IMG-URL</label>
-# <label description="TEXT-2">IMG-URL</label>
-# <label description="TEXT-3">IMG-URL</label>
-# </labelgroup>
-# <labelgroup name="GroupTwo" type="text">
-# <location x="12" y="45" />
-# <location x="32" y="65" />
-# <location x="21" y="54" />
-# <label>TEXT-1</label>
-# <label>TEXT-2</label>
-# <label>TEXT-3</label>
-# </labelgroup>
-# </randomlabel>
-# ===========================================
-# side effect:
-# location (123,456): $GroupOne[0] = 2 # images give out indexes
-# (321,654): $GroupOne[1] = 1
-# (213,546): $GroupOne[2] = 0
-# location (12,45) : $GroupTwo[0] = "TEXT-3"
-# (32,65) : $GroupTwo[1] = "TEXT-1"
-# (21,54) : $GroupTwo[2] = "TEXT-2"
-# ===========================================
+
+=pod
+
+=head1 NAME
+
+Apache::randomlable.pm
+
+=head1 SYNOPSIS
+
+Interface for producing applet code which
+randomizes the labelling of an image.
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 SYNTAX
+
+ <randomlabel bgimg="URL" width="12" height="45" texwidth="50">
+ <labelgroup name="GroupOne" type="image">
+ <location x="123" y="456" />
+ <location x="321" y="654" />
+ <location x="213" y="546" />
+ <label description="TEXT-1">IMG-URL</label>
+ <label description="TEXT-2">IMG-URL</label>
+ <label description="TEXT-3">IMG-URL</label>
+ </labelgroup>
+ <labelgroup name="GroupTwo" type="text">
+ <location x="12" y="45" />
+ <location x="32" y="65" />
+ <location x="21" y="54" />
+ <label>TEXT-1</label>
+ <label>TEXT-2</label>
+ <label>TEXT-3</label>
+ </labelgroup>
+ </randomlabel>
+ ===========================================
+ side effect:
+ location (123,456): $GroupOne[0] = 2 images give out indexes
+ (321,654): $GroupOne[1] = 1
+ (213,546): $GroupOne[2] = 0
+ location (12,45) : $GroupTwo[0] = "TEXT-3"
+ (32,65) : $GroupTwo[1] = "TEXT-1"
+ (21,54) : $GroupTwo[2] = "TEXT-2"
+ ===========================================
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item check_int()
+
+ utility function to do error checking on a integer.
+
+=item extract_tag_sizes()
+
+Parameters:
+ tag - tag potentially containing height/width attributes.
+ def_width - Default width.
+ def_height - Default height.
+ Returns:
+ list containing width/height.
+
+=item get_label_width()
+
+ Utility sub to compute the width of a label.
+
+=item end_labelgroup()
+
+begin to assign labels to locations
+
+=back
+
+=cut
+
+
package Apache::randomlabel;
use Apache::lonnet;
@@ -90,15 +138,8 @@
return $num;
}
-# Get width/height from an image tag...
-#
-# Parameters:
-# tag - tag potentially containing height/width attributes.
-# def_width - Default width.
-# def_height - Default height.
-# Returns:
-# list containing width/height.
-#
+
+
sub extract_tag_sizes {
my ($tag, $dw, $dh) = @_;
$tag =~ s/\s+/ /g; # Collapse whitespace.
@@ -359,9 +400,8 @@
return $result;
}
-#
-# Utility sub to compute the width of a label.
-#
+
+
sub get_label_width {
my $label = shift;
&Apache::lonxml::debug("image label = $label");
@@ -411,7 +451,8 @@
$out=Apache::run::run($code,$safeeval);
}
-# begin to assign labels to locations
+
+
sub end_labelgroup {
my ($target,$token,$tagstack,$parstack,$parser,$safeeval,$style)=@_;
my $gname = $Apache::randomlabel::groupname;
Index: loncom/homework/response.pm
diff -u loncom/homework/response.pm:1.207 loncom/homework/response.pm:1.208
--- loncom/homework/response.pm:1.207 Mon Nov 24 16:53:26 2008
+++ loncom/homework/response.pm Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# various response type definitons response definition
#
-# $Id: response.pm,v 1.207 2008/11/24 16:53:26 jms Exp $
+# $Id: response.pm,v 1.208 2008/11/25 13:16:17 jms Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -26,6 +26,29 @@
# http://www.lon-capa.org/
#
+=pod
+
+=head1 NAME
+
+Apache::resonse.pm
+
+=head1 SYNOPSIS
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item
+
+=back
+
+=cut
+
+
package Apache::response;
use strict;
use Apache::lonlocal;
@@ -1153,17 +1176,20 @@
$Apache::response::conceptgroup{'names'};
}
-#------------------------------------------------------------
-#
-# Get a parameter associated with a problem.
-# Parameters:
-# $id - the id of the paramater, either a part id,
-# or a partid and responspe id joined by _
-# $name - Name of the parameter to fetch
-# $default - Default value for the paramter.
-#
-#
-#
+
+=pod
+
+=item get_response_param()
+
+Get a parameter associated with a problem.
+Parameters:
+ $id - the id of the paramater, either a part id,
+ or a partid and responspe id joined by _
+ $name - Name of the parameter to fetch
+ $default - Default value for the paramter.
+
+=cut
+
sub get_response_param {
my ($id,$name,$default)=@_;
my $parameter;
@@ -1224,14 +1250,21 @@
}
}
-# basically undef and 0 (both false) mean that they still have work to do
-# and all true values mean that they can't do any more work
-#
-# a return of undef means it is unattempted
-# a return of 0 means it is attmpted and wrong but still has tries
-# a return of 1 means it is marked correct
-# a return of 2 means they have exceed maximum number of tries
-# a return of 3 means it after the answer date
+=pod
+
+=item check_status()
+
+basically undef and 0 (both false) mean that they still have work to do
+and all true values mean that they can't do any more work
+
+ a return of undef means it is unattempted
+ a return of 0 means it is attmpted and wrong but still has tries
+ a return of 1 means it is marked correct
+ a return of 2 means they have exceed maximum number of tries
+ a return of 3 means it after the answer date
+
+=cut
+
sub check_status {
my ($id)=@_;
if (!defined($id)) { $id=$Apache::inputtags::part; }
@@ -1299,3 +1332,8 @@
1;
__END__
+=pod
+
+=back
+
+=cut
\ No newline at end of file
Index: loncom/homework/lonhomework.pm
diff -u loncom/homework/lonhomework.pm:1.299 loncom/homework/lonhomework.pm:1.300
--- loncom/homework/lonhomework.pm:1.299 Wed Nov 19 18:34:56 2008
+++ loncom/homework/lonhomework.pm Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# The LON-CAPA Homework handler
#
-# $Id: lonhomework.pm,v 1.299 2008/11/19 18:34:56 jms Exp $
+# $Id: lonhomework.pm,v 1.300 2008/11/25 13:16:17 jms Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -25,6 +25,25 @@
#
# http://www.lon-capa.org/
+=pod
+
+=head1 NAME
+
+Apache::lonhomework.pm
+
+=head1 SYNOPSIS
+
+handles requests for output, evaluation, and
+alteration of a homework resource
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=cut
+
package Apache::lonhomework;
use strict;
Index: loncom/homework/structuretags.pm
diff -u loncom/homework/structuretags.pm:1.434 loncom/homework/structuretags.pm:1.435
--- loncom/homework/structuretags.pm:1.434 Mon Nov 10 11:44:54 2008
+++ loncom/homework/structuretags.pm Tue Nov 25 13:16:17 2008
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# definition of tags that give a structure to a document
#
-# $Id: structuretags.pm,v 1.434 2008/11/10 11:44:54 foxr Exp $
+# $Id: structuretags.pm,v 1.435 2008/11/25 13:16:17 jms Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -27,6 +27,29 @@
#
###
+=pod
+
+=head1 NAME
+
+Apache::structuretags
+
+=head1 SYNOPSIS
+
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=item
+
+=back
+
+=cut
+
package Apache::structuretags;
@@ -551,12 +574,19 @@
if ($temp =~ m/^error:.*/) { %Apache::lonhomework::history=(); }
}
-# -------------------------------------------------------------finalize_storage
-# Stores away the result has to a student's environment
-# checks form.grade_ for specific values, other wises stores
-# to the running users environment
-# Will increment totals for attempts, students, and corrects
-# if running user has student role.
+=pod
+
+=item finalize_storage()
+
+ Stores away the result has to a student's environment
+ checks form.grade_ for specific values, other wises stores
+ to the running users environment
+ Will increment totals for attempts, students, and corrects
+ if running user has student role.
+
+=cut
+
+
sub finalize_storage {
my ($given_symb) = @_;
my $result;
@@ -587,10 +617,16 @@
return $result;
}
-# -------------------------------------------------------------store_aggregates
-# Sends hash of values to be incremented in nohist_resourcetracker.db
-# for the course. Increments total number of attempts, unique students
-# and corrects for each part for an instance of a problem, as appropriate.
+=pod
+
+item store_aggregates()
+
+ Sends hash of values to be incremented in nohist_resourcetracker.db
+ for the course. Increments total number of attempts, unique students
+ and corrects for each part for an instance of a problem, as appropriate.
+
+=cut
+
sub store_aggregates {
my ($symb,$courseid) = @_;
my %aggregate;
@@ -2002,3 +2038,9 @@
1;
__END__
+
+=pod
+
+=back
+
+=cut
Index: loncom/enrollment/localenroll.pm
diff -u loncom/enrollment/localenroll.pm:1.31 loncom/enrollment/localenroll.pm:1.32
--- loncom/enrollment/localenroll.pm:1.31 Fri Feb 29 21:01:43 2008
+++ loncom/enrollment/localenroll.pm Tue Nov 25 13:16:26 2008
@@ -1,6 +1,6 @@
# functions to glue school database system into Lon-CAPA for
# automated enrollment
-# $Id: localenroll.pm,v 1.31 2008/02/29 21:01:43 raeburn Exp $
+# $Id: localenroll.pm,v 1.32 2008/11/25 13:16:26 jms Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -24,128 +24,154 @@
#
# http://www.lon-capa.org/
#
+
+=pod
+
+=head1 NAME
+
+localenroll
+
+=head1 SYNOPSIS
+
+This is part of the LearningOnline Network with CAPA project
+described at http://www.lon-capa.org.
+
+
+=head1 NOTABLE SUBROUTINES
+
+=over
+
+=back
+
+=cut
+
package localenroll;
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.
-################################
+=pod
+
+=item 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.
+
+=cut
sub run() {
my $dom = shift;
return 0;
}
-################################
-# sub fetch_enrollment
-#
-# connects to the institutional classlist data source,
-# reads classlist data and stores in an XML file
-# in /home/httpd/perl/tmp/
-#
-# classlist files are named as follows:
-#
-# DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
-#
-# e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
-# where DOMAIN = msu COURSE = 43551dedcd43febmsul1
-# INSTITUTIONALCODE = fs03nop590001
-# (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
-# department name, 590 = course number, 001 = section number.)
-#
-# fetch_enrollment requires three arguments -
-# $dom - DOMAIN e.g., msu
-# $affiliatesref - a reference to a hash of arrays that contains LON-CAPA
-# courses that are to be updated as keys, and institutional coursecodes
-# contributing enrollment to that LON-CAPA course as elements in each array.
-# $replyref - a reference to a hash that contains LON-CAPA courses
-# that are to be updated as keys, and the total enrollment count in all
-# affiliated sections, as determined from institutional data as hash elements.
-#
-# As an example, if fetch_enrollment is called to retrieve institutional
-# classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which
-# corresponds to fs03nop590, sections 001, 601 and 602 , and the course
-# also accommodates enrollment from a crosslisted course in the ost
-# department - fs03ost580002:
-#
-# the affiliatesref would be a reference to %affiliates which would be:
-#
-# @{$affiliates{'43551dedcd43febmsul1'}} =
-# ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
-#
-# fetch_enrollment would create four files in /home/httpd/perl/tmp/.
-# msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
-# msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
-# msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
-# msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
-#
-# In each file, student data would be stored in the following format
-#
-# <student username="smith">
-# <autharg>MSU.EDU</autharg>
-# <authtype>krb4</authtype>
-# <email>smith@msu.edu</email>
-# <enddate></enddate>
-# <firstname>John</firstname>
-# <generation>II</generation>
-# <groupID>fs03nop590001</groupID>
-# <lastname>Smith</lastname>
-# <middlename>D</middlename>
-# <startdate></startdate>
-# <studentID>A12345678</studentID>
-# </student>
-#
-# with the following at the top of the file
-#<?xml version="1.0" encoding="UTF-8"?>
-#<!DOCTYPE text>
-#<students>
-#
-# (all comment - #s removed)
-#
-# and a closing:
-#</students>
-#
-# The <startdate> and the <enddate> are the activation date and expiration date
-# for this student's role. If they are absent, then the default access start and
-# default access end dates are used. The default access dates can be set when
-# the course is created, and can be modified using the Automated Enrollment
-# Manager, or via the 'Upload a class list','Enroll a single student' or
-# 'Modify student data' utilities in the Enrollment Manager, by checking the
-# 'make these dates the default for future enrollment' checkbox. If no default
-# dates have been set, then the tudent role will be active immediately, and will
-# remain active until the role is explicitly expired using ENRL -> Drop students.
-# If dates are to included in the XML file, they should be in the format
-# YYYY:MM:DD:HH:MM:SS (: separators required).
-#
-# If there were 10 students in fs03nop590001, 5 students in fs03nop59o601,
-# 8 students in fs03nop590602, and 2 students in fs03ost580002,
-# then $$reply{'43551dedcd43febmsul1'} = 25
-#
-# The purpose of the %reply hash is to detect cases where the institutional
-# enrollment is 0 (most likely due to a problem with the data source).
-# In such a case, the LON-CAPA course roster is left unchanged (i.e., no
-# students are expired, even if automated drops is enabled.
-#
-# fetch_enrollment should return a 0 or 1, depending on whether a connection
-# could be established to the institutional data source.
-# 0 is returned if no connection could be made.
-# 1 is returned if connection was successful
-#
-# A return of 1 is required for the calling modules to perform LON-CAPA
-# roster changes based on the contents of the XML classlist file(s), e,g,,
-# msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
-#
-# XML classlist files are temporary. They are deleted after the enrollment
-# update process in the calling module is complete.
-#
-################################
+
+=pod
+
+=item fetch_enrollment()
+
+ connects to the institutional classlist data source,
+ reads classlist data and stores in an XML file
+ in /home/httpd/perl/tmp/
+
+ classlist files are named as follows:
+
+ DOMAIN_COURSE_INSTITUTIONALCODE_classlist.xml
+
+ e.g., msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
+ where DOMAIN = msu COURSE = 43551dedcd43febmsul1
+ INSTITUTIONALCODE = fs03nop590001
+ (MSU's course naming scheme - fs03 = Fall semester 2003, nop =
+ department name, 590 = course number, 001 = section number.)
+
+ fetch_enrollment requires three arguments -
+ $dom - DOMAIN e.g., msu
+ $affiliatesref - a reference to a hash of arrays that contains LON-CAPA
+ courses that are to be updated as keys, and institutional coursecodes
+ contributing enrollment to that LON-CAPA course as elements in each array.
+ $replyref - a reference to a hash that contains LON-CAPA courses
+ that are to be updated as keys, and the total enrollment count in all
+ affiliated sections, as determined from institutional data as hash elements.
+
+ As an example, if fetch_enrollment is called to retrieve institutional
+ classlists for a single LON-CAPA course - 43551dedcd43febmsul1 which
+ corresponds to fs03nop590, sections 001, 601 and 602 , and the course
+ also accommodates enrollment from a crosslisted course in the ost
+ department - fs03ost580002:
+
+ the affiliatesref would be a reference to %affiliates which would be:
+
+ @{$affiliates{'43551dedcd43febmsul1'}} =
+ ("fs03nop590001","fs03nop590601","fs03nop590602","fs03ost580002");
+
+ fetch_enrollment would create four files in /home/httpd/perl/tmp/.
+ msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
+ msu_43551dedcd43febmsul1_fs03nop590601_classlist.xml
+ msu_43551dedcd43febmsul1_fs03nop590602_classlist.xml
+ msu_43551dedcd43febmsul1_fs03ost580002_classlist.xml
+
+ In each file, student data would be stored in the following format
+
+ <student username="smith">
+ <autharg>MSU.EDU</autharg>
+ <authtype>krb4</authtype>
+ <email>smith@msu.edu</email>
+ <enddate></enddate>
+ <firstname>John</firstname>
+ <generation>II</generation>
+ <groupID>fs03nop590001</groupID>
+ <lastname>Smith</lastname>
+ <middlename>D</middlename>
+ <startdate></startdate>
+ <studentID>A12345678</studentID>
+ </student>
+
+ with the following at the top of the file
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE text>
+<students>
+
+ (all comment - s removed)
+
+ and a closing:
+</students>
+
+ The <startdate> and the <enddate> are the activation date and expiration date
+ for this student's role. If they are absent, then the default access start and
+ default access end dates are used. The default access dates can be set when
+ the course is created, and can be modified using the Automated Enrollment
+ Manager, or via the 'Upload a class list','Enroll a single student' or
+ 'Modify student data' utilities in the Enrollment Manager, by checking the
+ 'make these dates the default for future enrollment' checkbox. If no default
+ dates have been set, then the tudent role will be active immediately, and will
+ remain active until the role is explicitly expired using ENRL -> Drop students.
+ If dates are to included in the XML file, they should be in the format
+ YYYY:MM:DD:HH:MM:SS (: separators required).
+
+ If there were 10 students in fs03nop590001, 5 students in fs03nop59o601,
+ 8 students in fs03nop590602, and 2 students in fs03ost580002,
+ then $$reply{'43551dedcd43febmsul1'} = 25
+
+ The purpose of the %reply hash is to detect cases where the institutional
+ enrollment is 0 (most likely due to a problem with the data source).
+ In such a case, the LON-CAPA course roster is left unchanged (i.e., no
+ students are expired, even if automated drops is enabled.
+
+ fetch_enrollment should return a 0 or 1, depending on whether a connection
+ could be established to the institutional data source.
+ 0 is returned if no connection could be made.
+ 1 is returned if connection was successful
+
+ A return of 1 is required for the calling modules to perform LON-CAPA
+ roster changes based on the contents of the XML classlist file(s), e,g,,
+ msu_43551dedcd43febmsul1_fs03nop590001_classlist.xml
+
+ XML classlist files are temporary. They are deleted after the enrollment
+ update process in the calling module is complete.
+
+
+=cut
sub fetch_enrollment {
my ($dom,$affiliatesref,$replyref) = @_;
@@ -156,30 +182,33 @@
return $okflag;
}
-###############################
-# sub get_sections
-#
-# This is called by the Automated Enrollment Manager interface
-# (lonpopulate.pm) to create an array of valid sections for
-# a specific institutional coursecode.
-# e.g., for MSU coursecode: fs03nop590
-# ("001","601","602") would be returned
-#
-# If the array returned contains at least one element, then
-# the interface offerred to the course coordinator, lists
-# official sections and provides a checkbox to use to
-# select enrollment in the LON-CAPA course from each official section.
-#
-# 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 (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.
-#
-###############################
+=pod
+
+=item get_sections()
+
+ This is called by the Automated Enrollment Manager interface
+ (lonpopulate.pm) to create an array of valid sections for
+ a specific institutional coursecode.
+ e.g., for MSU coursecode: fs03nop590
+ ("001","601","602") would be returned
+
+ If the array returned contains at least one element, then
+ the interface offerred to the course coordinator, lists
+ official sections and provides a checkbox to use to
+ select enrollment in the LON-CAPA course from each official section.
+
+ 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 (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.
+
+
+
+=cut
sub get_sections {
my ($coursecode,$dom) = @_;
@@ -187,34 +216,35 @@
return @secs;
}
-###############################
-# sub new_course
-#
-# This is called by loncreatecourse.pm and
-# lonpopulate.pm to record that fact that a new course section
-# has been added to LON-CAPA that requires access to institutional data
-# At MSU, this is required, as institutional classlists can only made
-# available to faculty who are officially assigned to a course.
-#
-# The new_course subroutine is used to check that the course owner
-# of the LON-CAPA course is permitted to access the institutional
-# classlist for any course sections and crosslisted classes that
-# the course coordinator wishes to have affiliated with the course.
-#
-# If access is permitted, then 'ok' is returned.
-# The course section or crosslisted course will only be added to the list of
-# affiliates if 'ok' is returned.
-#
-# 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).
-# (b) the course owner. This is the LON-CAPA username and domain of the course
-# coordinator assigned to the course when it is first created, in the form
-# username:domain
-# (c) the LON-CAPA domain that contains the course
-#
-#################################
+=pod
+
+=item new_course()
+
+ This is called by loncreatecourse.pm and
+ lonpopulate.pm to record that fact that a new course section
+ has been added to LON-CAPA that requires access to institutional data
+ At MSU, this is required, as institutional classlists can only made
+ available to faculty who are officially assigned to a course.
+
+ The new_course subroutine is used to check that the course owner
+ of the LON-CAPA course is permitted to access the institutional
+ classlist for any course sections and crosslisted classes that
+ the course coordinator wishes to have affiliated with the course.
+
+ If access is permitted, then 'ok' is returned.
+ The course section or crosslisted course will only be added to the list of
+ affiliates if 'ok' is returned.
+
+ 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).
+ (b) the course owner. This is the LON-CAPA username and domain of the course
+ coordinator assigned to the course when it is first created, in the form
+ username:domain
+ (c) the LON-CAPA domain that contains the course
+
+=cut
sub new_course {
my ($course_id,$owner,$dom) = @_;
@@ -222,25 +252,26 @@
return $outcome;
}
-###############################
-# sub validate_courseID
-#
-# This is called whenever a new course section or crosslisted course
-# is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
-# and the Automated Enrollment Manager in lonpopulate.pm).
-# A check is made that the courseID that the course coordinator wishes
-# to affiliate with the course is valid according to the institutional
-# schedule of official classes
-#
-# A valid courseID is confirmed by returning 'ok'
-#
-# 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
-#
-###############################
+=pod
+
+=item validate_courseID()
+
+ This is called whenever a new course section or crosslisted course
+ is being affiliated with a LON-CAPA course (i.e., by loncreatecourse.pm
+ and the Automated Enrollment Manager in lonpopulate.pm).
+ A check is made that the courseID that the course coordinator wishes
+ to affiliate with the course is valid according to the institutional
+ schedule of official classes
+
+ A valid courseID is confirmed by returning 'ok'
+
+ 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
+
+=cut
sub validate_courseID {
my ($course_id,$dom) = @_;
@@ -248,48 +279,51 @@
return $outcome;
}
-###############################
-# sub create_password
-#
-# This is called when the authentication method set for the automated
-# enrollment process when enrolling new users in the domain is "localauth".
-# This could be signalled for the specific user by the value of localauth
-# 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 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) $dom - the domain of the new user.
-# (c) $username - the username of the new user (currently not actually used)
-#
-# 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
-# 1 means password created. In this case the calling module - Enrollment.pm
-# will send the LON-CAPA username and password to the new user's e-mail
-# (if one was provided), or to the course owner (if one was not provided and
-# the new user was created by the automated process), or to the active
-# course coordinator (if the new user was created using the 'update roster
-# now' interface included in the Automated Enrollment Manager).
-# (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().
-###############################
+=pod
+
+=item create_password()
+
+ This is called when the authentication method set for the automated
+ enrollment process when enrolling new users in the domain is "localauth".
+ This could be signalled for the specific user by the value of localauth
+ 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 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) $dom - the domain of the new user.
+ (c) $username - the username of the new user (currently not actually used)
+
+ 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
+ 1 means password created. In this case the calling module - Enrollment.pm
+ will send the LON-CAPA username and password to the new user's e-mail
+ (if one was provided), or to the course owner (if one was not provided and
+ the new user was created by the automated process), or to the active
+ course coordinator (if the new user was created using the 'update roster
+ now' interface included in the Automated Enrollment Manager).
+ (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().
+
+
+=cut
sub create_password {
my ($authparam,$dom,$username) = @_;
@@ -299,41 +333,44 @@
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'} = 'fs03nop590' (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.
-###############################
+=pod
+
+=item 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'} = 'fs03nop590' (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.
+
+=cut
+
sub instcode_format () {
my ($dom,$instcodes,$codes,$codetitles,$cat_titles,$cat_order) = @_;
@@ -341,35 +378,38 @@
return $outcome;
}
-###############################
-# sub institutional_photos
-#
-# Called when automated enrollment manager is used to update student photos.
-#
-# Incoming data: six arguments
-# (a) $dom (domain)
-# (b) $crs (LONCAPA course number)
-# (c) $affiliates: a reference to a hash with the keys set to the
-# institutional course IDs for the course.
-# (d) $result: a reference to a hash which will return usernames
-# of students (& separated) in following categories (the keys):
-# new, update, missing, same, deleted, noid, nouser. The list
-# includes those students for whom the result of the modification
-# process was either addition of a new photo. update of an
-# existing photo, photo was found to be missing from institution's
-# data store, photo used is same as before, or photo was
-# deleted from storage on LON-CAPA server housing student's
-# information, no student ID was available.
+
+=pod
+
+=item institutional_photos()
+
+ Called when automated enrollment manager is used to update student photos.
+
+ Incoming data: six arguments
+ (a) $dom (domain)
+ (b) $crs (LONCAPA course number)
+ (c) $affiliates: a reference to a hash with the keys set to the
+ institutional course IDs for the course.
+ (d) $result: a reference to a hash which will return usernames
+ of students (& separated) in following categories (the keys):
+ new, update, missing, same, deleted, noid, nouser. The list
+ includes those students for whom the result of the modification
+ process was either addition of a new photo. update of an
+ existing photo, photo was found to be missing from institution's
+ data store, photo used is same as before, or photo was
+ deleted from storage on LON-CAPA server housing student's
+ information, no student ID was available.
-# (e) $action: the type of action needed. (e.g., update, delete);
-# (f) $students: a reference to a hash with the keys set to student
-# usernames and domains in the form username:domain, and values set
-# to the studentID, if action is required for specific students.
-#
-# returns 1 parameter: 'ok' if no processing errors.
-# other course or student specific values can be stored as values
-# in the appropriate referenced hashes.
-###############################
+ (e) $action: the type of action needed. (e.g., update, delete);
+ (f) $students: a reference to a hash with the keys set to student
+ usernames and domains in the form username:domain, and values set
+ to the studentID, if action is required for specific students.
+
+ returns 1 parameter: 'ok' if no processing errors.
+ other course or student specific values can be stored as values
+ in the appropriate referenced hashes.
+
+=cut
sub institutional_photos {
my ($dom,$crs,$affiliates,$result,$action,$students) = @_;
@@ -377,22 +417,25 @@
return $outcome;
}
-###############################
-# sub photo_permission
-#
-# Incoming data: three arguments
-# (a) $dom (domain)
-# (b) $perm_reqd: a reference to a a scalar that is either 'yes'
-# if a course owner must indicate acceptance of conditions of use,
-# 'no' otherwise.
-# (c) $conditions: the text of the conditions of use.
-#
-# returns 1 parameter: 'ok' if no processing errors.
-# $$perm_reqd is set to 'yes' or 'no'
-# $$agreement is set to conditions of use - plain text string
-# which will be displayed in a textarea in a web form.
-###############################
-
+=pod
+
+=item photo_permission()
+
+ Incoming data: three arguments
+ (a) $dom (domain)
+ (b) $perm_reqd: a reference to a a scalar that is either 'yes'
+ if a course owner must indicate acceptance of conditions of use,
+ 'no' otherwise.
+ (c) $conditions: the text of the conditions of use.
+
+ returns 1 parameter: 'ok' if no processing errors.
+ $$perm_reqd is set to 'yes' or 'no'
+ $$agreement is set to conditions of use - plain text string
+ which will be displayed in a textarea in a web form.
+
+
+=cut
+
sub photo_permission {
my ($dom,$perm_reqd,$conditions) = @_;
$$perm_reqd = 'no';
@@ -401,19 +444,21 @@
return $outcome;
}
+=pod
-###############################
-# sub manager_photo_update
-#
-# Incoming data: one argument
-# (a) $dom (domain)
-#
-# returns 2 parameters: update (0 or 1), and comment.
-# Called by automated enrollment manager, to determine
-# whether "Update Student photos" button will be available,
-# and if so, the message (plain text string) that will be displayed
-# with the button.
-###############################
+=item manager_photo_update()
+
+ Incoming data: one argument
+ (a) $dom (domain)
+
+ returns 2 parameters: update (0 or 1), and comment.
+ Called by automated enrollment manager, to determine
+ whether "Update Student photos" button will be available,
+ and if so, the message (plain text string) that will be displayed
+ with the button.
+
+
+=cut
sub manager_photo_update {
my ($dom) = @_;
@@ -422,22 +467,26 @@
return ($update,$comment);
}
-###############################
-# sub check_section
-#
-# Incoming data: three arguments (+ fourth optional argument)
-# (a) $class - institutional class id (coursecode concatanated with section)
-# (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
-# 2.6 and later - comma-separated list of
-# username:domain for course owner and co-owners.)
-# (c) $dom - domain of course
-# (d) $dbh - optional database handle
-#
-# returns 1 parameter - $sectioncheck ('ok' or other value).
-# Verifies that at least one of the course owner (or co-owners) have access
-# to classlist for specific class according to institution's SIS
-# 'ok' if access available
-###############################
+=pod
+
+
+=item check_section()
+
+ Incoming data: three arguments (+ fourth optional argument)
+ (a) $class - institutional class id (coursecode concatanated with section)
+ (b) $owner - course owner (2.2 and later username:domain; pre-2.2 username;
+ 2.6 and later - comma-separated list of
+ username:domain for course owner and co-owners.)
+ (c) $dom - domain of course
+ (d) $dbh - optional database handle
+
+ returns 1 parameter - $sectioncheck ('ok' or other value).
+ Verifies that at least one of the course owner (or co-owners) have access
+ to classlist for specific class according to institution's SIS
+ 'ok' if access available
+
+
+=cut
sub check_section {
my ($class,$owner,$dom,$dbh) = @_;
@@ -445,67 +494,71 @@
return $sectioncheck;
}
-###############################
-# sub instcode_defaults
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $defaults - reference to hash which will contain default regular
-# expression matches for different components of an
-# institutional course code
-# (c) $code_order - reference to array which will contain order of
-# component parts used in institutional code.
-#
-# returns 1 parameter - ('ok' or other value).
-# Used to construct a regular expression to be used when searching for
-# courses based on fragments of an institutional code.
-# $defaults contains defaults to use for each component, and code_order
-# contains keys of hash in order in which they are to be concatenated.
-#
-# e.g., INSTITUTIONALCODE = fs03nop590
-# (MSU's course naming scheme - fs = semester, 03 = year, nop =
-# department name, 590 = course number)
-#
-# %{$defaults} = (
-# 'Year' => '\d{2}',
-# 'Semester' => '^[sfu]s',
-# 'Department' => '\w{2,3}',
-# 'Number' => '\d{3,4}\w?',
-# );
-#
-# @{$code_order} = ('Semester','Year','Department','Number');
-#
-###############################
+=pod
+
+=item instcode_defaults()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $defaults - reference to hash which will contain default regular
+ expression matches for different components of an
+ institutional course code
+ (c) $code_order - reference to array which will contain order of
+ component parts used in institutional code.
+
+ returns 1 parameter - ('ok' or other value).
+ Used to construct a regular expression to be used when searching for
+ courses based on fragments of an institutional code.
+ $defaults contains defaults to use for each component, and code_order
+ contains keys of hash in order in which they are to be concatenated.
+
+ e.g., INSTITUTIONALCODE = fs03nop590
+ (MSU's course naming scheme - fs = semester, 03 = year, nop =
+ department name, 590 = course number)
+
+ %{$defaults} = (
+ 'Year' => '\d{2}',
+ 'Semester' => '^[sfu]s',
+ 'Department' => '\w{2,3}',
+ 'Number' => '\d{3,4}\w?',
+ );
+
+ @{$code_order} = ('Semester','Year','Department','Number');
+
+=cut
sub instcode_defaults {
my ($dom,$defaults,$code_order) = @_;
return 'ok';
}
-###############################
-# sub allusers_info
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $instusers - reference to hash which will contain hashes,
-# where keys will be usernames and value will be a
-# hash of user information. Keys in the inner hash
-# will be some or all of: lastname,firstname,
-# middlename, generation, id, inststatus -
-# institutional status (e.g., faculty,staff,student)
-# Values are all scalars except inststatus,
-# which is an array.
-# (c) $instids - reference to hash which will contain ID numbers.
-# 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' 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.
-#
-###############################
+
+=pod
+
+=item allusers_info()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $instusers - reference to hash which will contain hashes,
+ where keys will be usernames and value will be a
+ hash of user information. Keys in the inner hash
+ will be some or all of: lastname,firstname,
+ middlename, generation, id, inststatus -
+ institutional status (e.g., faculty,staff,student)
+ Values are all scalars except inststatus,
+ which is an array.
+ (c) $instids - reference to hash which will contain ID numbers.
+ 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' 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.
+
+
+=cut
sub allusers_info {
my ($dom,$instusers,$instids) = @_;
@@ -513,58 +566,59 @@
return $outcome;
}
-###############################
-# sub get_userinfo
-#
-# 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
-# (d) $instusers - reference to hash which will contain info for user
-# as key = value; keys will be one or all of:
-# lastname,firstname,middlename,generation,id,inststatus -
-# institutional status (e.g., faculty,staff,student)
-# Values are all scalars except inststatus,
-# which is an array.
-# (e) $instids - reference to hash which will contain ID numbers -
-# 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.
-# (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' 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.
-#
-###############################
+=pod
+
+=item get_userinfo()
+
+ 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
+ (d) $instusers - reference to hash which will contain info for user
+ as key = value; keys will be one or all of:
+ lastname,firstname,middlename,generation,id,inststatus -
+ institutional status (e.g., faculty,staff,student)
+ Values are all scalars except inststatus,
+ which is an array.
+ (e) $instids - reference to hash which will contain ID numbers -
+ 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.
+ (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' 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.
+
+=cut
sub get_userinfo {
my ($dom,$uname,$id,$instusers,$instids,$types,
@@ -573,23 +627,25 @@
return $outcome;
}
-###############################
-# sub inst_usertypes
-#
-# Incoming data: three arguments
-# (a) $dom - domain
-# (b) $usertypes - reference to hash which will contain
-# key = value, where keys are institution
-# affiliation types (e.g., Faculty, Student etc.)
-# and values are titles (e.g., Faculty/Academic Staff)
-# (c) $order - reference to array which will contain the order in
-# 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' if no processing error, or other value
-# if an error occurred.
-#
-###############################
+=pod
+
+=item inst_usertypes()
+
+ Incoming data: three arguments
+ (a) $dom - domain
+ (b) $usertypes - reference to hash which will contain
+ key = value, where keys are institution
+ affiliation types (e.g., Faculty, Student etc.)
+ and values are titles (e.g., Faculty/Academic Staff)
+ (c) $order - reference to array which will contain the order in
+ 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' if no processing error, or other value
+ if an error occurred.
+
+
+=cut
sub inst_usertypes {
my ($dom,$usertypes,$order) = @_;
@@ -599,33 +655,34 @@
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
+=pod
-#
-# returns 'ok' if no processing error.
-#
-###############################
+=item 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.
+
+=cut
sub username_rules {
my ($dom,$ruleshash,$rulesorder) = @_;
@@ -633,25 +690,26 @@
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.
-#
-###############################
+=pod
+
+=item 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.
+
+=cut
sub id_rules {
my ($dom,$ruleshash,$rulesorder) = @_;
@@ -659,26 +717,27 @@
return $outcome;
}
-###############################
-# sub selfcreate_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)
-# 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.
-#
-###############################
+=pod
+=item selfcreate_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)
+ 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.
+
+
+=cut
sub selfcreate_rules {
my ($dom,$ruleshash,$rulesorder) = @_;
@@ -686,21 +745,23 @@
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.
-#
-###############################
+=pod
+
+=item 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.
+
+
+=cut
sub username_check {
my ($dom,$uname,$to_check,$resultshash) = @_;
@@ -708,21 +769,23 @@
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.
-#
-###############################
+=pod
+
+=item 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.
+
+
+=cut
sub id_check {
my ($dom,$id,$to_check,$resultshash) = @_;
@@ -730,21 +793,23 @@
return $outcome;
}
-###############################
-# sub selfcreate_check
-#
-# Incoming data: four arguments
-# (a) $dom - domain (scalar)
-# (b) $selfcreatename - e-mail proposed as username (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.
-#
-###############################
+=pod
+
+=item selfcreate_check()
+
+ Incoming data: four arguments
+ (a) $dom - domain (scalar)
+ (b) $selfcreatename - e-mail proposed as username (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.
+
+
+=cut
sub selfcreate_check {
my ($dom,$selfcreatename,$to_check,$resultshash) = @_;
@@ -752,19 +817,23 @@
return $outcome;
}
-###############################
-# sub AUTOLOAD
-#
-# Incoming data: none
-# Returns ''
-#
-# Prevents errors when undefined subroutines are called in this package
-# Will allow new routines added in the future to be called from lond etc.
-# without the need for customized versions of local*.pm packages to be
-# modified to include the new subroutines immediately.
-#
-# See "Programming Perl" 3rd ed. pp 296-298.
-###############################
+=pod
+
+=item AUTOLOAD()
+
+ Incoming data: none
+ Returns ''
+
+ Prevents errors when undefined subroutines are called in this package
+ Will allow new routines added in the future to be called from lond etc.
+ without the need for customized versions of local*.pm packages to be
+ modified to include the new subroutines immediately.
+
+ See "Programming Perl" 3rd ed. pp 296-298.
+
+=back
+
+=cut
sub AUTOLOAD {
our $AUTOLOAD;
--jms1227618987--