[BACK]Return to storage.html CVS log [TXT] [DIR] Up to [LON-CAPA] / doc / homework
File:  [LON-CAPA] / doc / homework / storage.html
Revision 1.3: download - view: text, annotated - select for diffs
Thu Apr 7 06:56:20 2005 UTC (19 years, 1 month ago) by albertel
Branches: MAIN
CVS tags: version_2_9_X, version_2_9_99_0, version_2_9_1, version_2_9_0, version_2_8_X, version_2_8_99_1, version_2_8_99_0, version_2_8_2, version_2_8_1, version_2_8_0, version_2_7_X, version_2_7_99_1, version_2_7_99_0, version_2_7_1, version_2_7_0, version_2_6_X, version_2_6_99_1, version_2_6_99_0, version_2_6_3, version_2_6_2, version_2_6_1, version_2_6_0, version_2_5_X, version_2_5_99_1, version_2_5_99_0, version_2_5_2, version_2_5_1, version_2_5_0, version_2_4_X, version_2_4_99_0, version_2_4_2, version_2_4_1, version_2_4_0, version_2_3_X, version_2_3_99_0, version_2_3_2, version_2_3_1, version_2_3_0, version_2_2_X, version_2_2_99_1, version_2_2_99_0, version_2_2_2, version_2_2_1, version_2_2_0, version_2_1_X, version_2_1_99_3, version_2_1_99_2, version_2_1_99_1, version_2_1_99_0, version_2_1_3, version_2_1_2, version_2_1_1, version_2_1_0, version_2_12_X, version_2_11_X, version_2_11_4_uiuc, version_2_11_4_msu, version_2_11_4, version_2_11_3_uiuc, version_2_11_3_msu, version_2_11_3, version_2_11_2_uiuc, version_2_11_2_msu, version_2_11_2_educog, version_2_11_2, version_2_11_1, version_2_11_0_RC3, version_2_11_0_RC2, version_2_11_0_RC1, version_2_11_0, version_2_10_X, version_2_10_1, version_2_10_0_RC2, version_2_10_0_RC1, version_2_10_0, version_2_0_X, version_2_0_99_1, version_2_0_2, version_2_0_1, version_2_0_0, version_1_99_3, version_1_99_2, version_1_99_1_tmcc, version_1_99_1, version_1_99_0_tmcc, version_1_99_0, loncapaMITrelate_1, language_hyphenation_merge, language_hyphenation, bz6209-base, bz6209, HEAD, GCI_3, GCI_2, GCI_1, BZ4492-merge, BZ4492-feature_horizontal_radioresponse, BZ4492-feature_Support_horizontal_radioresponse, BZ4492-Support_horizontal_radioresponse
- ENV -> env

    1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    2: <html>
    3:   <head>
    4:     <title>Store / Restore</title>
    5:   </head>
    6: 
    7:   <body>
    8:     <h1>Store / Restore</h1>
    9: 
   10:     <p>
   11:       2 important functions in lonnet.pm are
   12:       <tt>&Apache::lonnet::store()</tt> and
   13:       <tt>&Apache::lonnet:restore()</tt>. These functions are for
   14:       handlers to store a perl hash to a users permanent data space in
   15:       an easy manner, and to retrieve it again on another call.  It is
   16:       expected that a handler would use this once at the begining to
   17:       retrieve data. And then once at the end to send only the new
   18:       data back.
   19:     </p>
   20:     <p>
   21:       The hash that is returned by <tt>restore</tt> will have all of
   22:       the previous value for all of the elments of the hash.
   23:     </p>
   24:     <p>
   25:       Example: 
   26:     </p>
   27:     <pre>
   28: #creating a hash
   29: my %hash;
   30: $hash{'foo'}='bar';
   31: #storing it
   32: &Apache::lonnet::store(\%hash);
   33: #changing a value 
   34: $hash{'foo'}='notbar';
   35: #adding a new value
   36: $hash{'bar'}='foo';
   37: &Apache::lonnet::store(\%hash);
   38: #retrieving the hash
   39: my %history=&Apache::lonnet::restore();
   40: #print the hash
   41: foreach my $key (sort(keys(%history))) {
   42:     print("\%history{$key} = $history{$key}");
   43: }
   44:     </pre>
   45:     Will print out:
   46:     <pre>
   47: %history{1:foo} = bar
   48: %history{1:keys} = foo:timestamp
   49: %history{1:timestamp} = 990455579
   50: %history{2:bar} = foo
   51: %history{2:foo} = notbar
   52: %history{2:keys} = foo:bar:timestamp
   53: %history{2:timestamp} = 990455580
   54: %history{bar} = foo
   55: %history{foo} = notbar
   56: %history{timestamp} = 990455580
   57: %history{version} = 2
   58:     </pre>
   59:     <p>
   60:       Note that the special hash entries <i>keys</i>, <i>version</i>
   61:       and <i>timestamp</i> were added to the hash. <i>version</i> will
   62:       be equal to the total number of versions of the data that have
   63:       been stored. The <i>timestamp</i> attribute will be the UNIX
   64:       time the hash was stored. <i>keys</i> is available in every
   65:       historical section to list which keys were added or changed
   66:       at a specific historical revision of a hash.
   67:     </p>
   68:     <p>
   69:       <b>Warning</b> do not store the hash that restore returns
   70:       directly. This will cause a mess since it will restore the
   71:       historical keys as if the were new keys. I.E. <tt>1:foo</tt>
   72:       will become <tt>1:1:foo</tt> etc.
   73:     </p>
   74:     <h3>
   75:       Calling convention:
   76:     </h3>
   77:     <pre>
   78:   my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname);
   79:   &Apache::lonnet::store(\%newrecord,$symb,$courseid,$domain,$uname);
   80:     </pre>
   81:     <h4>
   82:       Arguments (only %newrecord is required the rest are somewhat
   83:       optional, read the details):
   84:     </h4>
   85:     <ul>
   86:       <li>
   87: 	<i>$symb</i> - a string containing the internal name of the
   88: 	specific instance of a resource. Usually this value can be
   89: 	gotten from
   90: 	<tt>&Apache::lonnet::symbread($filename)</tt>. If the
   91: 	argument is blank, it will attempt to use <tt>symbread()</tt>
   92: 	for it. If the result is ambiguous store/restore will fail.
   93:       </li>
   94:       <li>
   95: 	<i>$courseid</i> - the internal name for a course, usually
   96: 	found in <tt>$env{'request.course.id'}</tt> which is what will
   97: 	be looked at if no value is passed to the functions.
   98:       </li>
   99:       <li>
  100: 	<i>$domain</i> - the domain that the user belongs to, usually
  101: 	found in <tt>$env{'user.domain'}</tt> which is what will be
  102: 	looked at if no value is passed to the functions.
  103:       </li>
  104:       <li>
  105: 	<i>$uname</i> - the login name for the user, usually
  106: 	found in <tt>$env{'user.name'}</tt> which is what will
  107: 	be looked at if no value is passed to the functions.
  108:       </li>
  109:       <li>
  110: 	<i>\%newrecord</i> - the hash to store being passed by reference
  111:       </li>
  112:     </ul>
  113:     <h4>
  114:       Return values:
  115:     </h4>
  116:     <ul>
  117:       <li>
  118: 	<i>an empty string</i> - the function was unable to determine
  119: 	exactly where to store or restore from. At least one of the
  120: 	"optional" arguments was unable to be determined. 
  121:       </li>
  122:       <li>
  123: 	<i>a hash</i> - restore successfully read a old hash for this
  124: 	specific user / resource instance.
  125:       </li>
  126:       <li>
  127: 	<i>no_such_host</i> - the homeserver dosen't exist
  128: 	in the network.
  129:       </li>
  130:       <li>
  131: 	<i>con_delayed</i> - the homeserver was uncontactable at
  132: 	this time. The store will be delayed until it is again
  133: 	available.
  134:       </li>
  135:       <li>
  136: 	<i>con_failed</i> - the homeserver was uncontactable at this
  137: 	time and store was unable to delay the store until a later
  138: 	time. The store failed.
  139:       </li>
  140:       <li>
  141: 	<i>ok</i> - the store completed succesfully
  142:       </li>
  143:       <li>
  144: 	<i>error:</i> - remote server failied to store or restore the
  145: 	reason follows the :
  146:       </li>
  147:     </ul>
  148:     <hr>
  149:     <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
  150: <!-- Created: Mon May 21 09:58:20 EDT 2001 -->
  151: <!-- hhmts start -->
  152: Last modified: Wed May 30 10:52:16 EDT 2001
  153: <!-- hhmts end -->
  154:   </body>
  155: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>