: gets the values of the keys
+passed in @what from the requested user's environment, returns a hash
-reconlonc() : tries to reconnect lonc client processes.
+=back
+
+=head2 User Roles
+
+=over 4
=item *
-critical() : passes a critical message to another server; if cannot get
-through then place message in connection buffer
+allowed($priv,$uri) : check for a user privilege; returns codes for allowed
+actions
+ F: full access
+ U,I,K: authentication modes (cxx only)
+ '': forbidden
+ 1: user needs to choose course
+ 2: browse allowed
=item *
-appenv(%hash) : read in current user environment, append new environment
-values to make new user environment
+definerole($rolename,$sysrole,$domrole,$courole) : define role; define a custom
+role rolename set privileges in format of lonTabs/roles.tab for system, domain,
+and course level
=item *
-delenv($varname) : read in current user environment, remove all values
-beginning with $varname, write new user environment (note: flock is used
-to prevent conflicting shared read/writes with file)
+plaintext($short) : return value in %prp hash (rolesplain.tab); plain text
+explanation of a user role term
+
+=back
+
+=head2 User Modification
+
+=over 4
=item *
-spareserver() : find server with least workload from spare.tab
+assignrole($udom,$uname,$url,$role,$end,$start) : assign role; give a role to a
+user for the level given by URL. Optional start and end dates (leave empty
+string or zero for "no date")
=item *
-queryauthenticate($uname,$udom) : try to determine user's current
-authentication scheme
+changepass($uname,$udom,$currentpass,$newpass,$server) : attempts to
+change a users, password, possible return values are: ok,
+pwchange_failure, non_authorized, auth_mode_error, unknown_user,
+refused
=item *
-authenticate($uname,$upass,$udom) : try to authenticate user from domain's lib
-servers (first use the current one)
+modifyuserauth($udom,$uname,$umode,$upass) : modify user authentication
=item *
-homeserver($uname,$udom) : find the homebase for a user from domain's lib
-servers
+modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene) :
+modify user
=item *
-idget($udom,@ids) : find the usernames behind a list of IDs (returns hash:
-id=>name,id=>name)
+modifystudent
+
+modify a students enrollment and identification information.
+The course id is resolved based on the current users environment.
+This means the envoking user must be a course coordinator or otherwise
+associated with a course.
+
+This call is essentially a wrapper for lonnet::modifyuser and
+lonnet::modify_student_enrollment
+
+Inputs:
+
+=over 4
+
+=item B<$udom> Students loncapa domain
+
+=item B<$uname> Students loncapa login name
+
+=item B<$uid> Students id/student number
+
+=item B<$umode> Students authentication mode
+
+=item B<$upass> Students password
+
+=item B<$first> Students first name
+
+=item B<$middle> Students middle name
+
+=item B<$last> Students last name
+
+=item B<$gene> Students generation
+
+=item B<$usec> Students section in course
+
+=item B<$end> Unix time of the roles expiration
+
+=item B<$start> Unix time of the roles start date
+
+=item B<$forceid> If defined, allow $uid to be changed
+
+=item B<$desiredhome> server to use as home server for student
+
+=back
=item *
-idrget($udom,@unames) : find the IDs behind a list of usernames (returns hash:
-name=>id,name=>id)
+modify_student_enrollment
+
+Change a students enrollment status in a class. The environment variable
+'role.request.course' must be defined for this function to proceed.
+
+Inputs:
+
+=over 4
+
+=item $udom, students domain
+
+=item $uname, students name
+
+=item $uid, students user id
+
+=item $first, students first name
+
+=item $middle
+
+=item $last
+
+=item $gene
+
+=item $usec
+
+=item $end
+
+=item $start
+
+=back
+
=item *
-idput($udom,%ids) : store away a list of names and associated IDs
+assigncustomrole($udom,$uname,$url,$rdom,$rnam,$rolename,$end,$start) : assign
+custom role; give a custom role to a user for the level given by URL. Specify
+name and domain of role author, and role name
=item *
-usection($domain,$user,$courseid) : output of section name/number or '' for
-"not in course" and '-1' for "no section"
+revokerole($udom,$uname,$url,$role) : revoke a role for url
=item *
-userenvironment($domain,$user,$what) : puts out any environment parameter
-for a user
+revokecustomrole($udom,$uname,$url,$role) : revoke a custom role
+
+=back
+
+=head2 Course Infomation
+
+=over 4
=item *
-subscribe($fname) : subscribe to a resource, return URL if possible
+coursedescription($courseid) : course description
=item *
-repcopy($filename) : replicate file
+courseresdata($coursenum,$coursedomain,@which) : request for current
+parameter setting for a specific course, @what should be a list of
+parameters to ask about. This routine caches answers for 5 minutes.
+
+=back
+
+=head2 Course Modification
+
+=over 4
=item *
-ssi($url,%hash) : server side include, does a complete request cycle on url to
-localhost, posts hash
+writecoursepref($courseid,%prefs) : write preferences (environment
+database) for a course
=item *
-log($domain,$name,$home,$message) : write to permanent log for user; use
-critical subroutine
+createcourse($udom,$description,$url) : make/modify course
+
+=back
+
+=head2 Resource Subroutines
+
+=over 4
=item *
-flushcourselogs() : flush (save) buffer logs and access logs
+subscribe($fname) : subscribe to a resource, returns URL if possible (probably should use repcopy instead)
=item *
-courselog($what) : save message for course in hash
+repcopy($filename) : subscribes to the requested file, and attempts to
+replicate from the owning library server, Might return
+HTTP_SERVICE_UNAVAILABLE, HTTP_NOT_FOUND, FORBIDDEN, OK, or
+HTTP_BAD_REQUEST, also attempts to grab the metadata for the
+resource. Expects the local filesystem pathname
+(/home/httpd/html/res/....)
+
+=back
+
+=head2 Resource Information
+
+=over 4
=item *
-courseacclog($what) : save message for course using &courselog(). Perform
-special processing for specific resource types (problems, exams, quizzes, etc).
+EXT($varname,$symb,$udom,$uname) : evaluates and returns the value of
+a vairety of different possible values, $varname should be a request
+string, and the other parameters can be used to specify who and what
+one is asking about.
+
+Possible values for $varname are environment.lastname (or other item
+from the envirnment hash), user.name (or someother aspect about the
+user), resource.0.maxtries (or some other part and parameter of a
+resource)
=item *
-countacc($url) : count the number of accesses to a given URL
+directcondval($number) : get current value of a condition; reads from a state
+string
=item *
-sub checkout($symb,$tuname,$tudom,$tcrsid) : check out an item
+condval($condidx) : value of condition index based on state
=item *
-sub checkin($token) : check in an item
+metadata($uri,$what,$liburi,$prefix,$depthcount) : request a
+resource's metadata, $what should be either a specific key, or either
+'keys' (to get a list of possible keys) or 'packages' to get a list of
+packages that this resource currently uses, the last 3 arguments are only used internally for recursive metadata.
+
+this function automatically caches all requests
=item *
-sub expirespread($uname,$udom,$stype,$usymb) : set expire date for spreadsheet
+metadata_query($query,$custom,$customshow) : make a metadata query against the
+network of library servers; returns file handle of where SQL and regex results
+will be stored for query
=item *
-devalidate($symb) : devalidate spreadsheets
+symbread($filename) : return symbolic list entry (filename argument optional);
+returns the data handle
=item *
-hash2str(%hash) : convert a hash into a string complete with escaping and '='
-and '&' separators, supports elements that are arrayrefs and hashrefs
+symbverify($symb,$thisfn) : verifies that $symb actually exists and is
+a possible symb for the URL in $thisfn, and if is an encryypted
+resource that the user accessed using /enc/ returns a 1 on success, 0
+on failure, user must be in a course, as it assumes the existance of
+the course initial hash, and uses $ENV('request.course.id'}
+
=item *
-hashref2str($hashref) : convert a hashref into a string complete with
-escaping and '=' and '&' separators, supports elements that are
-arrayrefs and hashrefs
+symbclean($symb) : removes versions numbers from a symb, returns the
+cleaned symb
=item *
-arrayref2str($arrayref) : convert an arrayref into a string complete
-with escaping and '&' separators, supports elements that are arrayrefs
-and hashrefs
+is_on_map($uri) : checks if the $uri is somewhere on the current
+course map, user must be in a course for it to work.
=item *
-str2hash($string) : convert string to hash using unescaping and
-splitting on '=' and '&', supports elements that are arrayrefs and
-hashrefs
+numval($salt) : return random seed value (addend for rndseed)
=item *
-str2array($string) : convert string to hash using unescaping and
-splitting on '&', supports elements that are arrayrefs and hashrefs
+rndseed($symb,$courseid,$udom,$uname) : create a random sum; returns
+a random seed, all arguments are optional, if they aren't sent it uses the
+environment to derive them. Note: if symb isn't sent and it can't get one
+from &symbread it will use the current time as its return value
=item *
-tmpreset($symb,$namespace,$domain,$stuname) : temporary storage
+ireceipt($funame,$fudom,$fucourseid,$fusymb) : return unique,
+unfakeable, receipt
=item *
-tmprestore($symb,$namespace,$domain,$stuname) : temporary restore
+receipt() : API to ireceipt working off of ENV values; given out to users
=item *
-store($storehash,$symb,$namespace,$domain,$stuname) : stores hash permanently
+countacc($url) : count the number of accesses to a given URL
+
+=item *
+
+checkout($symb,$tuname,$tudom,$tcrsid) : creates a record of a user having looked at an item, most likely printed out or otherwise using a resource
+
+=item *
+
+checkin($token) : updates that a resource has beeen returned (a hard copy version for instance) and returns the data that $token was Checkout with ($symb, $tuname, $tudom, and $tcrsid)
+
+=item *
+
+expirespread($uname,$udom,$stype,$usymb) : set expire date for spreadsheet
+
+=item *
+
+devalidate($symb) : devalidate temporary spreadsheet calculations,
+forcing spreadsheet to reevaluate the resource scores next time.
+
+=back
+
+=head2 Storing/Retreiving Data
+
+=over 4
+
+=item *
+
+store($storehash,$symb,$namespace,$udom,$uname) : stores hash permanently
for this url; hashref needs to be given and should be a \%hashname; the
remaining args aren't required and if they aren't passed or are '' they will
be derived from the ENV
=item *
-cstore($storehash,$symb,$namespace,$domain,$stuname) : same as store but
+cstore($storehash,$symb,$namespace,$udom,$uname) : same as store but
uses critical subroutine
=item *
-restore($symb,$namespace,$domain,$stuname) : returns hash for this symb;
+restore($symb,$namespace,$udom,$uname) : returns hash for this symb;
all args are optional
=item *
-coursedescription($courseid) : course description
+tmpstore($storehash,$symb,$namespace,$udom,$uname) : storage that
+works very similar to store/cstore, but all data is stored in a
+temporary location and can be reset using tmpreset, $storehash should
+be a hash reference, returns nothing on success
=item *
-rolesinit($domain,$username,$authhost) : get user privileges
+tmprestore($symb,$namespace,$udom,$uname) : storage that works very
+similar to restore, but all data is stored in a temporary location and
+can be reset using tmpreset. Returns a hash of values on success,
+error string otherwise.
=item *
-get($namespace,$storearr,$udomain,$uname) : returns hash with keys from array
-reference filled in from namesp ($udomain and $uname are optional)
+tmpreset($symb,$namespace,$udom,$uname) : temporary storage reset,
+deltes all keys for $symb form the temporary storage hash.
=item *
-del($namespace,$storearr,$udomain,$uname) : deletes keys out of array from
-namesp ($udomain and $uname are optional)
+get($namespace,$storearr,$udom,$uname) : returns hash with keys from array
+reference filled in from namesp ($udom and $uname are optional)
=item *
-dump($namespace,$udomain,$uname,$regexp) :
-dumps the complete (or key matching regexp) namespace into a hash
-($udomain, $uname and $regexp are optional)
+del($namespace,$storearr,$udom,$uname) : deletes keys out of array from
+namesp ($udom and $uname are optional)
=item *
-put($namespace,$storehash,$udomain,$uname) : stores hash in namesp
-($udomain and $uname are optional)
+dump($namespace,$udom,$uname,$regexp) :
+dumps the complete (or key matching regexp) namespace into a hash
+($udom, $uname and $regexp are optional)
=item *
-cput($namespace,$storehash,$udomain,$uname) : critical put
-($udomain and $uname are optional)
+inc($namespace,$store,$udom,$uname) : increments $store in $namespace.
+$store can be a scalar, an array reference, or if the amount to be
+incremented is > 1, a hash reference.
+
+($udom and $uname are optional)
=item *
-eget($namespace,$storearr,$udomain,$uname) : returns hash with keys from array
-reference filled in from namesp (encrypts the return communication)
-($udomain and $uname are optional)
+put($namespace,$storehash,$udom,$uname) : stores hash in namesp
+($udom and $uname are optional)
=item *
-allowed($priv,$uri) : check for a user privilege; returns codes for allowed
-actions
- F: full access
- U,I,K: authentication modes (cxx only)
- '': forbidden
- 1: user needs to choose course
- 2: browse allowed
+putstore($namespace,$storehash,$udomain,$uname) : stores hash in namesp
+keys used in storehash include version information (e.g., 1:$symb:message etc.) as
+used in records written by &store and retrieved by &restore. This function
+was created for use in editing discussion posts, without incrementing the
+version number included in the key for a particular post. The colon
+separated list of attribute names (e.g., the value associated with the key
+1:keys:$symb) is also generated and passed in the ampersand separated
+items sent to lonnet::reply().
=item *
-definerole($rolename,$sysrole,$domrole,$courole) : define role; define a custom
-role rolename set privileges in format of lonTabs/roles.tab for system, domain,
-and course level
+cput($namespace,$storehash,$udom,$uname) : critical put
+($udom and $uname are optional)
=item *
-metadata_query($query,$custom,$customshow) : make a metadata query against the
-network of library servers; returns file handle of where SQL and regex results
-will be stored for query
+eget($namespace,$storearr,$udom,$uname) : returns hash with keys from array
+reference filled in from namesp (encrypts the return communication)
+($udom and $uname are optional)
=item *
-plaintext($short) : return value in %prp hash (rolesplain.tab); plain text
-explanation of a user role term
+log($udom,$name,$home,$message) : write to permanent log for user; use
+critical subroutine
-=item *
+=back
-assignrole($udom,$uname,$url,$role,$end,$start) : assign role; give a role to a
-user for the level given by URL. Optional start and end dates (leave empty
-string or zero for "no date")
+=head2 Network Status Functions
+
+=over 4
=item *
-modifyuserauth($udom,$uname,$umode,$upass) : modify user authentication
+dirlist($uri) : return directory list based on URI
=item *
-modifyuser($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene) :
-modify user
+spareserver() : find server with least workload from spare.tab
-=item *
+=back
+
+=head2 Apache Request
-modifystudent($udom,$uname,$uid,$umode,$upass,$first,$middle,$last,$gene,$usec,
-$end,$start) : modify student
+=over 4
=item *
-writecoursepref($courseid,%prefs) : write preferences for a course
+ssi($url,%hash) : server side include, does a complete request cycle on url to
+localhost, posts hash
+
+=back
+
+=head2 Data to String to Data
+
+=over 4
=item *
-createcourse($udom,$description,$url) : make/modify course
+hash2str(%hash) : convert a hash into a string complete with escaping and '='
+and '&' separators, supports elements that are arrayrefs and hashrefs
=item *
-assigncustomrole($udom,$uname,$url,$rdom,$rnam,$rolename,$end,$start) : assign
-custom role; give a custom role to a user for the level given by URL. Specify
-name and domain of role author, and role name
+hashref2str($hashref) : convert a hashref into a string complete with
+escaping and '=' and '&' separators, supports elements that are
+arrayrefs and hashrefs
=item *
-revokerole($udom,$uname,$url,$role) : revoke a role for url
+arrayref2str($arrayref) : convert an arrayref into a string complete
+with escaping and '&' separators, supports elements that are arrayrefs
+and hashrefs
=item *
-revokecustomrole($udom,$uname,$url,$role) : revoke a custom role
+str2hash($string) : convert string to hash using unescaping and
+splitting on '=' and '&', supports elements that are arrayrefs and
+hashrefs
=item *
-dirlist($uri) : return directory list based on URI
+str2array($string) : convert string to hash using unescaping and
+splitting on '&', supports elements that are arrayrefs and hashrefs
+
+=back
+
+=head2 Logging Routines
+
+=over 4
+
+These routines allow one to make log messages in the lonnet.log and
+lonnet.perm logfiles.
=item *
-directcondval($number) : get current value of a condition; reads from a state
-string
+logtouch() : make sure the logfile, lonnet.log, exists
=item *
-condval($condidx) : value of condition index based on state
+logthis() : append message to the normal lonnet.log file, it gets
+preiodically rolled over and deleted.
=item *
-EXT($varname,$symbparm) : value of a variable
+logperm() : append a permanent message to lonnet.perm.log, this log
+file never gets deleted by any automated portion of the system, only
+messages of critical importance should go in here.
+
+=back
+
+=head2 General File Helper Routines
+
+=over 4
=item *
-metadata($uri,$what,$liburi,$prefix,$depthcount) : get metadata; returns the
-metadata entry for a file; entry='keys', returns a comma separated list of keys
+getfile($file,$caller) : two cases - requests for files in /res or in /uploaded.
+(a) files in /uploaded
+ (i) If a local copy of the file exists -
+ compares modification date of local copy with last-modified date for
+ definitive version stored on home server for course. If local copy is
+ stale, requests a new version from the home server and stores it.
+ If the original has been removed from the home server, then local copy
+ is unlinked.
+ (ii) If local copy does not exist -
+ requests the file from the home server and stores it.
+
+ If $caller is 'uploadrep':
+ This indicates a call from lonuploadrep.pm (PerlHeaderParserHandler phase)
+ for request for files originally uploaded via DOCS.
+ - returns 'ok' if fresh local copy now available, -1 otherwise.
+
+ Otherwise:
+ This indicates a call from the content generation phase of the request.
+ - returns the entire contents of the file or -1.
+
+(b) files in /res
+ - returns the entire contents of a file or -1;
+ it properly subscribes to and replicates the file if neccessary.
=item *
-symblist($mapname,%newhash) : update symbolic storage links
+filelocation($dir,$file) : returns file system location of a file
+based on URI; meant to be "fairly clean" absolute reference, $dir is a
+directory that relative $file lookups are to looked in ($dir of /a/dir
+and a file of ../bob will become /a/bob)
=item *
-symbread($filename) : return symbolic list entry (filename argument optional);
-returns the data handle
+hreflocation($dir,$file) : returns file system location or a URL; same as
+filelocation except for hrefs
=item *
-numval($salt) : return random seed value (addend for rndseed)
+declutter() : declutters URLs (remove docroot, beginning slashes, 'res' etc)
+
+=back
+
+=head2 HTTP Helper Routines
+
+=over 4
=item *
-rndseed($symb,$courseid,$domain,$username) : create a random sum; returns
-a random seed, all arguments are optional, if they aren't sent it uses the
-environment to derive them. Note: if symb isn't sent and it can't get one
-from &symbread it will use the current time as its return value
+escape() : unpack non-word characters into CGI-compatible hex codes
=item *
-ireceipt($funame,$fudom,$fucourseid,$fusymb) : return unique,
-unfakeable, receipt
+unescape() : pack CGI-compatible hex codes into actual non-word ASCII character
+
+=back
+
+=head1 PRIVATE SUBROUTINES
+
+=head2 Underlying communication routines (Shouldn't call)
+
+=over 4
=item *
-receipt() : API to ireceipt working off of ENV values; given out to users
+subreply() : tries to pass a message to lonc, returns con_lost if incapable
=item *
-getfile($file) : serves up a file, returns the contents of a file or -1;
-replicates and subscribes to the file
+reply() : uses subreply to send a message to remote machine, logs all failures
=item *
-filelocation($dir,$file) : returns file system location of a file based on URI;
-meant to be "fairly clean" absolute reference
+critical() : passes a critical message to another server; if cannot
+get through then place message in connection buffer directory and
+returns con_delayed, if incapable of saving message, returns
+con_failed
=item *
-hreflocation($dir,$file) : returns file system location or a URL; same as
-filelocation except for hrefs
+reconlonc() : tries to reconnect lonc client processes.
+
+=back
+
+=head2 Resource Access Logging
+
+=over 4
=item *
-declutter() : declutters URLs (remove docroot, beginning slashes, 'res' etc)
+flushcourselogs() : flush (save) buffer logs and access logs
=item *
-escape() : unpack non-word characters into CGI-compatible hex codes
+courselog($what) : save message for course in hash
=item *
-unescape() : pack CGI-compatible hex codes into actual non-word ASCII character
+courseacclog($what) : save message for course using &courselog(). Perform
+special processing for specific resource types (problems, exams, quizzes, etc).
=item *
@@ -3280,4 +6664,14 @@ as a PerlChildExitHandler
=back
+=head2 Other
+
+=over 4
+
+=item *
+
+symblist($mapname,%newhash) : update symbolic storage links
+
+=back
+
=cut
500 Internal Server Error
Internal Server Error
The server encountered an internal error or
misconfiguration and was unable to complete
your request.
Please contact the server administrator at
root@localhost to inform them of the time this error occurred,
and the actions you performed just before this error.
More information about this error may be available
in the server error log.