Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 491)

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.