Store / Restore
2 important functions in lonnet.pm are
&Apache::lonnet::store() and
&Apache::lonnet:restore(). These functions are for
handlers to store a perl hash to a users 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 begining to
retrieve data. And then once at the end to send only the new
data back.
The hash that is returned by restore will have all of
the previous value for all of the elments of the hash.
Example:
#creating a hash
my %hash;
$hash{'foo'}='bar';
#storing it
&Apache::lonnet::store(\%hash);
#changing a value
$hash{'foo'}='notbar';
#adding a new value
$hash{'bar'}='foo';
&Apache::lonnet::store(\%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::store(\%newrecord,$symb,$courseid,$domain,$uname,$home);
Arguments (only %newrecord is required the rest are somewhat
optional, read the details):
-
$symb - a string containing the internal name of the
specific instance of a resource. Usually this value can be
gotten from
&Apache::lonnet::symbread($filename). If the
argument is blank, it will attempt to use symbread()
for it. If the result is ambiguous store/restore will fail.
-
$courseid - the internal name for a course, usually
found in $ENV{'request.course.id'} which is what will
be looked at if no value is passed to the functions.
-
$domain - the domain that the user belongs to, usually
found in $ENV{'user.domain'} which is what will be
looked at if no value is passed to the functions.
-
$uname - the login name for the user, usually
found in $ENV{'user.name'} which is what will
be looked at if no value is passed to the functions.
-
$home - the homeserver for the user, usually found in
$ENV{'user.home'} but can be easily gotten from a
domain and name through
&Apache::lonnet::homeserver($uname,$domain). If no
value is passed to store/restore the value in %ENV will be
used.
-
\%newrecord - the hash to store being passed by reference
Return values:
-
an empty string - the function was unable to determine
exactly where to store or restore from. At least one of the
"optional" arguments was unable to be determined.
-
a hash - restore successfully read a old hash for this
specific user / resource instance.
-
no_such_host - the $home specfied desn't exist
in the network.
-
con_delayed - the $home was uncontactable at
this time. The store will be delayed until it is again
available.
-
con_failed - the $home was uncontactable at this
time and store was unable to delay the store until a later
time. The store failed.
-
ok - the store completed succesfully
-
error: - remote server failied to store or restore the
reason follows the :
Guy Albertelli
Last modified: Mon May 21 11:07:44 EDT 2001