Data Storage and Retrieval

Using Newton Data Storage Objects

Each soup has only one tags index; if you add a tags index to a
soup that already has one, it replaces the original tags index. For
more information, see the description of the

AddIndexXmit

method (page 9-42) in Newton Programmer's Reference.

Removing Soups

11

When the user scrubs your application's icon in the Extras Drawer, the system
sends a

DeletionScript

message to your application. The

DeletionScript

function is an optional function that you supply in your application's

form

part.

This function accepts no arguments. You can remove your application's soups from
within this function by invoking the

RemoveFromStoreXmit

soup method. The

RemoveFromStoreXmit

method is defined only for single soups; in other words,

you must remove each member of a union soup separately.

For more information on the

DeletionScript

method, see the Newton Toolkit

User's Guide. See also "RemoveFromStoreXmit" (page 9-47) in Newton
Programmer's Reference.

Do not delete soups from within your application's

viewQuitScript

method--

user data needs to be preserved until the next time the application is run. For
similar reasons, do not remove soups from within your application's

RemoveScript

method. This method does not distinguish between removing

software permanently (scrubbing its icon in the Extras Drawer) and removing
software temporarily (ejecting the PCMCIA card.)

Using Built-in Soups

11

The soup-based data storage model makes it easy for applications to reuse existing
system-supplied soups for their own needs and to share their own soups with other
applications. Refer to Chapter 19, "Built-in Applications and System Data," to see
descriptions of the soups used by the applications built into the Newton ROM. You
can also use these descriptions as a model for documenting the structure of your
application's shared soups.

Making Changes to Other Applications' Soups

11

You should avoid changing other applications' soups if at all possible. If you must
make changes to another application's soup, be sure to respect the format of that
soup as documented by its creator. When possible, confine your changes to a single
slot that you create in any soup entry you modify.

When naming slots you add to other applications' soups, exercise the same caution
you would in naming soups themselves--use your application name and developer
signature in the slot name to avoid name-space conflicts.