C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects
W A R N I N G
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
method (page 9-42) in Newton Programmer's Reference.
When the user scrubs your application's icon in the Extras Drawer, the system
message to your application. The
function is an optional function that you supply in your application's
This function accepts no arguments. You can remove your application's soups from
within this function by invoking the
soup method. The
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
method, see the Newton Toolkit
User's Guide. See also "RemoveFromStoreXmit" (page 9-47) in Newton
Do not delete soups from within your application's
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
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
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
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.