Palm Database Programming The Electronic Version
Chapter 2: What You Need To Know About Palm Devices
This material was published in 1999. See the free
Palm OS Programming
online course I developed for
CodeWarriorU for some updated material.
Prev Chapter |
Prev Section |
Next Section |
Next Chapter |
Unlike desktop computers, which can use virtual memory
(memory that is swapped to and from a hard disk as needed) to increase
the amount of memory available to an application, the memory chips
that come with the Palm device are all you have to work with. Memory
is a precious commodity on the Palm platform.
ROM and RAM
Palm devices come with varying amounts of memory, both read-only
(ROM) and read-write (RAM). ROM memory is used to store the operating
system, the built-in applications (such as the Address Book), and some
default data for those applications. Newer models such as the Palm III
use flash memory instead of ROM so that the operating system can be
upgraded without replacing the memory chips.
RAM memory is where everything else is stored — the
applications you've installed on the device, the data for those
applications, user settings, and various system data areas. The
original Palm devices came with very little memory, as low as 512K of
ROM and 128K of RAM, but the Palm III comes with 2MB of RAM, a
significant increase. Table 2.1 lists the RAM sizes in the various
Table 2.1 Palm Device RAM Sizes
PalmPilot Professional and IBM WorkPad
Remember that unlike a desktop computer, the Palm device is never
actually turned off — when you press the power button the
device merely goes into sleep mode. Anything placed in RAM stays there
until explicitly erased.
Cards and Heaps
ROM and RAM are packaged together on what is known as a memory card.
Palm devices can support multiple cards, but so far only one card is
installed in each device. The memory card number (starting at 0) is a
required parameter in some system calls, but until more memory cards
are added to the device you can safely pass 0 in all cases.
The memory on a card is divided into heaps. ROM is
considered a single heap. RAM consists of at least two heaps, the
first of which is referred to as the dynamic heap, while the
rest are called storage heaps.
The dynamic heap is used both by the operating system and by
applications. Among other things, the dynamic heap stores the
- Operating system data, including the system trap dispatch table,
user interface structures, and various buffers
- The application stack, where local variables and function return
addresses are stored
- The application global and static variables, referred to as the
global data block
- Dynamically allocated memory used by an application
The size of the dynamic heap can be quite small. On Palm OS 1.0
devices it's only 32K. On Palm OS 2.0 devices it's either 32K
(PalmPilot Personal) or 64K (PalmPilot Professional), but if TCP/IP is
available (only on the Professional) it uses 32K of the memory. So,
effectively there is only 32K of memory available in the dynamic heap
for Palm OS 1.0 and 2.0. In Palm OS 3.0, the dynamic heap size is 96K,
but again TCP/IP requires 32K of this, leaving 64K for general use.
There are two important differences between the dynamic heap and
the storage heaps. First, the contents of the dynamic heap are always
cleared when the device is reset. The dynamic heap is not meant for
use as long-term storage. The contents of the storage heaps are
preserved, except in the most extreme cases, such as when the
batteries are removed from the device for more than a minute or when a
hard reset (explained subsequently) is performed. Second, the storage
heaps are write-protected (in fact, all writing has to be done via
system functions) to prevent an application from writing over another
application's permanent storage, while the contents of the dynamic
heap are not write-protected, making it possible for badly behaved
applications to crash the device.
In Palm OS 1.0 and 2.0 there are multiple storage heaps, each no
more than 64K in size. Thus, the maximum size of memory that can be
allocated as a single chunk from any heap in the system is just under
64K. Palm OS 3.0 consolidates all the storage heaps into a single
storage heap but keeps the allocation limit. The limit may be removed
in a future version of the operating system.
Handles and Local IDs
Because physical memory is limited, heap fragmentation is to be
avoided whenever possible. Fragmentation occurs when there are chunks
of allocated memory spread throughout the heap, interspersed between
the blocks of free memory. If two blocks of free memory are adjacent,
for example, the Memory Manager can merge them into a single contiguous
chunk. The larger a block of free memory is, the greater the
likelihood that a request for memory will succeed.
In an ideal world all the allocated memory would sit at one end of
the heap and the free memory at the other end, but real applications
rarely behave this way. One way to avoid heap fragmentation is to
relocate the allocated chunks so that more of the free chunks can be
combined into larger blocks. The Memory Manager needs to know which
blocks can be moved and which must stay fixed in place, otherwise the
application will crash if one of the blocks it was using is suddenly
shifted to another location. This is done by using memory handles.
A handle uniquely identifies a moveable block of memory.
Conceptually, you can think of it as a pointer to a fixed memory block
which itself holds a pointer to the moveable block. When the Memory
Manager needs to move a block, it adjusts the pointer inside the
handle — all references to the handle itself remain valid
because the handle is fixed. At any point an application can use the
handle to lock the moveable block. Locking a handle in Palm OS
fixes the moveable block in memory to prevent the Memory Manager from
moving it. The application then obtains a pointer to the newly fixed
block. When the application is finished with the block, it unlocks
the handle, making the block moveable again.
Applications can also allocate nonmoveable memory blocks, but their
use is discouraged. They're best used for temporary memory allocations
and should be freed as soon as possible.
Whether fixed or moveable, a block of memory can also be accessed
by its local ID. The local ID is an offset relative to the
start of the memory card. Palm OS provides APIs to convert handles and
pointers to local IDs and vice versa. Local IDs are used mostly with
certain system functions, in particular the Data Manager functions.
Future Palm devices may allow the user to add and remove memory
cards — using local IDs allows the base address of a card
to change without affecting the data it holds.
Allocating from the Dynamic Heap
Palm OS provides functions analogous to the C runtime library's
malloc, realloc, and free functions for allocating fixed memory blocks
from the dynamic heap:
VoidPtr MemPtrNew( ULong size );
Err MemPtrResize( VoidPtr ptr, ULong newSize );
Err MemPtrFree( VoidPtr ptr );
All fixed-block memory allocation occurs with these functions: the
C++ new and delete operators call MemPtrNew and MemPtrFree, for
Moveable blocks in the dynamic heap are allocated using
MemHandleNew and deallocated using MemHandleFree:
VoidHand MemHandleNew( ULong size );
Err MemHandleFree( VoidHand handle );
Before using a handle, you must lock it to obtain a pointer to a
block of memory and unlock it when you're done:
VoidHand CopyStringIntoHandle( Char *string )
VoidHand handle = MemHandleNew( StrLen( string ) );
Char *dst = (Char *) MemHandleLock( handle );
StrCopy( dst, string );
MemHandleUnlock( handle );
You can also unlock a moveable block using the locked pointer
because Palm OS can determine the handle that corresponds to a given
pointer. The Palm OS Memory Manager also provides a number of
functions for mapping handles to local IDs and back, resizing handles,
and other miscellaneous operations.
Databases and the Storage Heap
Memory in the storage heap (or heaps) is accessed using the Data
Manager API (application programming interface), which provides
higher-level abstractions built on top of the Memory Manager that are
useful when dealing with permanent storage. From the Data Manager's
point of view, the storage heap is divided into databases. In
Palm terminology, a database is just a collection of memory
blocks allocated from the storage heap. We discuss Palm databases in
detail in Chapter 5, so in this section we limit the discussion to a
few basic facts. Note that most of the Memory Manager APIs can be used
with blocks of memory from the storage heap as well as the dynamic
There are two kinds of Palm OS databases: record and resource. A record
database stores records, which are blocks of memory of
arbitrary size (they don't have to be of equal size) that hold
user-defined data. Records can be accessed by linear index, by a
unique identifier, or by an application-defined key. The records in a
database can also be sorted. A resource database has less
overhead than a record database because it just stores a set of resources,
which are memory blocks grouped by type and unique identifier only. No
sorting is possible, and searching for a particular resource requires
a linear search. The maximum size of any record or resource in a
database is just under 64K.
All databases have a name, a type, and a creator ID. The name of
the database must be unique and must be less than 32 characters long.
The type is a four-byte value that identifies the kind of data in the
database. By convention, the type value is represented using a
four-character ASCII string, with each character in the string mapping
to one of the bytes. (For readability, only printable ASCII
characters, those in the range 32 to 127, are used.) The creator ID
is a four-byte value, also represented as a four-character string,
registered with Palm Computing that identifies the person or company
who created the database. It's used to link databases of different
types together with the application that created them. We'll talk more
about creator IDs when we discuss applications in Chapter 4. Because
registered creator IDs are unique, a common strategy to ensure that
the database name is also unique is to append the creator ID to the
name. For example, if you had a database that you wanted to call
"Memos" and a creator ID of "ERIC," using the name
"Memos-ERIC" or even "ERIC-Memos" should ensure
Resource databases are typically used by the system. For example,
your application is really just a resource database, with different
resources for the code, the initialization data for global and static
variables, and for the static user interface elements. When
programming, you'll be mostly dealing with record databases, not
Prev Chapter |
Prev Section |
Next Section |
Next Chapter |
Copyright ©1999 by Eric Giguere. All rights reserved.
From Palm Database Programming: The Complete Developer's Guide.
Reprinted here with permission from the publisher. Please see the
and disclaimer notices for more details.
If you find the material useful, consider buying one of
linking to this site from your own site or in your weblog,
or sending me a note.