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

C H A P T E R 1 1
Data Storage and Retrieval
Using Newton Data Storage Objects 11-63
In contrast, the EntryUndoChanges function clears the entry cache without writing
the cached entry to the soup. This function makes references to the entry point to
the original, unmodified entry residing in the soup, instead of the cached entry.
Note that reading, printing, or modifying any slot in the entry after calling
EntryFlushXmit , EntryUndoChanges , or AddFlushedXmit causes the
entire entry to be read back into the NewtonScript heap; thus, use these functions
only when you’re sure you won’t need to access the entry in the near future.
If you do need to work with the entry data after you’ve written it to the soup, you’ll
want to use functions and methods that don’t clear the entry cache after writing the
soup entry. The
AddToDefaultStoreXmit and AddToStoreXmit union soup
methods save frames as soup entries without clearing the entry cache afterward.
When adding frames to single soups, you can use the
AddXmit soup method for
the same purpose. The EntryChangeXmit function also writes the cached entry
back to its soup without flushing the cache afterward. Contrast this function with
the
EntryFlushXmit function, which clears the entry cache after writing the
cached entry back to its soup. Table 11-1 summarizes the caching behavior of all
methods that write entries to soups or union soups.
Using Soup Change Notification 11
When your application changes an entry in a shared soup, the system executes
callback functions registered by applications using that soup, allowing them to take
action in response to the change. The system-supplied soup change notification
service allows applications to
■ notify each other when they make changes to soup entries
■ respond to notifications precisely
Table 11-1 Effect of functions and methods on entry cache
Function or method Cached entry
uSoup :AddToDefaultStoreXmit( frame, changeSym ) Creates and returns
uSoup :AddToStoreXmit( frame, changeSym ) Creates and returns
soup :AddXmit( frame, changeSym ) Creates and returns
soup :AddFlushedXmit( frame, changeSym ) Does not create or return
EntryFlushXmit( entry ) Returns existing
EntryChangeXmit( entry ) Returns existing
EntryUndoChanges( entry ) Throws away existing