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>