[BACK]Return to storage.html CVS log [TXT] [DIR] Up to [LON-CAPA] / doc / homework
File:  [LON-CAPA] / doc / homework / storage.html
Revision 1.2: download - view: text, annotated - select for diffs
Thu May 31 21:21:49 2001 UTC (23 years, 5 months ago) by albertel
Branches: MAIN
CVS tags: version_1_3_X, version_1_3_3, version_1_3_2, version_1_3_1, version_1_3_0, version_1_2_X, version_1_2_99_1, version_1_2_99_0, version_1_2_1, version_1_2_0, version_1_1_X, version_1_1_99_5, version_1_1_99_4, version_1_1_99_3, version_1_1_99_2, version_1_1_99_1, version_1_1_99_0, version_1_1_3, version_1_1_2, version_1_1_1, version_1_1_0, version_1_0_99_3, version_1_0_99_2, version_1_0_99_1, version_1_0_99, version_1_0_3, version_1_0_2, version_1_0_1, version_1_0_0, version_0_99_5, version_0_99_4, version_0_99_3, version_0_99_2, version_0_99_1, version_0_99_0, version_0_6_2, version_0_6, version_0_5_1, version_0_5, version_0_4, stable_2002_spring, stable_2002_july, stable_2002_april, stable_2001_fall, conference_2003, STABLE, HEAD
- removed homeserver args, as the is handled internally

<!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);
  &Apache::lonnet::store(\%newrecord,$symb,$courseid,$domain,$uname);
    </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>\%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 homeserver dosen't exist
	in the network.
      </li>
      <li>
	<i>con_delayed</i> - the homeserver was uncontactable at
	this time. The store will be delayed until it is again
	available.
      </li>
      <li>
	<i>con_failed</i> - the homeserver 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: Wed May 30 10:52:16 EDT 2001
<!-- hhmts end -->
  </body>
</html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>