Data Storage and Retrieval

Using Newton Data Storage Objects

Saving Frames as Soup Entries

11

To save a frame as a soup entry, pass the frame to either of the union soup methods

AddToDefaultStoreXmit

or

AddToStoreXmit

, or pass it to the

AddXmit

soup method. Each of these methods transforms the frame presented as its
argument into a soup entry, returns the entry, and transmits a change notification
message. The following code example illustrates the use of the

AddToDefaultStoreXmit

method:

local myFrame := {text: "Some info", color: 'blue};
// assume mySoupDef is a valid soup definition
local myUSoup := RegUnionSoup(mySoupDef)
myUSoup:AddToDefaultStoreXmit(myFrame,'|MyApp:MySig|);

The new soup entry that these methods create consists of the frame presented to the
entry-creation method, along with copies of any data structures the frame
references, as well as copies of any data structures those structures reference, and
so on. Thus, you must be very cautious about making soup entries out of frames
that include references to other data structures. In general, this practice is to be
avoided--it can result in the creation of extremely large entries or entries missing
slots that were present in the original frame.

For example, the presence of a

_parent

slot in the frame presented as an

argument to these methods causes the whole

_parent

frame (and its parent, and

so on) to be stored in the resulting entry, potentially making it extremely large. An
alternative approach is to store a key symbol in the data and find the parent object
in a frame of templates at run time.

Do not include

_proto

slots in frames presented to methods that create soup

entries. These slots are not written to the soup entry and are missing when the entry
is read from the soup.

Do not save magic pointers in soup entries. Because the objects they reference are
always available in ROM, saving magic pointers is unnecessary and may cause the
entries to exceed the maximum permissible size.

Circular pointers within an entry are supported, and an entry can refer to another
by using an entry alias.

The size of an individual entry is not limited by the NewtonScript language; however,
due to various practical limitations, entries larger than about 16 KB can impact
application performance significantly. For best performance, it is recommended
that you limit the size of individual entries to 8 KB or less. Note that this total does
not include data held by virtual binary objects that the entry references; virtual
binary objects save their data separately on a store specified when the virtual binary
object is created. For more information, see "Virtual Binary Objects" on page 12-2
in Chapter 12, "Special-Purpose Objects for Data Storage and Retrieval."