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

C H A P T E R 1 1
Data Storage and Retrieval
11-10 About Data Storage on Newton Devices
data from a different locale. To take advantage of this behavior, the application
must create an internationalized index for the soup and the query must request the
alternate sorting behavior explicitly in its query spec. For more information, see
“Internationalized Sorting Order for Text Queries” on page 11-45.
Saving User Preference Data in the System Soup 11
Most of the time you’ll want to store data in union soups, but one task for which
union soups are not suitable is the storage of your application’s user preferences
data. There are several good reasons for always saving user preferences data on the
internal store:
■ If your application is on a card that is moved from one Newton device to another,
it acts the way the users of the respective Newton devices think it should.
■ It rarely makes sense to distribute preferences data among several storage cards.
■ It’s difficult to guarantee that your application will always have access to any
particular card.
■ If your application is on the internal store and it simply adds preference data to
the default store, the preference data could be saved on an external store that
becomes unavailable to the application when a card is ejected.
Hence, the built-in ROM_SystemSoupName soup on the internal store is usually
the ideal place to keep your application’s preference data. The GetAppPrefs
function allows you to get and set your application’s preferences frame in this
soup. For more information, see the description of this function in Chapter 26,
“Utility Functions.” For more information about the
ROM_SystemSoupName soup
itself, see Chapter 19, “Built-in Applications and System Data.”
Queries 11
To retrieve entries from a soup or union soup, you perform a query by sending the
Query message to the soup or union soup. The Query method accepts as its
argument a frame known as a query specification or query spec. The query spec
defines criteria for the inclusion of entries in the query result. You can think of the
query spec as a filter that the
Query method uses to select a subset of the soup’s
data. Queries can test index key values or string values and perform customized
tests that you define.
A single query spec can specify multiple criteria that entries must meet in order to
be included in the result of the query. For example, you can specify that your query
return all entries created after a certain date that are tagged
'business but do not
contain the "paid" string. For instructional purposes, this chapter discusses
separately each test that a query spec may include.