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):

Return values:


Guy Albertelli
Last modified: Mon May 21 11:07:44 EDT 2001