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 NewtonProgrammer'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.