
                      PCompress by Britt Yenne

IF NOTHING ELSE, PLEASE READ SECTION II WHICH CONTAINS SPECIAL BETA-TEST
INSTRUCTIONS, INCLUDING HOW TO TEST THE COMPRESSION LIBRARIES ON YOUR
PILOT BEFORE RUNNING PCOMPRESS FOR REAL.


Table of Contents:

I.   Introduction -- What Is PCompress?
II.  Special Beta-Test Instructions
III. Interface / Options
IV.  What Algorithm Do You Use?
V.   Who do I thank/blame/contact for all this?
VI.  License / Source Code


I. ----- Introduction -- What Is PCompress? -----

PCompress is a utility which allows you to save memory by compressing
applications or databases which you don't use very often but don't want
to delete.  In compressed form, databases take up less memory.  However,
they must be uncompressed before they can be used again.

There are two important things to understand about PCompress.  First,
in order to compress a database, you must have about as much free
memory as the size of the database you're compressing.  It does sound
strange that you need extra memory in order to compress things to
free up memory, but PCompress (for safety) will not delete any parts
of a database until it is successfully compressed.  Hence, the
database and its compressed image must fit into memory at the same
time.

Second, there are two normal ways for an application to store data
on your Palm Pilot.  The primary way is to write out its records to
a database -- these are the application databases that PCompress can
compress.  The second way is to store small pieces of information
into the system preferences.  PCompress will NOT make a copy of these
system preferences when it compresses an application or its databases.
Therefore, be very careful when using the system "delete" function to
delete applications you have compressed with PCompress -- the system
"delete" function will remove the preferences settings, and PCompress
will not restore those when you uncompress the application.  PCompress's
Database View screen allows you to delete individual applications or
databases without deleting their preferences.

As a feature, PCompress allows you to compress a database several
times and keep more than one compressed version of that database.
This could be a reasonable way to keep a revision history of a
database.  When you have multiple compressed versions of a database,
you can tell them apart by comparing their creation dates as displayed
on the Database View screen (see below).

II. ----- Special Beta-Test Instructions -----

This beta-test version comes with a self-test option which I highly
recommend you run before turning PCompress loose on your precious
databases.  The self-test will randomly generate some databases and
then compress, uncompress, and verify their data.  The test will run
for 10 iterations or until you hit the 'cancel' button.  It prints a
loop counter at the top of the screen, indicating the number of
iterations performed so far.

The self tests are random, but may require as much as 200k of free
memory to run properly.

The cancel button can be a little hard to hit while the Pilot is busy
running the tests, so I suggest you hold your stylus to the button
until it responds.

The tests are different each time they're run, so feel free to set them
off as often as you like.  Don't bill me for the batteries, though.  :-)

If a test fails, it will print a fail message and a failure code at
the bottom left of the screen.  If it reports that there is not
enough memory, then you did not have enough free memory to run the
tests.  You could try again -- the tests are random and may not
require a lot of memory the next time they run.  If any other error
code is reported, please write down the failure code and the seed
value which is printed on the top line of the screen.  My email
address is below.

To run the self tests, go to the main PCompress screen and hit the
menu button.  A menu option named "Automated Test" should appear,
and you can select that option to start the tests.

III. ----- Interface / Options -----

The main screen shows the databases in your Palm Pilot along with
their sizes and the state of their backup bits.  Normal databases
are shown in the standard font, and compressed databases are shown in
the bold font.  You may use the category selector (in the upper
right-hand corner) to limit the view to only compressed or uncompressed
databases, and you can click the 'apps only' checkbox at the bottom of
the screen to limit the view to applications.  Tap the 'Reload' button
to refresh the view.

Tap on a database name to bring up the Database View screen.
This screen shows detailed database information and any available
compression options.

Tap on a backup bit checkbox to change the backup bit for that
database.  A database's backup bit determines whether that database
will be copied to your PC during Hotsync.  PCompress allows you to
change these bits in the hope that you'll Hotsync databases before
compressing them, just to make sure you don't lose your data due to
some obscure bug.  Please, please Hotsync your databases -- I can't
stress this enough.  If you use a tool like Backup Buddy then it
will take care of this for you.

The Database View shows detailed information about a database, including
its type, creator, and size.  If the database is compressed, then both
the compressed and uncompressed sizes are shown.  If the database is
an application, then the total size of its databases (if any) is also
shown.

To compress a database, select the desired compression level and tap
the 'compress' button.  Higher compression levels produce better results
but require more time.  The difference between compression levels
varies by the type of the database being compressed, but level 2 is
normally good for general use.

To uncompress a database, tap the 'uncompress' button.

Select 'delete after compress/uncompress' to automatically delete the
original database(s) after a successful compress/uncompress.  Select
'compress/uncompress all data' to also compress/uncompress all databases
owned by the application -- this is a convenient way to compress or
uncompress an application and all of its data.

IV. ----- What Algorithm Do You Use? -----

PCompress's compression algorithm is a variant of the one used by gzip.
The main modifications are to support a tighter memory space and a very
slow processor.  The goal is still to match occurrences of repeating
strings (LZ77) and then Huffman-encode the result.

The Huffman is dynamic but not adaptive.  This means that the algorithm
must make two passes, one to generate LZ77 output and calculate the
histogram, and a second to actually encode the LZ77 output.  Why not
use adaptive Huffman?  Well, even if we could overcome the tremendously
higher processor requirement, we also have a memory constraint.

PalmOS gives applications a total of around 36k of dynamic memory which
can be used for stack space, global variables, and allocated structures.
This is barely enough space to maintain workable string and hash tables.
All other memory is write-protected and requires special system calls
to modify.

For detailed questions, I'll refer you to the source code at this
point.  :-)  I've tried to keep the comments nice and descriptive, and
the compression library parts will compile and run on Linux.  If you
have any questions, please feel free to email me at the address below.

V. ----- Who do I thank/blame/contact for all this? -----

My name is Britt Yenne, and I work for a consulting firm named The
Kernel Group (TKG) in Austin, Texas.  TKG tends to focus more on AIX
and system management solutions than the Palm Pilot (darn it), so
consequently this project has been on my own time.

As of this writing, my e-mail address is "yenne@tkg.com".  Please feel
free to send me questions, comments, complaints, etc.  I'm setting up
a web page for my favorite Palm Pilot links and resources, as well as
any current contact information:

  http://www.jump.net/~syenne/pilot

If you prefer, you may send a letter to:

  Britt Yenne
  3008 Pioneer Way
  Round Rock, TX  78664

If you also have a real job and need system management solutions (Tivoli,
AIX, SP2, custom solutions) please check out my company's web site,
because that's what we do:

  http://www.tkg.com

VI. ----- License / Source Code -----

The PCompress program (ie. not the dynamic library portion) is
released under the GNU General Public License:

  This program is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 2
  of the License, or (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

The PCompress library will be released under the GNU Library General
Public License after beta-testing is complete.  This library will allow
all software authors, including commercial and shareware authors, to
use compression in their programs.  I'll write more on this when the
beta period is over.

A web link to the full text of the license, source code, and other
documentation about this software may be found at:

  http://www.jump.net/~syenne/pilot
