1-by-1 black pixel for creating lines
1-by-1 black pixel for creating lines
EricGiguere.com > Books > Palm Database Programming > Chapter 2
Printer-friendly version Set your preferences
Read my blogs on AdSense and affiliate marketing
Learn about these ads

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 | Contents


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.


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 Palm devices.

Table 2.1 Palm Device RAM Sizes



Pilot 1000


Pilot 5000


PalmPilot Personal


PalmPilot Professional and IBM WorkPad


Palm III


Palm IIIx


Palm V


Palm VII


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 following:

  • 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 example.

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 );
    return 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 heap.

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 uniqueness.

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 resource databases.

Prev Chapter | Prev Section | Next Section | Next Chapter | Contents

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 copyright and disclaimer notices for more details.

If you find the material useful, consider buying one of my books, linking to this site from your own site or in your weblog, or sending me a note.

Google Web www.ericgiguere.com   
1-by-1 black pixel for creating lines
Copyright ©2003-2012 Eric Giguere | Send mail about this page | About this site | Privacy policy
Site design and programming by Eric Giguere | Hosting by KGB Internet Solutions
This site is Java-powered
Other sites: The Unofficial AdSense Blog | Google Suggest Explorer | Invisible Fence Guide | Synclastic
This page was last modified on November 17, 2003
1-by-1 black pixel for creating lines
1-by-1 black pixel for creating lines