doc/homework/storage.html - view

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, 7 months 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_5_msu, version_2_11_5, 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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>Store / Restore</title> </head> <body> <h1>Store / Restore</h1> 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. The hash that is returned by <tt>restore</tt> will have all of the previous value for all of the elments of the hash. Example: <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> 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. <tt>1:foo</tt> will become <tt>1:1:foo</tt> etc. <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> $symb - 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> $courseid - 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> $domain - 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> $uname - 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> \%newrecord - the hash to store being passed by reference </li> </ul> <h4> Return values: </h4> <ul> <li> an empty string - 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> a hash - restore successfully read a old hash for this specific user / resource instance. </li> <li> no_such_host - the homeserver dosen't exist in the network. </li> <li> con_delayed - the homeserver was uncontactable at this time. The store will be delayed until it is again available. </li> <li> con_failed - the homeserver was uncontactable at this time and store was unable to delay the store until a later time. The store failed. </li> <li> ok - the store completed succesfully </li> <li> error: - 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>   Last modified: Wed May 30 10:52:16 EDT 2001  </body> </html>