List Documentation


Introduction

List is freeware, source is included. It has been over a year in the making. When I started working on this the ASDK had just been released, so the original list code was started in assembly. When GCC seemed to have hit a point of stability I moved over to using C -- its not better than assembly, just different.

What does list do? Its a simple database. Modeled after the address book, it should be intuitive to use, its supposed to look just like every other pilot application. If you just want to use list on your Pilot you can stop reading here, go use it. If there is something non-intuitive, email me and I'll address the problem.


The Pilot Application - list.prc

List works on both:
PalmOS 1.0 (the original) -- Pilot 1000, Pilot 5000
PalmOS 2.0 -- PalmPilot Personal, PalmPilot Professional
While not tested, I'm certain the PalmIII will also work fine.


[Customize Screen Shot] Install list.prc just like you would any other Pilot add-on. The first time you run list you will see the customization screen.

This screen is used to create a List database. You are required to fill in the database name, field 1 and field 2 names. The display order is configurable. The first two checkboxes are per database: Write Protect is used to prevent accidental editing; Backup next Hot-Sync is the backup bit status of this database.

The last two checkboxes are global flags for all List databases: Automate backup gives the List program control over the backup bit toggling, if you edit the database it is marked as needing a backup; Select database on launch changes the startup behaviour of list, List either opens the last database you were using, or presents a list of available databases (provided there is more than one) for you to select.

If you get stuck tapping the (i) will get you some help text.

Hint: I reverse the display order (field2,field1) for my book database. The view mode always shows field1 in larger text at the top, and feild2 in smaller text below. Having the book title in a larger font in the view mode looks cooler, and sorting by author makes more sense to me.



[Edit Screen Shot] Now we've created a new database, but there isn't anything in it yet. The main screen looks a lot like the built in addressbook application, to create a new record press the [New] button.

The edit screen has our two custom fields: Title and Author, and a note field. There is also a pop-down category selection in the upper right corner.

Seems very similar to the address book? Yes and no, the user interface was designed to look and feel just like one of the built in applications -- the code is original work, this is not a hacked up version of the address list.



[Main Screen Shot] The main view shows the name of the database in the usual application name area. The view is configurable based on category (just like the built-in applications). The hardware up/down buttons or the up/down arrows in the lower right corner scroll the list.

The [New] button begins editing a new entry. Selecting an entry from the list goes to view mode. The [Find] button starts a local find, it differs from a system find (the silk find button) in that it only searches the current List database. List will participate in system finds.

The funny looking icon on the botton of the screen appears when there is more than one List database. If you select this button (icon) you will be taken to the database selection screen.



[View Screen Shot] View mode indicates the record number and total number of records in the category (this is handy for figuring out how many records are in a the list database if the "All" category is selected).

As was mentioned before, the display order of this database is field2,field1 so that the author name is the sort key but the view mode shows the title in a larger font. This is strictly a personal preference.

If the database is not marked with the Write-Protect (see the customization screen), then a pen tap anywhere on the view screen will enter edit mode. Alternatively you can use the [Edit] button. This is the same behaviour as the address list built-in application.



The PC Application - listdb.exe

A Dos based application used to convert from .csv files to .pdb files. This is not a conduit, just a simple way to get data between Pilot and PC. The list pilot application marks the list databases with the backup bit such that when you hot-sync the list databases are copied down to your "Backup" directory.

CSV File Format

The syntax of the .csv file is specified over two parts, the first line, and the content. The first line must contain:

title,field1,field2,category1,category2,...,categoryN

where

  • Database title (31 characters), a comma,
  • Field1 name (15 characters), a comma,
  • Field2 name (15 characters), a comma,
  • Category1 name (15 characters), a comma,
  • [other category names comma separated]
  • line is ended with a return (enter key)
Example:
books,author,title,non-fiction,fiction

The second and all other lines in the file have the following format. Note that the categories entry in the content must correspond to one provided in the first line.

categoryX,field1,field2,Note
categoryY,field1,field2,Note
..etc..

where

  • Category name (must match one of the given names in the first line), a comma,
  • Field 1 data (64 characters), a comma,
  • Field 2 data (64 characters), a comma,
  • Note data (1024 characters)

Example:
fiction,William Gibson,Neuromancer,great book!
non-fiction,Judge Bork,The Anti-Trust Paradox,this thing stinks

Note, that Lists will sort according to the first name in this instance. If you wish to place the last name first and use a comma between them -- "Gibson, William" -- you must escape the comma with a "\" that precedes the comma.

Example:
fiction,Gibson\,William,Neuromancer,great book!

This causes the "\," sequence to be impossible to insert into a list database -- such is life.

The note field converts commas into CR's, so if you wanted a multi-line note field you would insert commas where you would like CR's.

Example:
fiction,William Gibson,Neuromancer,great book!,this is on a second line

Sample Input File

Cut between the ===cut=== marks and paste into a new text file, this simple example should help you get going.

===cut===
books,author,title,non-fiction,fiction
fiction,William Gibson,Neuromancer,great book!
non-fiction,Judge Bork,The Anti-Trust Paradox,this thing stinks
===cut===

Running listdb.exe

If you run listdb.exe with no arguments you will get a usage printout. There are two modes of use: creation, extraction. If you want to convert a .csv file into a .pdb file the command is:
listdb -c test.pdb test.csv
If you want to extract a .pdb file into a .csv file the command is:
listdb -x test.pdb test.csv

Hint: If you're having trouble with the .csv format, try taking a database from the pilot Backup directory and extracting the .csv file from the .pdb. This will give you a template to work from.


Notes:

Freeware: List is freeware, it may be distributed freely, but not sold or included in for-profit collections without written permission from the author. This page is the List home page, and will always have the most recent information.

Bugs: I'm not aware of any crash bugs, and will do my best to fix fatal errors like that ASAP. Anything that is simply nit-picky may fall to the bottom of the priority list very quickly. List is distributed with full source, and I encourage people to help me out by finding the actual bug in the code and sending me the fix. I'll happily apply any reasonable fix to the source, and credit you with the work done.

Backup: I was required to upgrade to HotSync 1.1 since I had more than 32 databases installed on my Pilot and HotSync 1.0 only checks the first 32 during a HotSync. I got my copy from: http://www.3com.com/palm/custsupp/upgrade.html


Credits:

I'd like to mention a few people without whom this would not have been possible.

  • Darrin Massena (darrin@massena.com) - His web site, the ASDK, and news.massena.com.
  • John J. Lehett (jlehett@iag.net) & the GCC crew (Jeff Dionne, Kresten Thorup, ..)
  • Wes Cherry (wesc@ricochet.net) - PilRC.
  • Ian Goldberg (iang@abraham.cs.berkeley.edu) - Callback workaround for GCC 0.5.0.
  • Bertand Simon (b.simon@iname.com) - That hint I needed for categories.
  • Alan Macy (AlanMacy@responsivesoftware.com) - How to set the backup bit on databases
  • Ken Shirriff (ken.shirriff@eng.sun.com) - PDB format in java source
  • Pat Beirne & The Pilot-UNIX group ( Pace Willisson, Kenneth Albanowski, Kevin L. Flynn, Brian J. Swetland, D. Jeff Dionne ) -- Pilot File Dumper (PDB format)
  • Raymond Lau -- Ray's PalmPilot Software Archive http://www.palmcentral.com
  • Matthew Rowntree (mattr@globalx.com) - Web page guru
  • Martin Mueller (mm@lunetix.de) - listdb.exe bugfix
  • Wayne Campbell (wacampbell@mmm.com) - find bug solution for PalmIII
  • Joseph Reagle Jr. (reagle@w3.org) - A better example for the listdb.exe doc
  • Palm/3com -- Gremlins in the PalmOS emulator
  • Christopher Antos (chrisant@premier1.net) -- (HandyShopper sources) how to update app info correctly