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

C H A P T E R 1 1
Data Storage and Retrieval
11-24 About Data Storage on Newton Devices
Query Global Function Is Obsolete 11
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 Types Obsolete 11
Query specs no longer require a type slot; if this slot is present, it is ignored.
StartKey and EndTest Obsolete 11
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.
Queries on Nil-Value Slots Unsupported 11
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.