Data Storage and Retrieval

Using Newton Data Storage Objects

indexes: [{structure: 'slot, path: 'aSlot,

type: 'string}]

};

// register soup or retrieve already-registered soup

local myUsoup := RegUnionSoup('|myApp:mySig|, mySoupDef);

You can unregister a soup definition whenever you no longer need to create the
soup it defines. If your application is the only one that uses your soup, you need
only ensure that its definition is registered while the application is actually open. If
other applications use your soup, you may wish to leave its definition registered
even after your application is closed or removed; however, most applications
unregister their soup definitions at one of these times, if only to make that much
more memory available to other applications.

The following code fragment illustrates the use of the

UnRegUnionSoup

function:

// unregister my soup def

UnRegUnionSoup (mySoupDef.Name, '|myApp:mySig|);

// don't forget to set all unused references to nil

myUsoup := nil;

Retrieving Existing Soups

11

To retrieve your own union soups, you can use the

RegUnionSoup

function as

described in "Registering and Unregistering Soup Definitions" beginning on
page 11-33. Alternatively, you can call the

GetUnionSoupAlways

global

function to retrieve any union soup by name.

Use of the

GetUnionSoupAlways

global function is straightforward, as the

following example shows. Note that you can pass system-supplied constants to this
function to retrieve soups used by the system and the built-in applications. For
more information, see Chapter 19, "Built-in Applications and System Data."

// retrieve "mySoup:mySig" union soup by name
local myUSoup := GetUnionSoupAlways("mySoup:mySig");
// retrieve soup used by built-in Names application
local names := GetUnionSoupAlways(ROM_CardFileSoupName);

Note that you can use the

IsInstance

utility function to determine whether a

specified soup is a union soup. Pass either of the symbols

'PlainSoup

or

'UnionSoup

as the value of the class parameter to this function, as shown in the

following code fragment.

IsInstance(mySoup, 'UnionSoup);