Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 466)

C H A P T E R 1 1
Data Storage and Retrieval
11-34 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);