Data Storage and Retrieval

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.