Data Storage and Retrieval

Using Newton Data Storage Objects

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.