This is release 1.3 of the Currency Conduit. This release was made on February 8, 2006.
Currency Conduit Release 1.3, including this documentation, is adapted from release 1.2 by Tim Endres to work with the current version (3.4beta as of this writing) of Currency.
This conduit will automate the updating of your Currency Calculator program on the Palm by acting as a conduit to the Palm program. Conduits run when you HotSync.
Of course, you must first install the Currency calculator on your palm. The Currency Calculator program that runs on the Palm was originally written by Henrique Martins and updated for Palm OS 5.4.x by Ton van Overbeek. Tim Endres originally wrote this conduit, which automates the updating of the currency rates so you do not have to manually download them. You can download a copy of the Currency Calculator program at:
http://currex.sourceforge.net
While this conduit is written in Java, which will run on any computer platform, it does require the JSync software from Palm in order to run. Unfortunately, Palm has only written the JSync software for the Windows platform. Therefore, the Currency Conduit will only work under Windows, not on the Macintosh, not under Linux. This conduit was tested under Windows XP. It should work fine on older Windows versions (95/98, NT4, and Windows 2000).
This document appears long and complicated, and the steps are certainly not entirely user friendly. However, some people who are very illiterate when it comes to computers have managed to install the software and to get it working. If you read all of the sections and follow each step carefully, you should be up and running in short order.
If you have one of the newer Palm handhelds (e.g. TX, Treo650, LifeDrive, Z22) then you are most likely using Palm Desktop and HotSync software version 6.0.x.
Java based conduits (including this one) are not working on HotSync 6.0.x.
One of the central dynamic link libraries (sync20.dll) for HotSync manager is missing some entrypoints needed for JSync based conduits. A replacement for sync20.dll, which provides these missing entrypoints, is available in the folder HotSync6. With this replacement JSync based conduits work with HotSync 6.0.x.
sync20.dll is located in the Palm Desktop folder, typically C:\Program Files\Palm. You can check the version by right clicking sync20.dll, select Properties, select the Version tab and look at 'File Version'. On my system the original sync20.dll has version 6.0.1 and the replacement has 6.0.3.
Do NOT replace sync20.dll if you are using an older version of the Palm Desktop and HotSync software. Doing so leaves you with a non-working HotSync. You have been warned.
Before you can use Java Conduits, you must have a Java VM installed on your PC, and you must install the Palm HotSync Java Support. If you are not sure if these are installed, you should run JSyncInstaller.exe to be sure. JSyncInstaller.exe will install everything that the Palm software needs to run Java based conduits. Once you have installed JSync, you will be able to run any Java based conduit, of which there are several very useful ones. It does not cause any harm to run JSyncInstaller.exe more than once.
If you need the JSync Installer package, you can download a copy from here:
http://sourceforge.net/project/showfiles.php?group_id=156150
and look for JSyncInstaller.exe in the "currency conduit" package.
The JSyncInstaller.exe download is 9.09 MB.
Please note that the JSync installer has a very poor user interface. It gives you very little feedback. However, it almost never fails, and if it does fail, you will get an error message. Thus, if the JSyncInstaller.exe file runs and completes and does not display any error messages, then it most likely installed correctly.
Once you have installed the Java Conduit support, you need to install the Currency Conduit software. To do this, simply copy the Java JAR file named "currex.jar" to a convenient location on your computer. A common location to place the file is in the JSync folder in your Palm Desktop installation folder (typically C:\Program Files\Palm\JSync). You may place it anywhere on your hard disk.
The currex.jar file is located in the 'jars' folder in the directory where you extracted the Currency Conduit ZIP archive.
Once you have installed the Java Conduit support, and installed the Currency Conduit JAR file, you need to configure the HotSync Manager software to know about the new conduit. To do this, run the program named "CondCfg.exe" in the folder named "ConfigHotSync". This program will display a dialog listing the currently configured conduits.
Click the "Add..." button. This will display a large dialog box with many fields. Fear not! Fill in those fields as follows:
- Conduit Type -
Select the 'Application' radio button
- Configuration Fields -
Conduit: jsync13.dll
Creator ID: cRr6
Directory: currex
File: currex.prf
Remote Database: CupdateDB
Name: Currency Conduit
Username: <your HotSync user name>
Priority: 2
Information: Currency Conduit
- Extra Information -
Select the 'Java Conduit:' radio button
Class Name: com.dotfile.palm.currexc.CurrExConduit
Class Path: <path to JAR file>\currex.jar
You must replace the "<your HotSync user name>" with the username configured in HotSync. To check this, select the "Custom..." menu item in the popup menu for the HotSync taskbar icon. This will display the customization dialog. Your user name will be displayed at the top of the dialog's contents, just above the conduit list.
You must also replace the "<path to JAR file>" in the Class Path with the path to the currex.jar file. A path is the list of folders, or directories, inside which a file resides. For instance, if you installed currex.jar in the "JSync" folder in the "Palm" desktop folder, then the Class Path might look like this:
C:\Program Files\Palm\JSync\currex.jar
You MUST NOW RESTART the HotSync Manager to get the new settings to take effect. To do this, click on the HotSync Manager icon in the taskbar (lower right corner of your screen). This will cause the HotSync Manager popup icon to appear. Select the 'Exit' menu item. The HotSync Manager icon will disappear from the taskbar.
To start the HotSync Manager again, click on the Windows Start menu in the lower left corner of your screen, select 'Programs', then 'Palm', and finally 'HotSync Manager'. This HotSync Manager icon should re-appear in the lower right corner of the taskbar again.
Otherwise, you can just restart the computer, which will accomplish the same thing. I recommend this if you do not fully understand the previous paragraph.
Before you run the HotSync, please configure the conduit. Click on the HotSync icon in your taskbar and select the "Custom..." menu command. This will display a dialog listing the conduits that can be configured. Select the "Currency Conduit" and click the "Change..." button. This will display the Currency Conduit Configuration dialog.
The "Currency Database Update URL" field is the field in which you enter the URL from which the database update will be downloaded. The default (http://currex.sourceforge.net/cupdate.pdb) should be OK.
If you are NOT behind a firewall, UNcheck the "Use Proxy?" checkbox.
However if you are behind a firewall, you may have to work through a proxy server. If so, check the "Use Proxy?" checkbox. Then fill in the hostname and port number fields with the hostname and port number of your proxy server. Your network administrator will provide these to you if you do not know what they are. You can also find the settings in your web browser's configuration. NOTE that the conduit does not support authentication, so if your proxy requires a username and password, you are out of luck, the conduit will not work behind your firewall.
If you are having difficulties making the conduit operate, please check the checkbox "Log Debug Info?", which will cause additional output on your HotSync log. Please include this log information in any correspondence you send, since it will help debug the problem more quickly.
Restart the HotSync Manager and sync your palm. You should now see the Currency sync reported in the log and during the progress messages. Each time you sync your Palm, you will get the latest exchange rates directly from the Web!!!!
ClassPath is not configured correctly in CondCfg.exe.
The ClassPath setting in CondCfg.exe tells the JSync software
where to find the code that implements the currency conduit.
If this setting does not point to the location of the 'currex.jar'
file on your hard disk, the JSync software will not find the
"java class" that implements the conduit. In this case you
will see 'ClassNotFoundException' messages all over your
HotSync log.
ClassName is not configured correctly in CondCfg.exe.
The ClassName setting in CondCfg.exe tells the JSync software
which "java class" implements the currency conduit.
If this setting is misspelled, the JSync software will not find
the "java class" that implements the conduit. In this case you
will see 'ClassNotFoundException' messages all over your
HotSync log.
The Conduit setting in CondCfg.exe is misspelled.
People frequently misspell the Conduit setting in CondCfg.exe
as 'jsynch13.dll', as opposed to the correct setting 'jsync13.dll'.
I see the message 'java.lang.ClassNotFoundException' in the log.
This is almost always the result of the ClassPath setting in CondCfg.exe
not being set properly. This setting must describe the location of the
currex.jar file on your hard disk. If you placed this file in the Palm
desktop directory, then the ClassPath might look like this:
C:\Program Files\Palm\currex.jar
The other common reason for this error message is that the ClassName is
misspelled in CondCfg.exe. The correct spelling is,
"com.dotfile.palm.currexc.CurrExConduit",
however, many people leave the 'c' off of the 'currexc' and spell it as,
"com.dotfile.palm.currex.CurrExConduit".
When I click on the 'Currency Conduit' item in the Custom Dialog,
nothing happens.
This is almost always the result of the ClassPath setting in CondCfg.exe
not being set properly. This setting must describe the location of the
currex.jar file on your hard disk. If you placed this file in the Palm
desktop directory, then the ClassPath might look like this:
C:\Program Files\Palm\currex.jar
The other common reason for this problem is that the ClassName is not spelled correctly in CondCfg.exe. Otherwise, check all of your settings in CondCfg.exe.
After I configure the conduit in CondCfg.exe and restart HotSync, the
conduit is not listed in the Custom Dialog.
This is often because the 'Creator Id' is not set properly in the CondCfg.exe.
Make sure it is 'cRr6'. If you misspelled it, please delete the incorrect
conduit using the 'Delete' button in CondCfg.exe. Then, use Add to add a new
one and spell the Id correctly.
Another common problem is that the 'Conduit' setting in CondCfg.exe is not spelled correctly. It should be 'jsync13.dll', but people often misspell it as 'jsynch13.dll', which will not work.
Everything is configured and the conduit runs, but I get an error
saying "Read/Write Error" or "Operation timed out".
Sometimes the server for the currency updates is overloaded
and running slow. This causes the conduit to timeout. This is usually
the problem when you see the "Operation timed out" message.
Otherwise, the other most common reason for this problem is firewalls and proxies. A firewall is designed to protect your local network from the worldwide Internet. It limits what connections can come in and out. To allow your web requests (like a request for a web page) to work, the firewall will provide a "proxy" to escort you through the wall. In such a situation, you will need to check the "Use Proxy?" checkbox and fill in the configuration for the proxy host and port number, which your admin will provide you. However, if your proxy requires a username and password, the conduit will not work for you, as passwords are not supported.
When I try to add the conduit in CondCfg.exe, I get the message "Conduit
already exists", and I can not save the settings.
This is because you have already added the conduit once. If it is already
listed, just click on the 'Details' button to edit the settings of the
existing conduit entry.
When I run the JSync installer, nothing happens.
Something always happens when JSyncInstaller.exe is run.
The UI is simply not very good and does not give good feedback. However,
it very rarely fails. If you find a directory named 'JSync' in your
Palm directory, then the installer worked just fine. Typically, once
you run JSyncInstaller.exe, you are set as far as JSync is concerned.
Currency Conduit Software
First, run the CondCfg.exe program and select the 'cRr6', 'Currency
Conduit' item in the list, then click the 'Delete' button. This will
clear your registry of the conduit's settings.
Delete the currex.jar file.
Delete the directory that you created when you extracted the contents of the Currency Conduit ZIP archive.
JSync Software
Open the 'Add/Remove' dialog box by double clicking the 'Add/Remove'
icon in your Control Panel (Start menu --> Settings --> Control Panel).
Select the 'Palm Conduit Support for Java' line in the list of installed
software and click
the 'Change/Remove' button. This will uninstall the JSync software.
You have uninstalled the software.
You are reading it.
If you are unable to get the conduit to work, please re-read each section of this document. As a final resort you can ask a question in the 'Open Discussion an Help' forum on sourceforge:
http://sourceforge.net/forum/?group_id=156150
You can also uninstall the conduit. Remember, you can
still use the Currency Calculator program and update it manually.
Many thanks to Tim Endres, the original author of this conduit and its
documentation and to
Stefan Braunstein (
http://www.braunstein.de/pda/palm/currency/
) who kept the conduit source after the disappearance of Henrique Martins
original website.
Ton van Overbeek, ton@v-overbeek.nl