C H A P T E R 1 1
Data Storage and Retrieval
11-8
About Data Storage on Newton Devices
The soup definition frame specifies a name that identifies the soup to the system, a
user-visible name for the soup, a symbol identifying the application that "owns"
the soup, a user-visible string that describes the soup, and an array of index
specification frames defining the default set of indexes with which the soup is
created. For a complete description of the slots in the soup definition frame, see the
section "Soup Definition Frame" (page 9-2) in Newton Programmer's Reference.
user-visible name for the soup, a symbol identifying the application that "owns"
the soup, a user-visible string that describes the soup, and an array of index
specification frames defining the default set of indexes with which the soup is
created. For a complete description of the slots in the soup definition frame, see the
section "Soup Definition Frame" (page 9-2) in Newton Programmer's Reference.
Methods that add an entry to a union soup use the information in its soup definition
to create a member soup to hold the new entry if the member soup is not present on
the appropriate store at the time the entry is added. If a member of the union is
present on the specified store, the new entry is added to the existing member soup
and a new soup is not created. In most cases, the store in question is specified by
the user's preferences for the default storage of new data items; if necessary,
however, you can specify by store the member soup in which the new entry is to
reside. Note also that you can create union soup members explicitly, if necessary.
to create a member soup to hold the new entry if the member soup is not present on
the appropriate store at the time the entry is added. If a member of the union is
present on the specified store, the new entry is added to the existing member soup
and a new soup is not created. In most cases, the store in question is specified by
the user's preferences for the default storage of new data items; if necessary,
however, you can specify by store the member soup in which the new entry is to
reside. Note also that you can create union soup members explicitly, if necessary.
If no frames have ever been added to a particular union soup, the union's member
soups may not exist at all. You can add entries to a union soup in this state
(member soups are created automatically), but you cannot query a union soup that
has no members.
soups may not exist at all. You can add entries to a union soup in this state
(member soups are created automatically), but you cannot query a union soup that
has no members.
Member soups may be unavailable for other reasons, as well. For example, the
user might have removed a member soup temporarily by ejecting the card on
which it resides or might have removed the soup permanently by scrubbing it in
the Extras Drawer.
user might have removed a member soup temporarily by ejecting the card on
which it resides or might have removed the soup permanently by scrubbing it in
the Extras Drawer.
The descriptive information in a soup definition frame can be used to supply
information about a soup for use by the system, applications, or the user. For
example, this information can be used to make the user aware of a particular soup's
owner and function before allowing the user to delete the soup.
information about a soup for use by the system, applications, or the user. For
example, this information can be used to make the user aware of a particular soup's
owner and function before allowing the user to delete the soup.
To make a soup definition available for use, you must first register it with the
system. For information on registering and unregistering soup definitions, see the
section "Registering and Unregistering Soup Definitions" beginning on page 11-33.
system. For information on registering and unregistering soup definitions, see the
section "Registering and Unregistering Soup Definitions" beginning on page 11-33.
NewtApp applications also make use of soup definitions; for more information, see
Chapter 4, "NewtApp Applications."
Chapter 4, "NewtApp Applications."
Indexes
11
An index is a data structure that provides random access to the entries in a soup as
well as a means of ordering those entries. A designated value extracted from each
soup entry is stored separately in the soup's index as the index key for that entry.
Because the system can retrieve and sort index key values without reading their
associated soup entries into memory, indexes provide a fast and efficient means of
finding soup entries.
well as a means of ordering those entries. A designated value extracted from each
soup entry is stored separately in the soup's index as the index key for that entry.
Because the system can retrieve and sort index key values without reading their
associated soup entries into memory, indexes provide a fast and efficient means of
finding soup entries.
The system maintains all indexes automatically as soup entries are added, deleted,
or changed. Thus, index data is always up-to-date and readily available.
or changed. Thus, index data is always up-to-date and readily available.