Blocks and Records

Since the handheld treats most parts of a database as chunks of raw data, Pyrite uses a common API to allow applications to access database contents. There are five basic block types, each represented by a class:

Each of these classes inherits from a common parent called Block. The Block family of classes provide the basic interface which all Pyrite applications use to access Palm Computing platform data.

The Block class and its children are not intended to be used alone; they are meant to be subclassed, in order to provide a more friendly interface to their contents. Subclasses of the Block family can define named fields. When the block is read from its database, it is unpacked into a friendly, Python-accessible form; when it is written back to the database, its contents are first transformed into the representation used on the handheld.

Using Blocks

Using a Block object (or, more precisely, an application specific subclass of Block) is almost exactly like using a dictionary, keyed by field name. Unlike a regular dictionary, a Block can only contain a limited set of key/value pairs, and each value must usually be of a specific type. The set of allowable keys, and the value types which accompany them, are defined by the subclass.

Important: Giving a field a value of the wrong type is likely to result in an exception when the block is packed. This means that the exception, if any, will be thrown when storing the block in a database, not when the value is set.

Block objects have get, keys, values, items, and has_key methods, which work the same as they do on ordinary dictionaries.

Every Block has an attribute called raw, which contains the packed representation of its contents. You should never set this field directly; instead, call the Block's unpack method with the string of raw data you wish to place in the Block. If you have made changes to the contents of the Block's fields, you should call its pack method before examining the raw attribute.

Records

Records in a database contain an extra longword of header information, to specify the category and attributes of the record. Record objects have several extra attributes which contain this information:

id (integer)

The unique ID of the record, generated when it is first created on the handheld. The unique ID is used during synchronization to associate a record on the handheld with a corresponding record on the desktop. The unique ID is a three-byte integer; if you do not supply one (leaving it equal to 0), one will be created when the record is transferred to the handheld.

Note: When writing to a local file in the prc/pdb format, you must provide unique IDs or else the Palm Desktop will refuse to install it. The Pyrite and pilot-link installers, however, don't care, and will allow the palmtop to generate IDs as the database is installed.

category (integer)

The category of the record, a small integer from 0 ("Unfiled") to 15. All records have a category; if the standard Category Manager isn't used by the application, this attribute will probably be zero, or might even be used for something else.

deleted (boolean)

If true, the record has been deleted by the handheld user. When the user deletes a record, a placeholder is left in memory until the next sync, so that the desktop can delete the corresponding record in its database. If the user selected the "Archive on PC" option when deleting the record, the entire record remains in the database (with this bit set) until the next sync.

modified (boolean)

If true, the record has been modified since the last sync. (In handheld programs, this bit is called "dirty".) The Database interface offers a way to locate only the modified records in a database; during synchronization, this can be used to avoid examining records that need not be synchronized.

Important: If the handheld is synchronized to more than one desktop database, the modified bits may not accurately show which records need to be examined during a synchronization session.

secret (boolean)

If true, the user has marked this record as private.

busy (boolean)

If true, the record is currently in use.

archived (boolean)

If true, this record has been archived. (This attribute does not actually correspond to anything on the handheld; it is provided for use during synchronization.)

index (integer)

The index at which the record is positioned in the database. (Changing it doesn't change the position of the record, however.)

Resources

Pyrite treats resource databases almost identically to ordinary databases. The primary difference is that when your application retrieves a resource, Pyrite returns a Resource object, rather than a Record. Resource objects have the following attributes:

type (string [4 characters])

The resource type.

id (integer)

The resource id.

Palm Computing platform applications are actually just resource databases which follow a few conventions about type and id assignments. Program code resides in resources of type 'CODE', and the definitions of user interface elements are in resources with types like 'MENU', 'FORM', and so on. Because the contents of these resources are in standard formats, it is likely that future versions of Pyrite will include appropriate Resource subclasses, allowing easy examination and modification of the user interface portions of handheld applications.

Appinfo and Sortinfo

Each database has room for a single appinfo block and a single sortinfo block. These are represented by AppBlock and SortBlock objects, respectively. Because appinfo and sortinfo blocks are entirely application-specific, the AppBlock and SortBlock classes have no additional behavior or contents beyond those of the standard Block class.