Annotation of doc/homework/storage.html, revision 1.3
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
1.3 ! albertel 96: found in <tt>$env{'request.course.id'}</tt> which is what will
1.1 albertel 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
1.3 ! albertel 101: found in <tt>$env{'user.domain'}</tt> which is what will be
1.1 albertel 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
1.3 ! albertel 106: found in <tt>$env{'user.name'}</tt> which is what will
1.1 albertel 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>
![[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