Annotation of doc/homework/storage.html, revision 1.1
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>
! 78: my %record=&Apache::lonnet::restore($symb,$courseid,$domain,$uname,$home);
! 79: &Apache::lonnet::store(\%newrecord,$symb,$courseid,$domain,$uname,$home);
! 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>$home</i> - the homeserver for the user, usually found in
! 111: <tt>$ENV{'user.home'}</tt> but can be easily gotten from a
! 112: domain and name through
! 113: <tt>&Apache::lonnet::homeserver($uname,$domain)</tt>. If no
! 114: value is passed to store/restore the value in %ENV will be
! 115: used.
! 116: </li>
! 117: <li>
! 118: <i>\%newrecord</i> - the hash to store being passed by reference
! 119: </li>
! 120: </ul>
! 121: <h4>
! 122: Return values:
! 123: </h4>
! 124: <ul>
! 125: <li>
! 126: <i>an empty string</i> - the function was unable to determine
! 127: exactly where to store or restore from. At least one of the
! 128: "optional" arguments was unable to be determined.
! 129: </li>
! 130: <li>
! 131: <i>a hash</i> - restore successfully read a old hash for this
! 132: specific user / resource instance.
! 133: </li>
! 134: <li>
! 135: <i>no_such_host</i> - the <i>$home</i> specfied desn't exist
! 136: in the network.
! 137: </li>
! 138: <li>
! 139: <i>con_delayed</i> - the <i>$home</i> was uncontactable at
! 140: this time. The store will be delayed until it is again
! 141: available.
! 142: </li>
! 143: <li>
! 144: <i>con_failed</i> - the <i>$home</i> was uncontactable at this
! 145: time and store was unable to delay the store until a later
! 146: time. The store failed.
! 147: </li>
! 148: <li>
! 149: <i>ok</i> - the store completed succesfully
! 150: </li>
! 151: <li>
! 152: <i>error:</i> - remote server failied to store or restore the
! 153: reason follows the :
! 154: </li>
! 155: </ul>
! 156: <hr>
! 157: <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
! 158: <!-- Created: Mon May 21 09:58:20 EDT 2001 -->
! 159: <!-- hhmts start -->
! 160: Last modified: Mon May 21 11:07:44 EDT 2001
! 161: <!-- hhmts end -->
! 162: </body>
! 163: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to storage.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / doc / homework