Welcome to the Pilot Generic Conduit Manager

VERSION 3.0 NOTICE
------------------
THIS BUILD IS FOR HOTSYNC 1.1 and HOTSYNC 2.0 ONLY!

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

Features
--------

-provides data backup services for any Pilot app
	-fixes the data backup conduit problems of HotSync 1.1 (original version)
	-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
	-JFile
	-DinkyPad
	-cbasPad
	-Pilot Money
	-PAL
-bundled with PC viewers for DinkyPad, cbasPad and JFile
-fully supported by the MoneyView app from StingerSoft


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
------------
	GenCn20.dll	is the heart of the Conduit Manager system
	DinkVwA.dll	a helper .dll for my apps
	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
	JFileVw.exe	is a VB app to view, edit and import/export 
			databases for the JFile Pilot app

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.1 and HOTSYNC 2.0 ONLY! DO NOT USE THIS VERSION
WITH HOTSYNC 1.0!

Simply extract all the files to a working directory. Run the
CondMgr.exe program.

Install any of the pre-configured conduits, or install a custom.
On the first install, the app will copy the GenCn20.dll to the
correct location.
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

The JFile program requires that you first install the conduit (through
the CondMgr.exe program) and then install the individual databases 
(through the JFileVw program). [NOTE: you can actually run the JFileVw
program without installing a conduit, but you won't have the two-way
sync features that a GCM conduit will give you.]
Once installed, you can:
	create new records
	delete records
	edit records
	cut, copy and paste to text or spreadsheet apps
	save and load .csv files
	future versions will have printing and tab-separated files
	


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 the data from third party apps is only 
sent to the PC once. After this backup, any changes or additions
you make to your Pilot will not be sent to the PC for backup.
[It is possible that this is intentional; we need to find out from
the original programmers :) ]

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.






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
---------------



Contact
-------

patb@corel.ca
http://cpu563.adsl.sympatico.ca/gcm.htm



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

Freeware.




History
-------
GCM3.3 May 13/97
		JFileVw 3.3
			added the About box
			minor edits do not cause the column widths to change
			took out some debugging stuff
GCM3.2 May 12/97
		Conduit Manager 3.2
			fixed bugs in remove-conduit
GCM3.1 May 8/97
		JFileVw 3.1
			minor fixups on edit box
			detects and warns if HS is running
GCM3.0 May 7/97
		Conduit Manager 3.0
			supports HotSync 2.0
		GenCn20.dll 2.0.5
			supports multiple databases per conduit
			supports HotSync 2.0
		DinkyVw 3.0
			supports HotSync 2.0
		cBasVw 3.0
			supports HotSync 2.0
		JFileVw 3.0
			first release

GCM2.3 Jan 31/97
		Conduit Manager 2.3
			improved install
			added new sync notify method
		GenCn20.dll 2.0.4.0
			added new sync notify method
		DinkyView 2.8
			added comic view mode
			fixed 32k file limit
			speed up
		CBasView 2.1
			fixed 32k file limit
GCM2.1 Jan 20/97
		Conduit Manager 2.1
			changed the default global-backup directory
			to "GBackup"
		GenCn20.DLL
			bugfix: if the global-backup directory was
			a null string, the code bombed
GCM2.0 Jan 20/97
		Whole new release
		whole new can 'o worms
X7 Nov 27/97	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/97	-added a Pilot Money viewer
		-changed the conduit manager so that the PilotMoney conduit
			defaults to 'Pilot to PC'
X5 Nov 25/97	-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)


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 GenCond.DLL and DinkVwA.dll export a 
couple of simple little
routines 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

There is also a RegRenameKey() routine. Please see the docs on the
net.

