A Palm is such a neat portable device. You take notes on it, plan meetings or even write down anniversaries. It's a nice tool to have while on the road. Our intranet server, on the other hand, is also a great resource. We have our company's planning and agenda on it, and it has all those interesting notes, addresses and, in our case, a complete knowledge database. This server runs (of course) Linux, an Apache web server and MySQL database on top of it, glued together with a proprietary application engine.

Wouldn't it be great if the two environments could be synchronized? Of course! Now if we could only access the internal databases from the Palm on our Linux server, that would get us pointed toward the right direction. Documentation is sparse and the Internet is big. But then along came Kevin and Jeffrey, two students who, with some effort, put together a solution that allowed us to make changes on the Palm or on the corporate intranet server and have these modifications propagated to one another's counterpart databases.

All code below was tested on an Intel machine running a Red Hat 6.x release and a Palm Vx with serial cradle running Palm OS 3.5, but other combinations shouldn't cause any problems. The libraries used are unchanged since the first Palm appeared on the market, when they were still being produced by 3Com. I suppose (but haven't tested it) that Visor's won't cause any problem either, as they are running the same OS.

Let's start with the simple part: connecting the Palm to the server. First, we need to connect the cradle of the Palm with the serial port of the server. Then we create a device called pilot. This pilot is nothing more than a link to a serial port (in our case /dev/ttyS0):

ln /dev/ttyS0 /dev/pilot

Now, we're ready to open the connection to the Palm using a C program and a simple push on the HotSync button of the cradle. Once the connection is made, we can relax and read records from the Palm's databases.

Communicating and opening the connection to the Palm is easy with the pi library. This library simulates the BSD socket interface: create a socket, bind it to our device, listen for an incoming connection and accept it. The incoming connection is initiated by the Palm/cradle combination when a user hits the sync button on the cradle. Making a dæmon that waits for someone to come by and synchronize its Palm is illustrated in Listing 1. Loop this program forever.

Listing 1. Synchronizing the Palm

Once the connection is open, how do we interact with the Palm databases? Each database on the Palm has a name. We can open a database by name and get a specific record or cycle through the database. On a Macintosh or Windows platform these functions are performed by conduits. Palm itself provides a conduit on these platforms for every standard database included with the Palm OS bundle. The Palm database manager provides ways for us to cycle only through the modified records in a database. Modified since when? Well, since the last synchronization, the last time a server committed this database. So, we should do this in our programs when finished with the synchronization process. The lines in Listing 2 should be executed when the connection is open.

Listing 2. Cycling through Modified Records

Reading records from a Palm database doesn't qualify as synchronizing. We'll need to do more, such as write to the Palm, delete from it and read from our MySQL database. Since connecting to a MySQL database is outside the scope of this article, we won't discuss the further details of the synchronization problem (and the possible conflicts). However, Kevin Velghe has written an excellent document about it. You can read it at www.duo.be/palm/mysql_palm.html.

Records stored in a Palm database have unique numbers. Whenever you write a record to the device, it returns this number. You should store it on your desktop or central database, so that you can delete or update a specific record.

The dlp_WriteRecord accepts a Palm ID. If it is zero, the Palm OS will allocate a new one for you; if you pass an existing ID, the corresponding record will be updated. For most standard databases a pack function packs the structured record into a buffer. This process is shown in Listing 3.

Listing 3. Pack Function

If, as in our case, you're serving multiple Palms on one server/cradle, you'll need to find out whose Palm is in the cradle. Once the connection is open, call the ReadUserInfo function:

{
  int db, len, I, attr;
  recordid_t id;
  struct PilotUser U;

...open the connection...

  sd = pi_accept(sd, 0, 0);
  dlp_ReadUserInfo(sd,&U);
  printf("Palm of: %s", U.username);
  pi_close(sd);
}

The Palm database manager does not delete records automatically when the records are read. It marks them for deletion and even has the ability to mark them for archiving on the desktop or server counterpart. When reading a modified record one should check the attribute flag to see if this record needs to be deleted (or archived). It will be deleted permanently on the Palm once the database is cleaned up:

{
  ...
  for (;;) {
    len = dlp_ReadNextModifiedRec(sd, db,
                       buffer, &id, &I,
                       0, &attr, 0);
    if (len < 0) break;
    if ((attr & dlpRecAttrDeleted) ||
        (attr & dlpRecAttrArchived))
      printf("Marked for deletion: %ld", id);
  }
}

A good practice after synchronizing a Palm is to leave some comment about it in the Palm's log. You can write whatever you want, the time and date are added anyway. So, add the following code to the end of your programs:

{
  ...
  dlp_ResetSyncFlags(sd, db);
  dlp_CleanUpDatabase(sd, db);
  dlp_CloseDB(sd, db);
  dlp_AddSyncLogEntry(sd,
    "Read modifications from Pilot.\n");
  pi_close(sd);
}

To use your Pilot with a Linux box, get the pilot-link package. The interfaces exist for many platforms, from Next, BSD, Solaris, OS/2 to Linux. They let you write programs in many languages from Python, Java, Perl, Tcl to C++ and C. The FTP site ryeham.ee.ryerson.ca/pub/PalmOS has the file you need: pilot-link.0.9.3.tar.gz.

It compiles on a Linux box without trouble. It is really more than just an interface library containing a bunch of simple tools that illustrate its use. These simple tools are very useful, enough to back up a Pilot (and restore it), move data to and from it, send e-mail, install programs and databases and so on. The library is callable from C, C++, Perl, Python, Tcl and maybe a few other languages; if you happen to have any programming ability, you can craft tools to do anything you want, using the provided ones and the sample code in this article as examples.

New programs, extra documentation, remarks or HOWTOs may be submitted to palm@duo.be. We'll put them on the server available for the public at www.duo.be/palm.

Let's install the package by executing

tar -xvzf pilot-link.0.9.3.tar.gz

This will create a directory (pilot-link.0.9.3) containing the sources. Change your working directory to the source (pilot-link.0.9.3) directory.

Run ./configure. This will search through your system for information needed to compile the software. Configure will set things up to be installed in /usr/local by default. If you want to change it, run ./configure --prefix=DIR, where DIR is replaced with the name of the directory to which the software will be installed.

Run make. This will compile the software. The software will not be installed until later, so that you have a chance to try it out first. If you are replacing an older version with a newer release, you may wish to check to make sure that no functionality you need has been broken. Generally, this is not a problem.

As the root user, run make install. This will copy the software into directories under /usr/local (or wherever you specified with the --prefix option). If you cannot log in as root, you can install the software to some directory where you have write access.

Don't forget to add any new directories of executables to your search path. Check out all the neat tools installed together with the libraries. For a description of some of them, take a look at the article mentioned in Resources.

Resources