======================================================================
This is the README file for the contents of the samplecode directory:
======================================================================

Introduction: 

This sample-code is provided in addition to the written documentation to make 
it easier for you get the hang of the usage of the SyncBuilder framework. 
Most of the software is actually useful utility programs. Enjoy!


======================================================================
General usage information
======================================================================
The programs use a smart way to retrieve all the parameters they need.
First of all, you can specify parameters on the command-line. Parameters
need to begin with either "--" or "-", followed by enough letters of
the parameter name, followed by either a space or a "=", followed by the
parameter value. Thus, for a parameter called "port", all of the following
would be valid (plus many more combinations):
--port COM2
-p=/dev/pilot
-port /dev/pilot
--po=/dev/ttyS1

After the program has started, two different things may happen. If you
have specified the "gui" parameter, then a simple GUI will ask you for
the parameter values. It will fill in as many blanks as it can from
values you already specified on the command-line, and from defaults.
Press the OK button when you are done.

If you have not specified the "gui" parameter, then the program will ask
you the missing parameter values on the console. It will automatically
start running once you have specified all the required parameters.


======================================================================
Common program options
======================================================================
All of the programs accept the following parameters:
--help      Print complete usage information, then exit
--gui       Display a GUI
--port      The port (see explanation below)
--jhotsync  Use Brad Barclay's JHotSync protocol stack. This option
            enables serial synchronization over JavaSoft's CommAPI
			on a properly configured Windows (95/98/NT) or Solaris machine.
			(this is highly experimental and is known to fail under
			Linux)

The port specifies how the Palm device is connected to your machine. 
You may use the following ports:

/dev/ttyS0, /dev/ttyS1, ...: The serial ports on a Unix box.

/dev/pilot : If you have done sth. like "ln -s /dev/ttyS1 /dev/pilot" you can
             then specify /dev/pilot as the port. This can be really helpful
             if you can never remember which port is your mouse and which one
             is your cradle ;-)

COM1, COM2 : The serial ports on a Windows box. 

.          : A single dot specifies that you wish to synchronize through 
             TCP/IP. This requires you to establish a working PPP connection
             between your Palm device and the host. Read the document
             "palmos_networking.html" in the
             docs/website directory to find out how to do that.


======================================================================
Program descriptions
======================================================================

-----------------------------------------------------------------------
DeviceInfo:
-----------------------------------------------------------------------

Purpose:

Display all the information that can be found out about the Palm device
and its user.

Usage:

Just run it. 

What can be learned:

o The most simple way to open a connection to the Palm device
o How to retrieve information about the Palm device.


-----------------------------------------------------------------------
TimeSync:
-----------------------------------------------------------------------

Purpose:

Set the time on the Palm device to that on the host. 

Usage:

Just run it. This is one of the few sample programs that will actually 
CHANGE data on your Palm device!

What can be learned:

o The most simple way to open a connection to the Palm device
o How to set the time on the Palm device


-----------------------------------------------------------------------
DatabaseInfo:
-----------------------------------------------------------------------

Purpose:

Either print a list of all databases on the device, or print more specific
information about a single database.

Usage:

Just run it. 

What can be learned:

o The most simple way to open a connection to the Palm device
o How to retrieve information about databases.


-----------------------------------------------------------------------
DatabaseXFer:
-----------------------------------------------------------------------

Purpose:

Installs a PRC or PDB file onto the Palm device. The file may come from
any source, including a web server.

Usage:

Just run it. The name of the file may either be specified without a prefix,
if the file is located on the local file-system, or with the prefix "http://"
if the file is located on a web server.

CAUTION: This program will overwrite existing databases on your Palm device
without a warning. It is therefore NOT a smart idea to install files such as
DatebookDB.pdb to your device!!!


What can be learned:

o The most simple way to open a connection to the Palm device
o How to read and install PRC/PDB database files.


-----------------------------------------------------------------------
DBFetch:
-----------------------------------------------------------------------

Purpose:

Reads a database from the Palm device and stores it in a file in the 
popular PRC/PDB format.

Usage:

Just run it. This program is harmless, since it only reads from the
device. Try out database names like "DatebookDB", or "ToDoDB". You can
also run the DatabaseInfo program to find out the names of all the
databases on your device.

What can be learned:

o The most simple way to open a connection to the Palm device
o How to write PRC/PDB database files.


-----------------------------------------------------------------------
MemoWeb:
-----------------------------------------------------------------------

Purpose:

Reads the file MemoDB.pdb from the file system or a web server and turns it
into an HTML page.

Usage:

In order to run this program you need a file called "MemoDB.pdb" which you
can obtain either through the DBFetch program, or through the pilot-xfer
utility from the pilot-link package.
The filename can be either specified directly, or with the http:// prefix.
If you specify the http:// prefix, the file will be fetched from a web server.

What can be learned:

o How to read PRC/PDB database files.
o How to manipulate databases in memory, using the MemoryDatabase class.
o How to turn Record contents into HTML code.


-----------------------------------------------------------------------
dlptest:
-----------------------------------------------------------------------

Purpose:

Exercise a wide variety of functionality on the Palm device. This one
is for demonstration and testing purposes.
This is one of the few sample programs that will actually CHANGE data on 
your Palm device! It will add two entries to your Datebook application, 
which can easily be deleted afterwards (they are located at the current
date and read "Dinner at the Red House", and "Dinner at the White House").

Usage:

Run the program. Press <RETURN> whenever you are asked to do so. Do not wait 
too long to press <RETURN>, because this will lead to time-outs if you are 
synchronizing through a serial cable.

What can be learned:

o The most simple way to open a connection to the Palm device
o How to do many different things on the Palm device
o How to overwrite existing Records on the Palm device


-----------------------------------------------------------------------
SyncServerTest:
-----------------------------------------------------------------------

Purpose:

This is a minimal framework that shows how to synchronize many Palm devices
simultaneously. It will simply display the User Info from each device that 
connects to the server (it will read and display the info 10 times in order
to give you more time to trigger the HotSync on another device at the same
time).

Usage:

Just run the program. It will always use the TCP/IP port, because multiple
simultaneous connections are not supported through any other port.

What can be learned:

o A more sophisticated way to connect Palm devices to the host
o Usage of the SyncServer class, for automatic connection management
o Usage of the SyncHandler class, for reusable synchronization logic



-----------------------------------------------------------------------
LoggingSyncServerTest:
-----------------------------------------------------------------------

For instructions look at SyncServerTest. This example adds an event-based
logging facility to SyncServerTest.

What can be learned:

o A more sophisticated way to connect Palm devices to the host
o Usage of the SyncServer class, for automatic connection management
o Usage of the SyncHandler class, for reusable synchronization logic
o Usage of the ServiceStateListener class, for monitoring the SyncServer.




======================================================================
Outdated software:
======================================================================

You should not design your software after these examples :-)  They are 
outdated, and will be brought to a modernized state at a later time.

-----------------------------------------------------------------------
addresssucker.java, datesucker.java, mailsucker.java, memosucker.java,
todosucker.java:
-----------------------------------------------------------------------

Purpose:

These applications download the data from the built-in applications on the
Palm device and write them to a file as serialized Java objects. 
The file with the Java objects can be used to run the DejaGnu test-suite in 
the testsuite directory.

What can be learned:

o The most simple way to open a connection to the Palm device
o How to open databases and how to read data from them


-----------------------------------------------------------------------
*.disabled:
-----------------------------------------------------------------------
These applications are not meant for the general public. You should only
change their file-extension to .java and compile them if you have been
instructed to do so. If you do not know what you are doing they may
result in corrupt data on the Palm device!!!



=======================================================================
$Id: README,v 1.6 1999/02/21 13:21:25 christ Exp $
=======================================================================


