Data Storage and Retrieval

Using Newton Data Storage Objects

Your callback function must take any action that is appropriate to respond to the
change. Most applications have no need to respond to soup changes unless they are
open, which is why it is recommended that you register your callbacks when your
application opens and unregister them when it closes.

The arguments passed to your callback function include the name of the soup that
changed, the symbol identifying the callback function to execute, the kind of
change that occurred, and optional data such as changed soup entries. For a simple
code example, see "Registering Your Application for Change Notification"
beginning on page 11-64. For a complete description of the callback function and
its parameters, see the section "Callback Functions for Soup Change Notification"
(page 9-14) in Newton Programmer's Reference.

The

'soupEnters

and

'soupLeaves

messages are guaranteed

to be sent only when a reference to the changed soup exists. These
messages may not be sent for soups that are not in use. For
example, if no cursor object references the soup, this message
may not be sent.

Sending Notifications

11

When your application alters a soup, it may need to notify other applications that
the soup has changed. The best means of doing so depends on the exact nature
of the change.

The system provides functions and methods that transmit change notification
messages automatically after altering soups, union soups, or entries. The names of
these auto-transmit routines end with the

-Xmit

suffix. They are described

throughout this chapter in sections pertaining to the main behaviors they provide,
such as adding frames to soups as entries, changing entries, and so on.

The auto-transmit (fnOrMethodName

Xmit

) routines provide the easiest and best

way to send notifications when making a limited number of changes to a soup. For
example, to save a frame in a union soup and transmit an appropriate notification
message, use the

AddToDefaultStoreXmit

method as shown in the following

code fragment:

// get soup in which to save the new entry
local myUSoup := GetUnionSoupAlways("myUSoup:mySig");
// frame to add as new entry
local myFrame := {name: Daphne, color: tabby};
// add the entry and transmit change notification
local ent := myUSoup:AddToDefaultStoreXmit(myFrame,'|MyApp:MySig|);

The auto-transmit methods and functions accept a changeSym parameter identifying
the application that changed the soup. If you pass

nil

for the value of the