Data Storage and Retrieval

Using Newton Data Storage Objects

When the frame is constructed from the entry, it is cached in memory. At this point,
you can add, modify, and delete slots just as you would in any other frame;
however, the changes do not persist until the

EntryChangeXmit

function is

called for that particular entry. The

EntryChangeXmit

function writes the cached

entry frame back to the soup, replacing the original entry with the changed one.

If the

EntryUndoChangesXmit

function is called, the changes are thrown out

and the entry is restored to its original state. This function disposes of the cached
entry frame and restores the reference to the original uncached entry, just as if the
original entry was never referenced. Note that you can use the

FrameDirty

function to determine whether a cached entry has been modified since it was read
into the NewtonScript heap; however, this function does not detect changes to
individual characters in a string (a common operation for

clParagraphView

views). For more information, see "FrameDirty" (page 9-69) in Newton
Programmer's Reference.

The following code example gets an entry from the

namesUSoup

union soup,

changes it, and writes the changed entry back to the soup:

local namesUSoup := GetUnionSoupAlways(ROM_CardFileSoupName);
local namesCursor := namesUSoup:Query(nil);
local theEntry := namesCursor:Entry();
if theEntry then

begin

theEntry.cardType := 4;
EntryChangeXmit(theEntry, '|MyApp:MySig|);

end;

It's not always easy to determine the best time to write a cached entry back to its
soup. For example, it would be inappropriate to call a function like

EntryChangeXmit

from the

ViewChangedScript

method of a

protoLabelInputLine

view. When the user enters data on the input line with

the keyboard, the

ViewChangedScript

is called after every key press. Calling

the

EntryChangeXmit

function for every key press would be noticeably slow.

In some situations, the appropriate time to call

EntryChangeXmit

is more

obvious. For example, a natural time to call

EntryChangeXmit

would be when

the user dismisses an input slip.

Moving Entries

11

You can use the

MoveTarget

method of the root view to move (not copy) an

entry into the same-named soup on another store. For example, you would use
this method to move entries from one union soup member to another. For more
information, see "System-Supplied Filing Methods" (page 12-11) in Newton
Programmer's Reference.