Data Storage and Retrieval

Using Newton Data Storage Objects

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.