background image
C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects
11-59
No more than 32 KB of text (total of all strings, keeping in mind that one character
is 2 bytes) can reside in any soup entry. Another practical limitation is that there
must be space in the NewtonScript heap to hold the entire soup entry. You should
also be aware that Newton Backup Utility and Newton Connection Kit do not
support entries larger than 32K.
Keeping these limitations in mind, you can put any slots you need into your soup
entries. Entries within the same soup need not have the same set of slots. The only
slots to which you must pay special attention are those that are indexed. When you
create a soup, you specify which of its entries' slots to index. Indexed slots must
contain data of the type specified by the index. For example, if you specify that an
index is to be built on slot
foo
and that
foo
contains a text string, it's important
that every
foo
slot in every entry in the indexed soup contains a text string or
nil
.
Entries that do not have a
foo
slot will not be found in queries on the
foo
index.
Entries having a
foo
slot that contains data of some type other than
text
cause
various exceptions. For example, if you should try to add this kind of frame to an
indexed soup, the method that attempts to add the frame throws an exception; if
you try to add a new index on a slot that varies in data type from entry to entry, the
AddIndex
method throws an exception, and so on. Soup entries can contain
nil
-
value slots, but querying for such slots is not supported; that is, you can query only
for slots that hold non-
nil
values.
Removing Entries From Soups
11
To remove an entry, pass it to the
EntryRemoveFromSoupXmit
function, as
shown in the following code fragment. If you try to remove an invalid entry, this
function throws an exception. An entry can become invalid when, for example, the
user ejects the storage card on which it resides.
local myCursor := Query(nil);
local theEntry := myCursor:Entry();
if theEntry then
EntryRemoveFromSoup(theEntry, '|MyApp:MySig|);
Modifying Entries
11
Only one instance of a particular entry exists at any time, regardless of how the
entry was obtained. That is, if two cursors from two different queries on a
particular soup happen to be pointing at identical entries, they are actually both
pointing at the same entry.
When first retrieved from a soup, an entry is just an identifier. When the entry is
accessed as a frame (by getting or setting one of its slots), the complete entry frame
is constructed in the NewtonScript heap. The frame is marked to identify it as a
member of the soup from which it came.
© 2007-2017, o7 studio » при воспроизведении материала сайта ссылка обязательна