Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) User Manual

Page 486

C H A P T E R 1 1

Data Storage and Retrieval

11-54

Using Newton Data Storage Objects

■

getting the number of entries in cursor data

■

getting an index key from the cursor

■

copying the cursor

Getting a Cursor

Cursor objects are returned by the

Query

method. For more information, see

“Using Queries” beginning on page 11-38.

Testing Validity of the Cursor

When a storage card is inserted or a soup is created, union soups include new soups
in the union automatically as is appropriate. A cursor on a union soup may not be
able to include a new soup when the new soup’s indexes do not match those present
for the other soups in the union. In particular, this situation can occur when

■

The new soup does not have the index specified in the

indexPath

of the query

spec used to generate the cursor.

■

The query spec used to generate the cursor included a

tagSpec

and the new

soup does not have the correct tags index.

In such cases, the cursor becomes invalid. An invalid cursor returns

nil

when sent

messages such as

Entry

, and so on. Note that a valid cursor returns

nil

when it receives a message that positions it outside of the range of valid

entries. (For an example, see the text accompanying Figure 11-6 on page 11-46.)

You can test the cursor’s validity by invoking the

Status

cursor method. This

method returns the

'valid

symbol for cursors that are valid and returns the

'missingIndex

symbol when a soup referenced by the cursor is missing an

index. Your application needs to call this method when it receives either of the

'soupEnters

'soupCreated

soup change notification messages. If the

Status

method does not return the

'valid

symbol, the application must correct

the situation and recreate the cursor.

For a detailed description of the

Status

cursor method, see the section “Query

and Cursor Methods” (page 9-60) in Newton Programmer’s Reference. For a
discussion of soup change notification messages, see the section “Callback
Functions for Soup Change Notification” (page 9-14) in Newton Programmer’s
Reference.

Getting the Entry Currently Referenced by the Cursor

To obtain the entry currently referenced by the cursor, send the

Entry

message to

the cursor, as shown in the following code fragment:

// assume myCursor is valid cursor returned from a query

local theEntry := myCursor:Entry();