Compiling Palm^TM Apps on Linux

Alex Lange

One of the latest waves in systems administration is to use handheld devices to administer systems remotely. As sys admins need to be everywhere at once, the convenience and ease of administering systems via a Palm^TM Pilot (as one example) is becoming more and more apparent. Small programs called Palm Query Applications (PQAs), can be the front-end to systems administration tools, making them accessible to sys admins on the go. However, building a PQA is problematic for the Linux or UNIX systems administrator because Palm's development tools for PQAs run exclusively on Microsoft Windows.

This article describes how to compile a simple PQA on Linux using the public domain LinPQA compiler. I'll run through a few definitions, discuss where to get LinPQA and how to use it, and then present an example of a PQA-accessed systems administration application -- a Web-based logfile viewer.

What is a PQA?

A PQA (Palm Query Application) is a small program downloaded to a Palm Pilot. PQAs usually act as the front-end to access a Web server-based program that does most of the real work. For example, an HTML form that accepts input and passes it to a server's CGI program would be implemented on the Palm as a PQA.

PQAs use "Web Clippings", which is Palm's implementation of a subset of HTML 3.2. For this reason, you may sometimes hear a PQA referred to as a WCA or "Web Clippings Application." (In fact, Palm's own freely available PQA compiler for Windows is called WCABUILD.) Compiling a PQA or WCA translates your HTML 3.2-compliant Web page into the presentation format needed for a Palm Pilot.

Getting the LinPQA Compiler

LinPQA is freeware written by Steven James (pyro@linuxlabs.com) and blessed by the GNU public license, version 2. LinPQA is available on the Web at:

http://www.linuxlabs.com/software/linpqa.html

LinPQA comes with two programs:

• PQAcompile for building PQAs
• PQAdecompile for reverse engineering HTML

I will examine only PQAcompile in this article.

Accommodating Lowercase Tags

Most HTML is a mixture of upper- and lowercase tags. Out of the box, however, LinPQA understands only uppercase tags. You have two options:

1. Edit your HTML to make sure all tags and attribute names are uppercase.

2. Edit the source program PQAcompile.c to have it accommodate lowercase tags.

If you decide to edit PQAcompile.c, here's a snippet of code you will need to alter:

if(!strcasecmp(tag,"H1")) { /* heading 1 */
                *(pos++) = 0x01;
                *(pos++) = 0x0a;

Compiling the Compiler

LinPQA comes with an executable ready for the i386 architecture. If you haven't modified the source code as described above, then you're good to go. If you have modified the source, however, then you'll need socket libraries and header files for Pilot-Link to compile LinPQA. Pilot-Link, which is a collection of public domain PalmOS link-loader utilities, is freely available from many sites, several of which are listed in the "Resources" section.

Once you have obtained Pilot-Link, you can build LinPQA by running "make" in the directory in which you unzipped LinPQA. The result is the executable PQAcompile.

Creating a PQA

A PQA is a quick and efficient way to create a Palm-based application that requests and receives data from a Web server. For example, imagine the situation where a roving systems administrator wishes to be able to view recent logfile entries from a palmtop computer.

The administrator configures the Apache server running on a Linux machine to write its logs to the commonly configured directory /var/log/httpd with a filename specifying the date. For simplicity, the administrator also configures Apache to write its errors to this same file. The filename format is as follows:

/var/log/httpd/httpd-YYYYmmdd.log

The first step is to create a CGI program on the Web server that receives the date as input and returns the last 25 lines of the logfile associated with that date. Listing 1 shows the CGI program displayLog.cgi. The program reads a date from the QUERY_STRING variable and then tails the last 25 lines of a logfile whose name matches that string.

The administrator then creates a simple input form that requests a date from the user and passes it to the program shown in Listing 1. Listing 2 shows the HTML file logView.html that passes input to displayLog.cgi.

Note the HEAD's META tag (on line 4) that defines the attribute palmcomputingplatform as true. On line 7, I have embedded an absolute URL in the FORM's ACTION tag, complete with server name and fully qualified domain name. This is done to allow our Palm Pilot's network gateway to find our server. Line 14's MAXLENGTH attribute is necessary to force the Palm Pilot to allow us to type characters into the Date field. Without MAXLENGTH, you won't be able to enter a date even though the input field is displayed!

Line 14 in Listing 2 prompts the user to enter a value for the Date field. If the form field Date is null, the date defaults to a formatted string from the date command that represents the current date stamp of the log file.

After you create the HTML form that passes input to the CGI program, you must compile the form into a PQA that will run on the Palm Pilot. The syntax of the PQAcompile command is:

PQAcompile appname version title inputfile

To compile the logView.html file shown in Listing 2 into a PQA, use the command:

PQAcompile logView 1.0 "Logfile Viewer" logView.html

Testing with a Palm Emulator

To use the logView PQA, you must hot sync it to the Palm Pilot, which is a familiar operation for anyone who owns a Palm Pilot. Hot sync'ing is the process of copying programs or data to the handheld device.

Hot sync'ing while you're developing your program, however, can be tedious, especially if you're making many changes that need to be checked and rechecked. You might consider downloading Palm's emulators to help yourself out. The emulator itself is free, but it requires "skins" or ROMs to download for which you must register as a Palm developer, which is also free.

Conclusion

The example PQA described in this article is a simple application designed to show you the basic steps for creating, compiling, and implementing a palm query application. If you were implementing an application of this sort on a real network, you would need to provide an appropriate level of security, such as protecting the displayLog.cgi program through basic authentication (username and password challenge). (If you're concerned about security, you should also be aware of the limitations on security for wireless devices. See the article titled "Wireless (In)Security" by Ido Dubrawsky in May 2002 Sys Admin.)

You may also see other ways of customizing and enhancing the functionality of the logView application described in this article. logView is intended as an example. With the LinPQA compiler, you can create your own Palm query applications to address similar needs on your own network.

Resources

Palm Emulators for UNIX and other OSs -- http://www.palmos.com/dev/tools/emulator

LinPQA Compiler -- http://www.linuxlabs.com/software/linpqa.html

Pilot-Link Libraries -- http://rpmfind.net/linux/RPM/engarde/contrib/RPMS/i386/pilot-link-0.9.5- 1.0.1.i386.html

Pilot-Link Development Kit (for header files)-- http://packages.debian.org/unstable/devel/libpisock-dev.html

Alex Lange has been a technical writer for 20 years, a system administrator for 15, and a Web developer for 10. You can reach him at: Alex@Lange.org.