background image
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
11
Cursor objects are returned by the
Query
method. For more information, see
"Using Queries" beginning on page 11-38.
Testing Validity of the Cursor
11
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
Next
,
Prev
,
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
or
'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
11
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();
© 2007-2017, o7 studio » при воспроизведении материала сайта ссылка обязательна