NAME

Apache::lonnet.pm


SYNOPSIS

This file is an interface to the lonc processes of the LON-CAPA network as well as set of elaborated functions for handling information necessary for navigating through a given cluster of LON-CAPA machines within a domain. There are over 40 specialized functions in this module which handle the reading and transmission of metadata, user information (ids, names, environments, roles, logs), file information (storage, reading, directories, extensions, replication, embedded styles and descriptors), educational resources (course descriptions, section names and numbers), url hashing (to assign roles on a url basis), and translating abbreviated symbols to and from more descriptive phrases or explanations.

This is part of the LearningOnline Network with CAPA project described at http://www.lon-capa.org.


Package Variables

These are largely undocumented, so if you decipher one please note it here.

$processmarker

Contains the time this process was started and this servers host id.

$dumpcount

Counts the number of times a message log flush has been attempted (regardless of success) by this process. Used as part of the filename when messages are delayed.


NAME

Apache::lonnet - Subroutines to ask questions about things in the network.


SYNOPSIS

Invoked by other LON-CAPA modules, when they need to talk to or about objects in the network.

 &Apache::lonnet::SUBROUTINENAME(ARGUMENTS);

Common parameters:


OVERVIEW

lonnet provides subroutines which interact with the lonc/lond (TCP) network layer of LON-CAPA. They can be used to ask about classes, users, and resources.

For many of these objects you can also use this to store data about them or modify them in various ways.

Symbs

To identify a specific instance of a resource, LON-CAPA uses symbols or ``symbs''. These identifiers are built from the URL of the map, the resource number of the resource in the map, and the URL of the resource itself. The latter is somewhat redundant, but might help if maps change.

An example is

 msu/korte/parts/part1.sequence___19___msu/korte/tests/part12.problem

The respective map entry is

 <resource id="19" src="/res/msu/korte/tests/part12.problem"
  title="Problem 2">
 </resource>

Symbs are used by the random number generator, as well as to store and restore data specific to a certain instance of for example a problem.

Storing And Retrieving Data

Three of the most important functions in lonnet.pm are &Apache::lonnet::cstore(), &Apache::lonnet:restore(), and &Apache::lonnet::store(), which is is the non-critical message twin of cstore. These functions are for handlers to store a perl hash to a user's permanent data space in an easy manner, and to retrieve it again on another call. It is expected that a handler would use this once at the beginning to retrieve data, and then again once at the end to send only the new data back.

The data is stored in the user's data directory on the user's homeserver under the ID of the course.

The hash that is returned by restore will have all of the previous value for all of the elements of the hash.

Example:

 #creating a hash
 my %hash;
 $hash{'foo'}='bar';
 #storing it
 &Apache::lonnet::cstore(\%hash);
 #changing a value
 $hash{'foo'}='notbar';
 #adding a new value
 $hash{'bar'}='foo';
 &Apache::lonnet::cstore(\%hash);
 #retrieving the hash
 my %history=&Apache::lonnet::restore();
 #print the hash
 foreach my $key (sort(keys(%history))) {
   print("\%history{$key} = $history{$key}");
 }

Will print out:

 %history{1:foo} = bar
 %history{1:keys} = foo:timestamp
 %history{1:timestamp} = 990455579
 %history{2:bar} = foo
 %history{2:foo} = notbar
 %history{2:keys} = foo:bar:timestamp
 %history{2:timestamp} = 990455580
 %history{bar} = foo
 %history{foo} = notbar
 %history{timestamp} = 990455580
 %history{version} = 2

Note that the special hash entries keys, version and timestamp were added to the hash. version will be equal to the total number of versions of the data that have been stored. The timestamp attribute will be the UNIX time the hash was stored. keys is available in every historical section to list which keys were added or changed at a specific historical revision of a hash.

Warning: do not store the hash that restore returns directly. This will cause a mess since it will restore the historical keys as if the were new keys. I.E. 1:foo will become 1:1:foo etc.

Calling convention:

 my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname,$home);
 &Apache::lonnet::cstore(\%newrecord,$symb,$courseid,$domain,$uname,$home);

For more detailed information, see lonnet specific documentation.


RETURN MESSAGES


PUBLIC SUBROUTINES

Session Environment Functions

User Information

User Roles

User Modification

Course Infomation

Course Modification

Resource Subroutines

Resource Information

Storing/Retreiving Data

Network Status Functions

Apache Request

Data to String to Data

Logging Routines

These routines allow one to make log messages in the lonnet.log and lonnet.perm logfiles.

General File Helper Routines

Usererfile file routines (/uploaded*)

HTTP Helper Routines


PRIVATE SUBROUTINES

Underlying communication routines (Shouldn't call)

Resource Access Logging

Other