background image
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.
© 2007-2024, o7 studio » при воспроизведении материала сайта ссылка обязательна