[BACK]Return to storage.html CVS log [TXT] [DIR] Up to [LON-CAPA] / doc / homework
File:  [LON-CAPA] / doc / homework / storage.html
Revision 1.1: download - view: text, annotated - select for diffs
Mon May 21 15:24:47 2001 UTC (22 years, 11 months ago) by albertel
Branches: MAIN
CVS tags: HEAD
- new files
- deleted extra diamond

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Store / Restore</title>
  </head>

  <body>
    <h1>Store / Restore</h1>

    <p>
      2 important functions in lonnet.pm are
      <tt>&Apache::lonnet::store()</tt> and
      <tt>&Apache::lonnet:restore()</tt>. 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.
    </p>
    <p>
      The hash that is returned by <tt>restore</tt> will have all of
      the previous value for all of the elments of the hash.
    </p>
    <p>
      Example: 
    </p>
    <pre>
#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}");
}
    </pre>
    Will print out:
    <pre>
%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
    </pre>
    <p>
      Note that the special hash entries <i>keys</i>, <i>version</i>
      and <i>timestamp</i> were added to the hash. <i>version</i> will
      be equal to the total number of versions of the data that have
      been stored. The <i>timestamp</i> attribute will be the UNIX
      time the hash was stored. <i>keys</i> is available in every
      historical section to list which keys were added or changed
      at a specific historical revision of a hash.
    </p>
    <p>
      <b>Warning</b> 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. <tt>1:foo</tt>
      will become <tt>1:1:foo</tt> etc.
    </p>
    <h3>
      Calling convention:
    </h3>
    <pre>
  my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname,$home);
  &Apache::lonnet::store(\%newrecord,$symb,$courseid,$domain,$uname,$home);
    </pre>
    <h4>
      Arguments (only %newrecord is required the rest are somewhat
      optional, read the details):
    </h4>
    <ul>
      <li>
	<i>$symb</i> - a string containing the internal name of the
	specific instance of a resource. Usually this value can be
	gotten from
	<tt>&Apache::lonnet::symbread($filename)</tt>. If the
	argument is blank, it will attempt to use <tt>symbread()</tt>
	for it. If the result is ambiguous store/restore will fail.
      </li>
      <li>
	<i>$courseid</i> - the internal name for a course, usually
	found in <tt>$ENV{'request.course.id'}</tt> which is what will
	be looked at if no value is passed to the functions.
      </li>
      <li>
	<i>$domain</i> - the domain that the user belongs to, usually
	found in <tt>$ENV{'user.domain'}</tt> which is what will be
	looked at if no value is passed to the functions.
      </li>
      <li>
	<i>$uname</i> - the login name for the user, usually
	found in <tt>$ENV{'user.name'}</tt> which is what will
	be looked at if no value is passed to the functions.
      </li>
      <li>
	<i>$home</i> - the homeserver for the user, usually found in
	<tt>$ENV{'user.home'}</tt> but can be easily gotten from a
	domain and name through
	<tt>&Apache::lonnet::homeserver($uname,$domain)</tt>. If no
	value is passed to store/restore the value in %ENV will be
	used.
      </li>
      <li>
	<i>\%newrecord</i> - the hash to store being passed by reference
      </li>
    </ul>
    <h4>
      Return values:
    </h4>
    <ul>
      <li>
	<i>an empty string</i> - 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. 
      </li>
      <li>
	<i>a hash</i> - restore successfully read a old hash for this
	specific user / resource instance.
      </li>
      <li>
	<i>no_such_host</i> - the <i>$home</i> specfied desn't exist
	in the network.
      </li>
      <li>
	<i>con_delayed</i> - the <i>$home</i> was uncontactable at
	this time. The store will be delayed until it is again
	available.
      </li>
      <li>
	<i>con_failed</i> - the <i>$home</i> was uncontactable at this
	time and store was unable to delay the store until a later
	time. The store failed.
      </li>
      <li>
	<i>ok</i> - the store completed succesfully
      </li>
      <li>
	<i>error:</i> - remote server failied to store or restore the
	reason follows the :
      </li>
    </ul>
    <hr>
    <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
<!-- Created: Mon May 21 09:58:20 EDT 2001 -->
<!-- hhmts start -->
Last modified: Mon May 21 11:07:44 EDT 2001
<!-- hhmts end -->
  </body>
</html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>