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

HTTP Helper Routines


PRIVATE SUBROUTINES

Underlying communication routines (Shouldn't call)

Resource Access Logging

Other