Annotation of doc/homework/storage.html, revision 1.2

1.1       albertel    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>
1.2     ! albertel   78:   my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname);
        !            79:   &Apache::lonnet::store(\%newrecord,$symb,$courseid,$domain,$uname);
1.1       albertel   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>
1.2     ! albertel  127: 	<i>no_such_host</i> - the homeserver dosen't exist
1.1       albertel  128: 	in the network.
                    129:       </li>
                    130:       <li>
1.2     ! albertel  131: 	<i>con_delayed</i> - the homeserver was uncontactable at
1.1       albertel  132: 	this time. The store will be delayed until it is again
                    133: 	available.
                    134:       </li>
                    135:       <li>
1.2     ! albertel  136: 	<i>con_failed</i> - the homeserver was uncontactable at this
1.1       albertel  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 -->
1.2     ! albertel  152: Last modified: Wed May 30 10:52:16 EDT 2001
1.1       albertel  153: <!-- hhmts end -->
                    154:   </body>
                    155: </html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>