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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-35
Adding Entries to Soups 11
This section describes how to add a frame to a union soup or a specified member
soup in a union. For information on creating union soups, see “Registering and
Unregistering Soup Definitions” on page 11-33. For information on retrieving
union soups, see “Retrieving Existing Soups” on page 11-34.
You can use either of the AddToDefaultStoreXmit or AddToStoreXmit
methods to save frames as soup entries. Both of these methods create a single soup
in which to save the new entry when the appropriate member of the union is not
already present on the store. The
AddToDefaultStoreXmit method adds its
entry to the member soup on the store specified by the user as the destination for
new entries. The
AddToStoreXmit method allows you to specify according to
store the member soup to which it adds the new entry.
Methods that create soup entries—such as the AddToDefaultStoreXmit ,
AddToStoreXmit , and AddXmit methods—destructively modify the frame
presented as their argument to transform it into a soup entry. Thus, any frame
passed to these methods must allow write access. If the original frame must remain
unmodified, pass a copy of it to these methods.
The following code fragment saves a frame in the default store member of the
myUsoup union by sending the AddToDefaultStoreXmit message to the
union soup object that the RegUnionSoup function returns:
// register soup def’n or get reference to already registered soup
local myUsoup := RegUnionSoup('|myApp:mySig|, mySoupDef);
// add the entry and transmit notification
local myEntry := myUSoup:AddToDefaultStoreXmit(
{aSlot:"my data"}, // frame to add to soup
'|myApp:mySig|); // app that changed soup
The following code fragment saves a frame in the internal store member of the
myUsoup union by sending the AddToStoreXmit message to the union soup
object that the GetUnionSoupAlways function returns:
// get pre-existing uSoup by name
local myUSoup := GetUnionSoupAlways("mySoup:mySig");
// add entry to member on internal store and transmit notification
local myEntry := myUSoup:AddToStoreXmit(
{aSlot:"my data"}, // frame to add to soup
(GetStores()[0]), // add to member on internal store
'|myApp:mySig|); // app that changed soup