C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects
When creating soups from within your application (
function, remember that this function calls the
all values it uses. Thus, instead of passing references such as
a local copy of your soup definition into your application part's
function for its use.
function uses the value of your soup definition's
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
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
function to add the
frame to the
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.
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
method notifies applications registered for changes
union soup that the
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
function to retrieve an
existing soup by name.
Once you have a valid soup object, you can send the
message to it to
retrieve soup entries. The
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
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
all entries having an
slot. For an overview of the use of query specifications,
see "Using Queries" beginning on page 11-38.