Data Storage and Retrieval

Using Newton Data Storage Objects

Note that if the query used to generate the cursor specifies a

beginKey

value, the

CountEntries

method starts counting at the first valid entry having an index key

value equal to or greater than the

beginKey

value. Similarly, if the query that

generated the cursor used an

endKey

value, the

CountEntries

method stops

counting at the last valid entry having an index key value equal to or less than the

endKey

value.

Note that the use of the

CountEntries

method is somewhat time-consuming and

may increase your application's heap space requirements; for performance reasons,
use this method only when necessary.

Getting the Current Entry's Index Key

11

The

EntryKey

cursor method returns the index key data associated with the

current cursor entry without reading the entry into the NewtonScript heap. Note,
however, that under certain circumstances the value returned by this method does
not match the entry's index key data exactly. For more information, see "Limitations
of Index Keys" on page 11-52.

Copying Cursors

11

You can clone a cursor to use for browsing soup entries without disturbing the
original cursor. Do not use the global functions

Clone

or

DeepClone

to clone

cursors. Instead, use the

Clone

method of the cursor to be copied, as shown in the

following code fragment:

local namesUSoup:= GetUnionSoupAlways(ROM_CardFileSoupName);
local namesCursor := namesUSoup:Query(nil);
local cursorCopy:= namesCursor:Clone();

Using Entries

11

This section discusses the functions and methods that work with soup entry objects
returned by cursors. This section describes

adding entries to soups

removing entries from soups

saving references to entries

modifying entries

replacing entries

sharing entry data

copying entry data

using the entry cache effectively