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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-27
When creating soups from within your application ( form ) part’s InstallScript
function, remember that this function calls the EnsureInternal function on
all values it uses. Thus, instead of passing references such as
partFrame.theForm.myMainSoupDef to the RegUnionSoup function, paste
a local copy of your soup definition into your application part’s InstallScript
function for its use.
The RegUnionSoup function uses the value of your soup definition’s name slot to
determine whether a particular soup definition has already been registered. You
need not be concerned with registering a soup definition twice as long as you don’t
register different soup definitions that have the same name. An application that
registers a soup definition when it opens can always use the union soup object
returned by the
RegUnionSoup function—if the union soup named by the soup
definition exists, this function returns it; otherwise, this function uses the specified
soup definition to create and return a new union soup.
The next code fragment uses the AddToDefaultStoreXmit function to add the
myFrame frame to the myUSoup union soup. This function creates a new member
soup to hold the entry if necessary. The soup is created on the store indicated by the
user preference specifying where new items are kept.
myUSoup:AddToDefaultStoreXmit(myFrame, '|MyApp:MySig|);
At this point, we have created a soup on the store specified by the user and added
an entry to that soup without ever manipulating the store directly.
Because you’ll often need to notify other applications—or even your own
application—when you make changes to soups, all the methods that modify
soups or soup entries are capable of broadcasting an appropriate soup change
notification message automatically. In the preceding example, the
AddToDefaultStoreXmit method notifies applications registered for changes
to the myUSoup union soup that the '|MyApp:MySig| application added an
entry to this union soup. For more information, see “Callback Functions for Soup
Change Notification” (page 9-14) in Newton Programmer’s Reference.
Most of the time, your application needs to work with existing soups rather than
create new ones. You can use the
GetUnionSoupAlways function to retrieve an
existing soup by name.
Once you have a valid soup object, you can send the Query message to it to
retrieve soup entries. The Query method accepts a query specification frame as its
argument. This frame defines the criteria soup entries must meet in order to be
retrieved by this query. Although you can pass
nil as the query spec in order to
retrieve all the entries in a soup, usually you’ll want to retrieve some useful subset
of all entries. For example, the following code fragment retrieves from
myUsoup
all entries having an aSlot slot. For an overview of the use of query specifications,
see “Using Queries” beginning on page 11-38.