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

Page 462

C H A P T E R 1 1

Data Storage and Retrieval

11-30

Using Newton Data Storage Objects

Referencing Stores

The

GetStores

global function returns an array of references to all currently

available stores. You can send the messages described in this section to any of the
store objects in this array.

local allStores := GetStores();

▲

W A R N I N G

Do not modify the array that the

GetStores

function returns.

▲

You can reference individual stores in the array by appending an array index value
to the

GetStores

call, as in the following code example:

local internalStore := GetStores()[0];

The first element of the array returned by the

GetStores

function is always the

internal store; however, the ordering of subsequent elements in this array cannot be
relied upon, as it may vary on different Newton devices.

IMPORTANT

Don’t call the

GetStores

function from your application’s

RemoveScript

method, or you may find yourself looking at the

“Newton needs the card…” slip. You can avoid this situation by
using the

IsValid

store method to test the validity of a store

object before sending messages to it.

▲

Retrieving Packages From Stores

The

GetPackages

global function returns an array of packages currently available

to the system; this array contains packages that reside on any currently available store.

To determine the store on which a specified package resides, test the value of the

store

slot in the package reference information frame associated with the

package. This frame is returned by the

GetPkgRefInfo

function.

To load a package procedurally, use either of the store methods

SuckPackageFromBinary

SuckPackageFromEndpoint

. For more

information, see the descriptions of these methods in “Data Storage and Retrieval
Reference” (page 9-1) in Newton Programmer’s Reference.

Testing Stores for Write-Protection

The store methods

CheckWriteProtect

and

IsReadOnly

determine whether a

store is write-protected. The former throws an exception when it is passed a
reference to a write-protected store, while the latter simply returns the value

nil