Apple Newton Programmer’s Newton 2.0 (for Newton 2.0) User Manual

Page 494

C H A P T E R 1 1

Data Storage and Retrieval

11-62

Using Newton Data Storage Objects

Note

The

EntryCopyXmit

method copies the cached entry—not the

original soup entry—into the destination soup.

◆

Sharing Entry Data

Shared soups and shared entries need to be in a well-documented format to allow
other applications to use them. For an example of how to document the structure of
your soup entries, refer to Chapter 19, “Built-in Applications and System Data.”
There you will see descriptions of the soups used by the built-in applications on
Newton devices produced by Apple Computer, Inc.

Using the Entry Cache Efficiently

Whenever you access a slot in a soup entry, the system reads the entire entry into
the NewtonScript heap if it is not already present. That is, simply testing or
printing the value of a single slot causes the entire soup entry in which it resides to
be read into the entry cache. For best performance, avoid creating cached entries
when you don’t need them, and flush the entry cache as soon as is appropriate. This
section describes how you can avoid unnecessary caching and how you can reclaim
cache memory explicitly. Table 11-1 on page 11-63 summarizes the use of the
entry cache by the functions and methods described in this discussion.

Reading a soup entry into memory requires more heap space than testing tag or
index values does. Whenever possible, work with index keys and tags rather than
the contents of soup entries. Some suggested techniques for doing so include
the following:

■

Avoid using

validTest

functions in favor of using

indexValidTest

functions in your queries, as the latter can be performed without reading soup
entries into memory.

■

Query on index key values or tag values rather than on values that require
reading soup entries into the NewtonScript heap.

■

Use the cursor method

EntryKey

to retrieve an entry’s key value without

reading the entry into the NewtonScript heap.

Normally, adding or changing a soup entry creates a cached entry. If you do not
plan on working further with an entry’s data after you’ve added or modified it, you
can reclaim heap space by releasing the memory used by the entry cache. You can
use the

AddFlushedXmit

soup method to add a soup entry without creating a

cached entry at all; in addition to saving heap space, this method saves you the time
normally required to create the cached entry. When working with a cached entry,
you can use the

EntryFlushXmit

function to write it back to its soup and clear

the entry cache.