Data Storage and Retrieval

Using Newton Data Storage Objects

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