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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-39
■ the use of internationalized sorting order
■ queries on multiple-slot indexes
Querying Multiple Soups 11
Soups having the same name can be associated logically by a union soup object. To
retrieve entries from all the available soups in a union, just send the
Query
message to the union soup object.
You must query differently named soups separately, however. For example, before
scheduling a meeting, you might send the
Query message to the
ROM_CardfileSoup soup for information regarding its participants, and send
another Query message to the ROM_CalendarSoupName soup to determine
whether you have conflicting appointments at the proposed meeting time.
Entry aliases provide a handy way to save references to soup entries. You can use
entry aliases to reference entries from different soups more easily. For more
information, see “Using Entry Aliases” on page 12-7.
Querying on Single-Slot Indexes 11
This section provides code examples illustrating a variety of queries on single-slot
indexes. For more information on indexes, see “Introduction to Data Storage
Objects” on page 11-2 and “Indexes” on page 11-8.
The following code fragment presents an example of the simplest kind of index
query—it returns all entries in the soup:
local myUSoup := GetUnionSoupAlways("mySoup:mySig");
local allEntriesCursor := myUSoup:Query(nil);
When nil is passed as the query spec, as in the example above, the query result
potentially includes all entries in the soup. The cursor generated by such a query
returns entries in roughly the same order that they were added to the soup;
however, this sorting order is not guaranteed because the system recycles the values
it uses to identify entries internally. The only way to guarantee that entries are
sorted in the order they were added to a soup is to index them on your own time
stamp slot.
Most situations will require that you query for a subset of a soup’s entries, rather
than for all of its entries. That is, you’ll want to include or exclude entries
according to criteria you define. For example, you might want to find only entries
that have a certain slot, or entries in which the value of a specified slot falls within
a certain range. The next several examples illustrate the use of single-slot index
queries for these kinds of operations.
To find all entries that have a particular slot, specify a path to that slot as the query
spec’s
indexPath value. Note that in order to query on the presence of a