Data Storage and Retrieval

Using Newton Data Storage Objects

// get from myUSoup all entries having an aSlot slot
local myCursor := myUSoup:Query({indexPath: 'aSlot});

The

Query

method returns a cursor object that iterates over the set of soup entries

satisfying the query specification passed as its argument. You can send messages to
the cursor to change its position and to retrieve specified entries, as shown in the
following example. For an overview of cursor-manipulation functions, see
"Moving the Cursor" beginning on page 11-55.

// move the cursor two positions ahead in index order
myCursor:Move(2);
// retrieve the entry at the cursor's current position
local myEntry := myCursor:Entry();

For the purposes of discussion, assume that the cursor returned the entry holding
the

myFrame

frame. When accessing this frame, use the NewtonScript dot

operator (

.

) to dereference any of its slots. In the current example, the expression

myEntry.aSlot

evaluates to the

"some string data"

value and the

expression

myEntry.otherSlot

evaluates to the

9258

value.

As soon as any slot in the entry is referenced, the system reads entry data into a
cache in memory and sets the

myEntry

variable to reference the cache, rather than

the soup entry. This is important to understand for the following reasons:

Referencing a single slot in an entry costs you time and memory space, even if
you only examine or print the slot's value without modifying it.

Changing the value of a slot in the entry really changes the cached entry frame,
not the original soup entry; changes to the soup entry are not persistent until the
cached entry frame is written back to the soup, where it takes the place of the
original entry.

You can treat the cached entry frame as the

myFrame

frame and assign a new

value to the

aSlot

slot directly, as shown in the following code fragment:

myEntry.aSlot := "new and improved string data";

To make the changes permanent, you must use

EntryChangeXmit

or a similar

function to write the cached entry frame back to the soup, as in the following example:

EntryChangeXmit(myEntry, '|MyApp:MySig| );

Like the other functions and methods that make changes to soups, the

EntryChangeXmit

function transmits an appropriate soup change notification

message after writing the entry back to its soup; in this case, the notification
specifies that the

'|MyApp:MySig|

application made an

'entryChanged

change to the soup. (All entries store a reference to the soup in which they reside,
which is how the

EntryChangeXmit

method determines which soup changed.)