Data Storage and Retrieval

About Data Storage on Newton Devices

Queries are now performed by the

Query

method of soups or union soups;

however, the

Query

global function still exists for compatibility with applications

using version 1.x of the Newton application programming interface. The

Query

method accepts the same query specification frame argument that the

Query

global function did; however, version 2.0 query specs provide additional features
that 1.x queries do not. For examples of the use of the

Query

method, see "Using

Queries" beginning on page 11-38. For a complete description of the query spec
frame and its slots, see "Query Specification Frame" (page 9-9) in Newton
Programmer's Reference.

Query specs no longer require a

type

slot; if this slot is present, it is ignored.

Because the order in which the cursor returns entries is determined entirely by
index values, specifying key values is sufficient to determine a range. Hence, the
use of an

endTest

function in a query spec is always unnecessary. Instead, your

query spec should specify an

endKey

or

endExclKey

value.

The

endTest

function was sometimes used for other purposes, such as stopping

the cursor after the visible portion of a list had been filled; however, this sort of test
is best performed outside the cursor to optimize performance. The caller of the
cursor's

Next

method should be able to determine when to stop retrieving soup

entries without resorting to the use of an

endTest

function.

When a cursor is generated initially and when it is reset, it references the entry
having the lowest index value in the set of entries in the selected subset. Thus, it is
usually unnecessary to use a start key, although this operation still works as in
earlier versions of system software. For those occasions when it is necessary to
start the cursor somewhere in the middle of the range, the use of a start key can be
simulated easily by invoking the cursor's

GotoKey

method immediately after

generating or resetting the cursor.

In Newton system software prior to version 1.05, storing a value of

nil

in the

indexed slot of an entry returns

nil

to the query for that entry; that is, the query

fails to find the entry. To work around this problem in older Newton systems, make
sure your indexed slots store appropriate values.

In Newton system software version 2.0, the behavior of queries on

nil

-value slots

is unspecified. For best performance, make sure your indexed slots store
appropriate values.