@wm
`
`\‘
`
`m
`Palm Datalgase
`Programming
`
`The Complete
`Developer’s
`Guide
`
`Eric Giguére
`
`Microsoft Corp. Exhibit 1059
`
`

`

`PalmTM Database Programming:
`The Complete
`Developer's Guide
`
`Eric Giguére
`
`Wlley Computer Publishing
`
`John Wiley 8: Sons, Inc.
`new you . cmcmasnan - WEINHEIM - RISBANE - SINGAPORE - ronomo
`
`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 appear in initial capital or ALL CAPITAL LETTERS. Readers, however,
`should contact the appropriate companies for more complete information regarding
`trademarks and registration.
`
`This book is printed on acid—free paper.
`
`Copyright © 1999 by Eric Giguere. All rights reserved.
`
`Published by John Wiley & Sons, Inc.
`
`Published simultaneously in Canada.
`
`No part of this publication may be reproduced, stored in a retrieval system or
`transmitted in any form or by any means, electronic, mechanical, photocopying,
`recording, seaming 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 payment of 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 addressed to 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 publisher is not
`engaged in professional services. If professional advice or other expert assistance is
`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.
`
`ISBN0471—35401-5(pbk.)
`
`1. Database design.
`QA76.9.D26G52
`1999
`005.74—dc21
`
`2. Palm OS.
`
`Printed in the United States of America.
`
`10987654321
`
`I. Title.
`
`99-36711
`CIP
`
`“E?
`4fl\a
`\.
`
`% g
`fibva
`
`g
`,
`
`,
`
`-
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`

`

`Is
`“
`_i_.
`man You mane.
`
`- Sleep mode occurs when there has been no user activity on the
`device for a certain number of 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 power to the processor
`and the other hardware. The real—time clock can also wake the device
`at a predetermined time.
`
`- Doze mode (sometimes referred to as idle mode) occurs when an
`application is waiting for user input. The processor is halted until a
`hardware interrupt 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.
`
`I Running mode occurs when the processor is executing instructions.
`This mode consumes the most power, so the device returns to doze
`mode as soon as possible in order to conserve battery power.
`
`As you can see, the power is never really 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 where it left off as soon as power is reapplied to the processor.
`
`Operating Systema
`
`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
`
`PAlM DATABASE PRGRAMMING
`
`Although Palm OS uses several threads internally, applications cannot
`create or use any threads other than the one they’re running on. You can
`only write single-threaded applications, which means that 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 we deal
`with event processing.
`
`Although applications are single-threaded and only one application ever
`appears active to the user, a second copy of the active application some-
`times runs on another thread but in a more limited environment. This is
`also covered in Chapter 4 when we discuss 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 grouped as 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 and lists.
`
`- The system managers handle non—UI interaction with the device,
`including access to the timers and the system event queue.
`
`- The memory managers handle memory allocation and management
`of Palm OS databases and resources, discussed later in this chapter.
`
`I The communication managers handle communications between the
`Palm device and the external world, using the serial port or the
`
`infrared port.
`
`We discuss most of the managers as we explore Palm programming.
`
`Palm OS Versions
`
`As the Palm devices have evolved, Palm Computing has released new
`versions of the operating system. Palm OS 3.2 is the most recent version
`of the operating system at the time this book was written and is available
`on the Palm VII. The Palm IIIX and Palm V run Palm OS 3.1, while the
`Palm 111 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 models prior to the Palm 111
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`

`

`
`
`102 Mm harmless Manama-me
`
`<UI/Chars.h>. Modifiers are bitmasks defined in <UI/Event.h>, such as
`shiftKeyMask or autoRepeatKeyMask. One modifier of particular inter-
`est is commandKeyMask, which indicates that the virtual key is actually
`a command. For example, if the commandKeyMask flag is set and the
`Virtual key is backlightChr, it’s the command to toggle the state of the
`backlight. Your application can intercept commands and substitute its
`own actions. 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 hardlChr, hardZChr, hardBChr, and hard4Chr Virtual keys
`before the system had a chance to 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 thumb is 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. The first
`technique is to check the event queue at regular intervals and process any
`waiting events. For example, consider the following program skeleton:
`// Start the normal event
`loop
`
`ProcessEvents( thWaitForever, false );
`
`// Perform a long operation
`
`Boolean DoLongOperation()
`{
`
`){
`i <= 40000; ++i
`for( int i = l;
`// Do something time—consuming here.
`// Then every once in a while check the event queue.
`
`)(
`)
`% 100 ) :: O
`i
`if( (
`Boolean quit : ProcessEvents( 0,
`if( quit
`){
`// application is quitting, stop
`
`true );
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`

`

`1
`
`Writing Palm Aplications
`
`, 103 _
`
`return false;
`
`return true;
`
`// Revised event
`
`loop
`
`
`Boolean ProcessEvents( int timeout, Boolean stopOnNilEvent
`{
`
`)
`
`EventType event;
`
`while( true ){
`EthetEvent( &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 nilEvent is read. A
`timeout value of 0 causes EthetEvent to return immediately if there are
`no events to process, returning a nilEvent.
`
`The second technique is to split a long operation into several steps, each
`of which is 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 queue that triggers
`the first step. Each step then adds another event to 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
`
`

`

`104'
`
`PALM DATABASE PROGRAMMING
`
`thirdStep
`
`// The event
`
`loop
`
`EVentType event;
`
`do {
`
`EthetEvent( &event, ethaitForever );
`
`switch( event.eType ){
`Case firstStep:
`DoFirstStep();
`break;
`case secondStep:
`DoSecondStep();
`break;
`case thirdStep:
`DoThirdStep();
`break;
`case .... // other events
`
`}
`} while( event.eType != appStopEvenL );
`
`// 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 )
`{
`
`EventType userEVent;
`
`userEvent.e”ype : eventID;
`
`EvtAddEvent”oQueue( &userEvent );
`
`// The first step
`
`void DoFirstStep()
`{
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`

`

`Writing Palm Applications
`
`«W‘IOS
`
`// do the first step...
`// at the end, post
`the event that starts the next one....
`
`AddUserEvent( secondStep );
`
`/ The second step
`
`> /
`
`void DoSecondStep()
`{
`
`// do the second step...
`// at the end, post the event that starts tne next one...
`
`AddUserEvent(
`
`thirdStep );
`
`oid DoThirdStep()
`
`// do the third step...
`
`} v
`
`{
`
`}
`
`Which approach to take depends on the nature of the operation. The first
`technique is 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 because there’s a single event loop, but it requires
`work in 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 Skeletona
`
`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:
`
`- A PilotMain that understands normal launches and includes the struc—
`ture to support other launches.
`
`- Resources that define a main form (the initial screen), an about form
`(to display information about the application), an alert (a dialog) for
`ROM version testing, a menubar, and the application icon.
`
`Microsoft Corp. Exhibit 1059
`
`Microsoft Corp. Exhibit 1059
`
`

`

`Wireless Communication Systems/ Palm Programming
`
`$49.99 USA/$11.50 CAN
`
`All the tools and information you’ll need to write effective
`
`applications for Palm devices
`Palm” Database Programming
`
`The demand for developers who can
`
`build applications for the Palm 05“
`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 specialiling in Palm
`05 development, this book covers
`everything from the basics of Palm
`devices and writing applications to
`database synchronilation 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 programs integrated
`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
`in
`Build applications using Sybase Ultra—
`Lite and Oracle‘“ Lite Consolidator
`
`The CD-ROM provides you with:
`
`All the examples discussed in the text
`
`Useful software that guides you
`through the development process,
`including a copy of CodeWarrior® Lite
`
`An evaluation version of Sybase’s
`Adaptive Server Anywhere relational
`database, including the UltraLite
`deployment technology
`
`Comprehensive reference material on
`Palm OS
`
`Complete working code for current
`database technologies
`
`ERIC GIGU‘ERE is 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 PowerJ
`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 Commodore Electronics.
`He holds bachelor’s and master’s
`
`degrees in computer science from
`the University of Waterloo, Ontario.
`
`The companion Web site at
`www.ericgiguere.com/palm features:
`
`' Updates on the Palm Computing"B7
`platform
`
`I Additional information not cov—
`ered in the book
`
`- Links to other important Palm
`Computing Web sites
`
`
`0
`Wiley Computer Publishing Timely. Practical. Reliable.
`Visit our Web site at www.wiley.com/compbooks/
`
`M
`
`arehouse — BK 1 5786342
`,
`.
`Palm Database Pm rammin :Th 9
`r
`Used, Very Gogod
`g
`e
`flmp'em Dale'flners Gurde
`(uVG) _s
`rm
`Microsoft Corp. Exhibit 1039
`
`JOHN WILEY & SONS, INC.
`New York - Chichester - Weinheim
`Brisbane - Singapore ‘ Toronto
`
`Microsoft Corp. Exhibit 1059
`
`