Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) - Manual (Page 460)

C H A P T E R 1 1
Data Storage and Retrieval
11-28 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.)