Welcome to the Pilot Generic Conduit Manager

VERSION 11 NOTICE 
----------------
The DinkyVw and PMoneyView user-interface is crude, crude. This will improve
in the near future.

DO NOT DO A BOTHWAY SYNC OF PILOT MONEY! IT IS NOT SUPPORTED!

DO NOT INSTALL IF YOU ARE USING HOTSYNC 1.1


Features
--------

-provides data backup services for any Pilot app
	-fixes the data backup conduit problems of HotSync 1.0
	-easy selection of data-restore options
	-does backup and restore for any Pilot app, even without
		a corresponding PC app
	-multiple backup files created
	-actually speeds up the HotSync process
-preconfigered setups for conduits
	-DinkyPad
	-cbasPad
	-Pilot Money
-bundled with PC viewers for DinkyPad and cbasPad


Notice
------
THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS,
WITHOUT WARRANTY OF ANY KIND. THROUGH THE USE OF THIS SOFTWARE
YOU ACCEPT THE POSSIBLE LOSS OF DATA OR PRODUCTIVITY.



The Programs
------------
	GenCond.dll	is the heart of the Conduit Manager system
	CondMgr.exe	is a VB app to manage the installation and
			removal of GenCond conduits
	cbasView.exe	is a VB app to view, create or delete
			entries for the cbasPad application
	DinkyVw.exe	is a VB app to view, create, delete, import,
			export/save or print entries for the DinkyPad
			Pilot application
	DinkVwA.dll	support code for the above
	PMoneyView.exe	is a VB app to view Pilot Money data on your PC

The GenCond.dll requires MSVCRT40.DLL

The VB programs require VB40032.DLL. The DinkyVw.exe program requires
the GenCond.dll program, and there MUST be a copy of GenCond.dll in
the same directory as DinkyVw.exe.


Installation and Usage
----------------------

THIS VERSION IS FOR HOTSYNC 1.0 ONLY! DO NOT USE THIS VERSION
WITH HOTSYNC 1.1!

Simply extract all the files to a working directory. Run the
CondMgr.exe program, and select the first menu item. This 
	-modifieds the registry
	-copies GenCond.dll to the pilot directory

Install any of the pre-configured conduits, or install a custom.
On the next HotSync, your data transfers will occur.

The cbasView program usage is obvious. Just run it.

The DinkyVw program allows:
	auto-select of the current sync file; other files can be
		opened with the browse button
	save your work
	save a picture as a bitmap file
	copy to the clipboard
	paste from the clipboard
	crude drawing on screen
	print single file or the whole collection
	new and delete of individual pictures




How it Works
------------

The Pilot handheld computer is a wonderful device for personal productivity.
It includes the ability to send a copy of all it's information to and from
a PC or Macintosh.

The built-in applications have "twins" on the PC which allow you
to work equally well on either platform, and move the data back
and forth, in sync.

The third-part applications which have been built normally do not
have "twins" on the PC, but the forward thinking designers at Palm
put a mechanism in place to automatically backup the Pilot data.
Programs like Pilot Money can have all their data backed-up, just in
case the Pilot loses all its memory.

Unfortunately, there is a minor bug in the code (described in the 
previous paragraph) and only some of the Pilot data is sent
for backup.

The Generic Conduit Manager system fixes this problem in a round-about
way.

When the Generic Conduit Manager is installed, it links a "generic conduit"
in place, so that every hot-sync invokes the "generic conduit".
This code searches the Win95 registry for Conduit Manager entries
and uses the data from there to do a generic hot-sync with the Pilot.

Because only modified data is transferred, each database that you
couple through the Generic Conduit actually speeds up your hot-sync.
[See the note below concerning categories. Not all apps can be
both-way hot-sync'd.]

The synchronization strategy:

Record
	- unmodified
	D deleted
	M modified
	N new 
	x does not exist

Pilot/PC
--	do nothing
-M	PC->Pilot
M-	Pilot->PC 
xM	PC->Pilot
Mx	Pilot->PC 
MM	create duplicate on Pilot and PC, cross update 
-D	delete on Pilot 
D-	delete on PC 
MD	over-ride the delete, Pilot->PC 
DM	over-ride the delete, PC->Pilot 
DD	delete on both
xD	do nothing
Dx	do nothing


Categories

This version of the Conduit Manager/Generic Conduit does not
handle categories. I will put this in if there is a demand.

In other words, if your database uses categories, your database files
WILL BE CORRUPTED if you let GenCond.dll sync them. A full PC->Pilot
or Pilot->PC sync will work ok, but the both-way sync will not handle
the merging of categories properly. You have been warned.



The HotSync 1.0 Problem
-----------------------

As mentioned above, the Pilot HotSync 1.0 program is a well designed,
forward thinking system. It does a good job of backing up data for
programs which didn't even exist when it was written.

There is a minor bug, which goes as follows: During a hot-sync, the
code on the PC asks the Pilot to give it a list of all the data
groups contained within the Pilot. The PC code then runs through the
registry, and tries to match up each data group with an entry in the
registry. Naturally, it finds Address, Todo, Datebook and Memopad,
and signals each one to sync itself. Any other data type that has a
conduit is run, as well. Any data group which is left over (and
marked for backup) is blindly copied to the PC, for a future
"restore". (This includes the Grafitti shortcuts, the Giraffe high
scores, DinkyPad data, cbasPad data and PilotMoney data).

The bug is this: when the PC asks the Pilot for a list of its data
groups, only the first 28 are returned. (This list includes the
application code as well as the data.) If the user has a fully packed
Pilot, many data groups can get left out. Since they don't make it to
the PC, a) their conduit never gets called b) they never get backed
up.

The GenCond.DLL system fixes this problem by working differently.
Each conduit that you invoke using the ConduitManager puts an entry
in the Win95 registry. During a hot-sync, the registry is scanned,
and each ConduitManager conduit is invoked, which transfers the data
to and from the Pilot.



Generic Conduit Manager for Developers
--------------------------------------

The Palm/USR conduit system is designed to allow a hotsync to
occur with both native and foreign data. The designers assume
that foreign data is in such a format that code will have to be written
to implement a hotsync. Therefore, the conduit system assumes that
each conduit will be different/unique. And that the data format for
each conduit will be different/unique.

The designers of the HotSync system also provide a "backup
conduit" which simply transfers raw data, in bulk.

I felt that these assumptions were a bit onerous. They assume that
everybody who develops a PC app will be interested and capable of
writing a DLL. I didn't think this was a reasonable assumption.
[Aside: To be a "real" Pilot programmer, you have to be conversent in
4 API's (Mac, Pilot, Win32 and ConduitSDK). That's 2 too many for
me.]

The Conduit Manager system uses a generic conduit, which can
sync any Pilot database on a record-by-record basis. In order to
do this, here are my assumptions:
	-the data storage format on the PC is fixed
	-the data storage format on the PC uses big-endian
numbers (like a Macintosh)
	-the PC programmer is willing to read and write
files that conform to these constraints

This means that developers on the PC can work at a simpler level.
There is no need to learn the entire Conduit management system. On
the other hand, we (the PC developers) have to write the code to read
and write MAC style numbers, and deal with fixed format records that
are created by a foreign app. If you can live with this, climb abord.


In the coming weeks, I will bolster this package with documentation
on the file formats, and sample code for the use of the GenCond.DLL
and the Generic Conduit Manager.




Features for programmers
------------------------

-provides a programming environment for creating sync'ing apps
-enables auto-install of apps or data




Future Features
---------------

The 1.1 release of the Conduit Manager will include:
-operation in the HotSync 1.1 environment
-auto-backup of your entire pilot, including all apps and data
(but probably not "preferences")


Contact
-------

patb@corel.ca



Shareware Status
----------------

It's too early in the cycle, but this project will be either
shareware or freeware. The decision is based on your feedback.




History
-------

X11 Dec 4/96	DinkyVw 2.3
			-changed the about box
			-fixed a benign bug in "new picture" code
			-changed printing back to PaintPicture() call
		ConduitManager 0.6
			-added interlock for detecting HotSync 1.1
X10 Dec 2/96	DinkyVw 2.2
			-changed help system to .htm file 
X9 Dec 2/96	ConduitManager 0.5
			-fixed DDE string for DinkyVw (should be "DinkyVw")
		DinkyVw 2.2
			-changed external DLL from gencond.dll to dinkvwa.dll
			(you no longer need to run DinkyVw from the Pilot directory)
X8 Nov 28/96	ConduitManager 0.4
			-fixed serious problems with the install
X7 Nov 27/96	ConduitManager0.3
			-added help text as an HTML file
			-modified the install so that DLL
			dependencies are checked (specifically,
			MSVCRT40.DLL)
			-modified the registry enumeration so
			that numeric gaps in the keys are visible
		DinkyVw2.1
			-added a crude 'overview' so that you can
			select a bitmap quickly from the collection

X6 Nov 26/96	-added a Pilot Money viewer
		-changed the conduit manager so that the PilotMoney conduit
			defaults to 'Pilot to PC'
X5 Nov 25/96	-got rid of MFC dependencies; this version
		only requires MSVCRT40; BTW, this code is
		written in VisualC++ 4.1.
		-fixed backup file management
		-improved sync logic, especially for DinkyPad
		-fixed slow-sync logic
unnumbered Nov17/96 private release to some developers
		
		

======================================================================
======================================================================
======================================================================
======================================================================



Tech Notes
----------
(hackers only)

In order to write a generic conduit, I had to figure out how to make
sure that the conduit gets called by the HotSync system. Using
HotSync 1.0, that is not simple, since the HotSync.exe (actually
syncmgr.dll) enumerates the databases in the Pilot, and only calls
the DLL's that are required to service this list. If the app that the
user has requested does not make it onto this enumeration, the DLL
will not get called.

To get around this, I install a proxy in the MemoPad conduit, by
inserting an ApplicationX registry entry. During the startup of the
gencond.dll, I reach back into the Component3 registry entry and
execute the memcond.dll first, and then run through the
ConduitManager entries.

For each one, the gencond.dll uses the registry information to locate
a file and reads it into memory. It then tries to sync up, record by 
record and creates a new local file. If all went well, the old file
is renamed and the new file written.

DDE
---
If you have an application that is running, it will get a couple of
DDE messages. Before the file is opened by the conduit, you will get
a "application/notify" message command with the string "sync start".
You have 1.5 seconds to write the file to disk before the gencond.dll
will try to read it.

After the file has been written, you will get a "application/notify"
message command with the string "sync finished". You can then re-read
the file into the app. [All records will be marked clean, and deleted
records will have been purged.] [Look at the source for cbasVw, in
Form_LinkExecute.]


Locating User Files
-------------------

In order to locate the files, each time the gencond.dll is executed, 
it puts an entry in the registry:
HKCU/Software/Palm Computing/PilotDesktop/Preferences/LastUserDir
="name of user dir, without trailing backslash"

To locate the data files, simply concatenate a "\DirName" to
this string. This should be the same DirName that the user put
into the ConduitManager. Examples are "DinkyVw" or "cbasVw".


Services
--------
If you wish to use it, the DinkVwA.DLL and GenCond.DLL export a simple little
routine to build up multiple backup files.

/*SDOC

  Function: MakeBackupFiles

  Params:   sFileName the name of the target file
      nBackups  the number of backups to keep

  Action:   The sFileName is used to locate a directory where
      the output files will go.

	If the sFileName does not exist, the function exits with a 0

      The current backup files are enumerated and
      the actual file called sFileName will
      be renamed to a backup file.

	Files which exceed the backup limit are deleted.

  Returns: 0 if no file activity took place; usually means that
			the given file does not exist
	
  Comment:
      Style 0 backups proceed like
        file.txt (original)
        file.txt.1
        file.txt.2
        file.txt.3
        ...
       (note: this destroys the Win95/NT association)
EDOC*/

C/C++
int MakeBackupFiles(const char* sFileName, int nBackups);


VB
Declare Function MakeBackupFiles lib "gencond.dll" alias _
"_MakeBackupFiles@8" (ByVal sFileName as String, _
ByVal nBackups as Long) as Long
