`
`
`
`PalmDatabase
`
`
`Programming
`
`
`
`The Complete
`Developer’s
`Guide
`
`Eric Giguére
`
`be
`
`Microsoft Corp. Exhibit 1059
`
`
`
`Palm™ Database Programming:
`The Complete
`Developer's Guide
`
`Eric Giguere
`
`Wiley Computer Publishing
`
`John Wiley & Sons, Inc.
`NEW YORK + CHICHESTER + WEINHEIM * BRISBANE « SINGAPORE + TORONTO
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`To my wife, Lisa, who has shown me other ways to synchronize
`
`Publisher: Robert Ipsen
`Editor: Carol Long
`Managing Editor: Angela Murphy
`Electronic Products, Associate Editor: Mike Sosa
`Text Design & Composition: North Market Street Graphics
`
`Designations used by companies to distinguish their products are often claimed as
`trademarks. In all instances where John Wiley & Sons,Inc., is aware of a claim, the
`product names appearin initial capital or ALL CAPITAL LETTERS. Readers, however,
`should contact the appropriate companies for more complete information regarding
`trademarks andregistration.
`
`This bookis printed on acid-free paper.
`
`Copyright © 1999 by Eric Giguere. All rights reserved.
`
`Published by John Wiley & Sons, Inc.
`
`Published simultaneously in Canada.
`
`Nopart of this publication may be reproduced,stored in a retrieval system or
`transmitted in any form or by any means,electronic, mechanical, photocopying,
`recording, scanning or otherwise, except as permitted under Sections 107 or 108 of
`the 1976 United States Copyright Act, without either the prior written permission of the
`Publisher, or authorization through paymentof the appropriate per-copy fee to the
`Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400,
`fax (978) 750-4744. Requests to the Publisher for permission should be addressedto the
`Permissions Department, John Wiley & Sons, Inc., 605 Third Avenue, New York, NY
`10158-0012, (212) 850-6011, fax (212) 850-6008, E-Mail: PERMREQ @ WILEY.COM.
`
`This publication is designed to provide accurate and authoritative information in regard
`to the subject matter covered. It is sold with the understanding that the publisheris not
`engaged in professional services. If professional advice or other expert assistanceis
`required, the services of a competent professional person should be sought.
`
`Library of Congress Cataloging-in-Publication Data:
`Giguere, Eric.
`Palm database programming: the complete developer's guide /
`Eric Giguere.
`p.
`cm.
`ISBN 0-471-35401-5 (pbk.)
`1. Database design.
`2. PalmOS.
`QA76.9.D26G52
`1999
`005.74—de21
`
`I. Title.
`
`99-36711
`CIP
`
`Printed in the United States of America.
`
`100987654321
`
`yid
`=
`
`
`
`Pach:New.|S
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`(OS
`ay
`What You Needto Knowa
`
`= Sleep mode occurs when there has been no user activity on the
`device for a certain numberof minutes. The default is two minutes,
`but you can change the wait period to one or three minutes using the
`Preferences application. Sleep mode is also entered when you turn
`off the device using the power button. In sleep mode, the processor,
`screen, and most of the other hardware do not receive any power, but
`the memory chips, the real-time clock, and some low-level circuitry
`do stay powered. Pressing a button restores powerto the processor
`and the other hardware. Thereal-time clock can also wake the device
`at a predeterminedtime.
`
`= Doze mode(sometimes referred to as idle mode) occurs when an
`application is waiting for user input. The processoris halted until a
`hardwareinterrupt signals user activity, such as the press of a button
`or a stroke of the pen. Most of an application’s time when the device
`is on is spent in doze mode.
`
`= Running modeoccurs when the processoris executing instructions.
`This mode consumesthe most power, so the device returns to doze
`mode as soonas possible in order to conserve battery power.
`
`As you cansee, the poweris neverreally turned off unless you pull out
`the batteries and let the internal capacitors (which keep the device
`charged while you change batteries) discharge completely. The active
`application is simply in a halted state when in sleep mode, ready to
`resume whereit left off as soon as poweris reapplied to the processor.
`
`Operating Systemeee
`The Palm operating system (Palm OS) provides the environment for
`your applications to run in and consists of two parts, the kernel and the
`managers.
`
`The Kernel
`
`The kernel is the core of Palm operating system (Palm OS). It provides
`the interface between the hardware (such as trapping interrupts when
`the user strokes the screen with the pen) and the rest of the operating
`system and also manages multiple threads of execution. The kernel in
`current use is licensed from Kadak Products Ltd. (www. kadak.com).
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`16 eehs PROGRAMMING
`
`Although Palm OSusesseveral threads internally, applications cannot
`create or use any threads otherthan the one they’re running on. You can
`only write single-threaded applications, which meansthat you'll have
`to perform long operations in small chunks to avoid the appearance of
`hanging the device. We discuss this further in Chapter 4 when wedeal
`with event processing.
`Although applications are single-threaded and only one application ever
`appearsactive to the user, a second copy of the active application some-
`times runs on another thread but in a more limited environment. Thisis
`also covered in Chapter 4 when wediscuss application launching.
`
`The Managers
`Apart from the kernel, Palm OS consists of a series of managers, which
`are collections of APIs grouped by function. Your applications use the
`managers to obtain system resources and interact with the user. The
`managers can be groupedas follows:
`= The UI managers handle all interaction with the user. This includes
`general functions for drawing on the screen as well as functions
`related to specific user interface elements such as fields andlists.
`m The system managers handle non-UI interaction with the device,
`including accessto the timers and the system event queue.
`= The memory managers handle memory allocation and management
`of Palm OS databases and resources, discussedlater in this chapter.
`= The communication managers handle communications between the
`Palm device and the external world, using the serial port or the
`infrared port.
`Wediscuss most of the managers as we explore Palm programming.
`
`Palm OS Versions
`
`As the Palm devices have evolved, Palm Computing has released new
`versionsof the operating system. Palm OS3.2 is the most recent version
`of the operating system at the time this book was written andis available
`on the Palm VII. The Palm IIx and Palm V run Palm OS 3.1, while the
`Palm Il runs Palm OS 3.0. The original Pilot 1000 and Pilot 5000
`machines run Palm OS 1.0. The PalmPilot Personal and PalmPilot Pro-
`fessional models run Palm OS 2.0. All Palm modelsprior to the Palm III
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`ya
`
`
`PALM DATABASE PROGRAMMING
`
`<Ul/Chars.h>. Modifiers are bitmasks defined in <UI/Event.h>, such as
`shiftKeyMask or autoRepeatKeyMask. One modifier of particular inter-
`est is commandKeyMask, whichindicates that the virtual keyis actually
`a command. For example, if the commandKeyMaskflag is set and the
`virtual key is backlightChr, it’s the commandto toggle the state of the
`backlight. Your application can intercept commands and substitute its
`ownactions. For example, a space game might choose to remap the four
`hardware buttons to control the player’s spaceship; it would do so by
`handling the hard1Chr, hard2Chr, hard3Chr, and hard4Chr virtual keys
`before the system had a chanceto see them.
`
`Performing Long Operations
`As with any event-driven application on other platforms,it’s important
`to process events on a regular and timely basis in order to keep the appli-
`cation responsive. An often-used rule of thumbis to always respond to
`user input within a tenth of a second. Any longer and the user gets impa-
`tient. (On the Palm Computing platform there is no hourglass cursor to
`indicate that the application is busy, so responsiveness is even more
`important than on a desktop platform.)
`
`On other platforms you can offload long operations onto a separate
`thread, but Palm applications are single-threaded. To perform long oper-
`ations and stay responsive you can use one of two techniques. Thefirst
`technique is to check the event queueat regular intervals and process any
`waiting events. For example, consider the following program skeleton:
`// Start the normal event
`loop
`
`ProcessEvents( evtWaitForever, false );
`
`// Perform a long operation
`
`Boolean DoLongOperation ()
`{
`
`){
`i <= 40000; ++i
`for( int i = 1;
`// Do something time-consuming here.
`// Then every once in a while check the event queue.
`
`){
`if( (i % 100) == 90)
`Boolean quit = ProcessEvents( 0,
`if( quit
`){
`// application is quitting, stop
`
`true );
`
`
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`aha Ed 103
`
`return false;
`
`return true;
`
`// Revised event
`
`loop
`
`
`Boolean ProcessEvents( int timeout, Boolean stopOnNilEvent
`{
`
`)
`
`EventType event;
`
`while( true ){
`EvtGetEvent( &event,
`
`timeout );
`
`switch( event.eType ){
`case nilEvent:
`
`if( stopOnNilEvent
`return false;
`
`) {
`
`} b
`
`reak;
`case appStopEvent:
`return true;
`case .... // process other events
`
`In this example the event loop has been revised to allow the caller to
`specify the timeout value and whether to stop when a nilEventis read. A
`timeoutvalue of 0 causes EvtGetEventto return immediately if there are
`no events to process, returning a nilEvent.
`The second techniqueis to split a long operation into several steps, each
`of whichis triggered by an event. Your application can define its own
`event identifiers greater than or equal to firstUserEvent. To start the
`operation you add a user-defined event to the event queuethat triggers
`the first step. Each step then adds another eventto trigger the next step.
`The skeleton code for such a sequence might be as follows:
`// Define the “user events” for this application
`
`enum userEvents {
`
`firstStep = firstUserEvent,
`secondStep,
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`YM PALM DATABASE PROGRAMMING
`
`thirdsStep
`
`// The event
`
`loop
`
`EventType event;
`
`do {
`
`EytGetEvent( &event, evtWaitForever );
`
`switch( event.eType ){
`case firstStep:
`DoFirstStep();
`break;
`case secondstep:
`DoSecondStep();
`break;
`case thirdStep:
`DoThirdSstep ();
`break;
`case .... // other events
`
`}
`} while( event.eType != appStopEvent );
`
`// until told to stop
`
`// At some point you start the operation
`
`AddUserEvent( firstStep );
`
`// Define a function to queue the user events
`
`void AddUserEvent ( userEvents eventID )
`‘i
`
`EventType userEvent;
`
`userEvent.eType = eventID;
`
`EvtaAddEventToQueue( &userEvent de
`
`// The first step
`
`void DoFirstStep()
`{
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`Ores omereenty 105
`
`// Qo the first step...
`// at the end, post
`the event that starts tne next one....
`
`AddUserEvent ( secondStep );
`
`/ The second step
`
`} /
`
`void DoSecondStep ()
`{
`
`// do the second step...
`// at the end, post the event that starts the next one...
`
`AddUserEvent(
`
`thirdStep );
`
`oid DoThirdStep()
`
`// do the third step...
`
`} v
`
`{
`
`}
`
`Which approachto take dependsonthe nature of the operation. Thefirst
`techniqueis best suited for operations that are hard to split into discrete
`steps, but watch out for recursive calls that start two or more long oper-
`ations. The event loop will require special coding to cancel the operation
`or quit the application entirely. The second technique fits best with the
`event-driven paradigm becausethere’s a single event loop, but it requires
`workin splitting the operation into steps and passing data between the
`different steps. On the other hand, at the start of each step it’s easy to
`update the user about the state of the operation.
`
`An Application Skeleton
`eee
`
`Before proceeding any further,let’s take a look at a simple application,
`AppSkeleton, which you'll find on the CD-ROM accompanying this book.
`AppSkeleton is the most basic well-behaved application you can write
`and includes the following features:
`
`m= A PilotMain that understands normal launches and includes the struc-
`ture to support other launches.
`= Resourcesthat define a main form (the initial screen), an about form
`(to display information about the application), an alert (a dialog) for
`ROMversiontesting, a menubar, and the application icon.
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`
`
`Wireless Communication Systems/Palm Programming
`All the tools and information you'll need to write effective
`applications for Palm devices
`Palm’ Database Programming
`
`$49.99 USA/$77.50 CAN
`
`The demand for developers who can
`build applications for the Palm OS”
`platform has never been greater.
`Now,with this “how-to” guide, you'll
`gain the necessary skills to program
`these new devices. Written by a soft-
`ware engineer specializing in Palm
`OS development, this book covers
`everything from the basics of Palm
`devices and writing applications to
`database synchronization and build-
`ing database-centric applications.
`You'll be able to apply the informa-
`tion presented to create database
`applications, graphical user inter-
`faces, and more.
`
`With the help of numerous examples
`and sample programsintegrated
`throughout this book, you will:
`
`
`
`
`
`Learn the key features of the Palm
`operating system
`
`Master the development tools needed
`to build, run, and debug applications
`
`Write interactive database programs
`for the Palm platform
`
`Explore the code behind the Palm
`user interface
`
`Learn about Palm databases, rela-
`tional databases, and database
`synchronization
`
`Create Palm applications that syn-
`chronize with external databases
`™
`Build applications using Sybase™ Ultra-
`Lite and Oracle® Lite Consolidator
`
`The CD-ROM provides you with:
`
`All the examples discussedin the text
`
`Useful software that guides you
`through the developmentprocess,
`including a copy of CodeWarrior® Lite
`
`An evaluation version of Sybase’s
`Adaptive Server Anywhererelational
`database, including the UltraLite
`deployment technology
`
`Comprehensive reference material on
`Palm OS
`
`ERIC GIGUEREis a software engi-
`neer in the Mobile and Embedded
`Computing Division of Sybase,
`Inc. Previously, he was a lead
`developer on PowerJ, Sybase’s
`Java development tool, where he
`was responsible for the Power]
`class library and database connec-
`tivity. He has written extensively
`for various magazines, including
`Dr. Dobb’s Journal, Software
`Development, Computer Language,
`Byte, and Compute. He also
`wrote the Programmer's Guide to
`ARexx for CommodoreElectronics.
`Heholds bachelor’s and master’s
`degrees in computer science from
`the University of Waterloo, Ontario.
`
`The companion Website at
`www.ericgiguere.com/palm features:
`
`¢ Updates on the Palm Computing®
`platform
`
`* Additional information not cov-
`ered in the book
`
`e Links to other important Palm
`Computing Web sites
`
`Complete working code for current
`database technologies
`
`
`o
`VIACTm aTICMEArlscCC
`Visit our Web site at www.wiley.com/compbooks/
`
`JOHN WILEY & SONS, INC.
`New York » Chichester * Weinheim
`Brisbane * Singapore * Toronto
`
`TUT
`Warehouse - BKI57@634>
`Palm Database Programming:
`The Comp!
`oo
`Used, Very Good
`g:
`Ine Complete Developer's Guide
`(uve)
`§
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`