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

C H A P T E R 1 1
Data Storage and Retrieval
About Data Storage on Newton Devices 11-23
Null Union Soups 11
Under unusual circumstances a 1. x application may encounter a union soup that
doesn’t contain any member soups. A soup in this state is referred to as a null
union soup. Queries on a null union soup fail. Attempts to add entries to a missing
member soup also fail if a soup definition for that soup has not been registered.
Null union soups should not normally occur with 1.
x applications and cannot occur
with applications that use the 2.0 union soup interface correctly.
Null union soups are most often found in the aftermath of a debugging session—
for example, if in the NTK Inspector you have deleted various soups (to test the
cases in which your application needs to create its own soups) and neglected to
restore things to their normal state.
Null union soups can also occur as a result of the application soup not being
created properly. Normally, when a card is ejected, the internal store member of a
union soup is left behind or a soup definition for creating that soup is available.
When this is not the case, the union soup reference to the internal store member is
null when the card is ejected. If you follow the guidelines outlined in “Registering
and Unregistering Soup Definitions” on page 11-33 this problem does not occur.
Null union soups can also occur when another application deletes one or more
soups that your application uses. Any application that deletes soups should at least
transmit a soup change notification, thereby allowing your application to deal with
the change appropriately.
When your application is running on a 1. x unit or when no soup definition exists
for a union soup, it is appropriate to test for a constituent soup’s validity before
trying to add an entry to it. Simply loop through the array of stores returned by the
GetStores function, sending the IsValid message to each of the constituent
soups in the union.
Query Compatibility Information 11
Version 2.0 of Newton system software provides a more powerful query mechanism
while at the same time simplifying the syntax of queries. Although old-style query
syntax is still supported, you’ll probably want to revise your application code to
take advantage of the features new-style queries provide. The following list
summarizes changes to queries. The remainder of this section explores query
compatibility issues in more detail.
Query ( soupOrUSoup , querySpec ) // use soupOrUSoup :Query( querySpec ) instead
querySpec := {type : symbol , // obsolete, do not use
startKey: keyValue , // use beginKey or beginExclKey
endTest: keyValue , // endKey or endExclKey instead
… }