Data Storage and Retrieval

Using Newton Data Storage Objects

parameter, the change notification is not sent, but the function or

method does everything else its description specifies.

Sometimes it may not be not desirable to send notifications immediately after
making each change to a soup; for example, when changing a large number of soup
entries, you might want to wait until after you've finished making all the changes to
transmit notification messages. You can use the

XmitSoupChange

global function

to send soup change notifications explicitly, as shown in the following code example:

// assume cursor and destSoup are valid
// xmit a single notification after all changes are made
while e := cursor:Entry() do EntryCopyXmit(e,destSoup,nil);
XmitSoupChange("mySoup:mySig", '|MyApp:MySig|, 'whatThe, nil);

The first argument to the

XmitSoupChange

function specifies the name of the

soup that has changed and the second argument specifies the application making
the change. The third argument is a predefined symbol specifying the kind of
change that was made, such as whether an entry was added, deleted, or changed.
Where appropriate, the final argument is change data, such as the new version of
the entry that was changed. Because this particular example makes multiple
changes to the

destSoup

soup, it passes the

'whatThe

symbol to indicate

unspecified changes, and passes

nil

as the change data. For a more detailed

discussion of change type and change data, see the section "Callback Functions for
Soup Change Notification" (page 9-14) in Newton Programmer's Reference.

Soup change notification messages are sent on a deferred basis. In most situations,
this implementation detail has no practical impact; however, you should be aware
that soup change messages are not sent until after the method that sends them
returns. For example, if your

ButtonClickScript

method causes a soup

change, the change notification message is not sent until after the

ButtonClickScript

method returns.