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

C H A P T E R 1 1
Data Storage and Retrieval
11-58 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.”