Data Storage and Retrieval

Using Newton Data Storage Objects

Registering and Unregistering Soup Definitions

11

The

RegUnionSoup

global function registers a soup definition with the system

and returns a union soup object to which you can send messages. Once the soup
definition is registered, various union soup methods create the union's member
soups as needed to save entries. A corollary function,

UnRegUnionSoup

,

unregisters a specified soup definition.

You can register a soup definition with the system any time before your application
needs to access the soup it defines. If your application is the only one using your
soup, you need only ensure that its definition is registered while the application is
actually open. Normally, code that registers soup definitions is provided by your
application part's

InstallScript

function or your application base view's

ViewSetupFormScript

method. 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.

Code to unregister soup definitions is usually provided either by your application
base view's

ViewQuitScript

method (to unregister when the application closes)

or your application part's

DeletionScript

function (to unregister only when the

application is removed.) An application that allows the user to file or move data
items from the Extras Drawer should allow its soup definitions to remain registered
while the application is closed, unregistering them only when the application is
removed. For more information on manipulating soup entries from the Extras
Drawer, see "About Icons and the Extras Drawer" on page 19-38 in Chapter 19,
"Built-in Applications and System Data."

Your application can also call the

RegUnionSoup

function to retrieve its own

union soups that already exist. If you call

RegUnionSoup

on a soup definition

that is already registered, this function replaces the currently registered soup
definition with the new one and returns the union soup named by the soup
definition passed as its argument; if that union soup does not exist, this method
uses the soup definition passed as its argument to create a new union soup that it
returns. Alternatively, you can call the

GetUnionSoupAlways

global function to

retrieve any extant union soup, not just those your application registers. For more
information, see "Retrieving Existing Soups" beginning on page 11-34.

To use the

RegUnionSoup

function, you might put code like the following

example in the

ViewSetupFormScript

method of your application's base view:

local mySoupDef := {name: "mySoup:mySig",

userName: "My Soup",
ownerApp: '|MyApp:MySig|,
ownerAppName : "My Application",
userDescr: "This is the My Application soup.",