Programming Visual Basic for the Palm OS

Installing the CDK

The Conduit Development Kit (CDK) is freely downloadable from the Palm web site.^[29] The CDK contains libraries and runtime bindings for VB and COM, as well as the C/C++ language. The InstallShield wizard puts everything into the directory you select (see Figure 4-3).

Figure 4-3. CDK directory structure

You can choose to install only the COM libraries, samples, and documentation by using the custom installation procedure and deselecting the C/API. We recommend performing a full installation, because the C/API contains some additional documentation you will find useful.

The Com folder contains the VB tutorial and sample projects, an installation tool, and another directory that simply contains links to the documents mentioned above. Most of the sample projects in the CDK are primers that focus on explaining at most one or two parts of the CDK. There is also a longer example, SyncSamp, which replaces the default Memo conduit and illustrates a complete conduit.

The Common folder contains the CDK programs and libraries used when developing conduits. This folder also contains the documentation, in both Adobe PDF and Microsoft Help formats. Earlier releases of the CDK runtime are supplied for backward compatibility; these won’t help you, because only the most recent release supports VB development.

If you have the Palm desktop software installed on your development machine, as is required to run AppForge, there are some issues you should be aware of when you install the CDK. By default, your system uses the HotSync manager that was installed with the Palm desktop software. Unfortunately, the ActiveX objects needed to develop and debug conduits are not installed with earlier releases of the Palm desktop.

If you have the luxury of developing your applications and software on separate computers, the following step is unnecessary. Otherwise, you will have to alter the desktop configuration so that the new HotSync manager runs during the synchronization process. Use the Microsoft RegEdit.exe tool, and alter the two registry keys as shown in Example 4-1. Note that the location of the updated HotSync manager depends on where you installed the CDK on your filesystem.

Example 4-1. Registry settings for HotSync manager

HKEY_CURRENT_USER\Software\U.S. Robotics\Pilot Desktop\Core
    HotSyncPath = C:\CDK401\Common\Bin\C4.01\Hotsync.exe
    Path = C:\CDK401\Common\Bin\C4.01

This is a good time to run the CDK tutorial SimpleDB, which shows how to run and debug a program under the control of the HotSync manager. This is how all conduits are executed, and it is important that you get comfortable with this environment. Running the tutorial also ensures that all of the CDK components are properly installed, and that the new HotSync manager is running correctly.

To run the tutorial, use the CondCfg.exe program to register the VB development environment as a conduit. Once the HotSync manager calls the VB IDE, you are in control and can test and debug your conduits with all the powerful VB features to which you are accustomed.

Let’s walk through the steps required to configure the tutorial. Start the CondCfg.exetool to show all the currently registered conduits, and to add, edit, and delete conduits. If you are developing on your own Palm desktop, be careful not to disturb the settings for the native Palm applications! We disable all conduits except those actually under development; this both increases the speed of the synchronization process and provides some security from data corruption. Press the Add button to bring up the Conduit Information dialog, into which you enter the settings for your conduit (see Figure 4-4). First, you must enter ComConduit.dll in the name field. The HotSync manager uses this DLL to locate and instantiate COM conduits.

Figure 4-4. CondCfg.exe registration screen

Because each conduit handles exactly one application on the Palm device, you must enter the unique Creator ID of your application. (There must be only one conduit registered for any Palm application. CondCfig.exe will not allow you to register a second conduit for the same application, or, more precisely, an application with the same Creator ID).

Tip

If there is no application on the Palm device with this ID, then the conduit will not run. You must install your Palm application first.

For our sample conduit, we entered Ch4a as the Creator ID. In addition, we entered Ch4aDB in the optional remote database field. As we’ll see later, the HotSync manager provides the conduit with a more accurate list of databases during an actual synchronization session.

In the extra information group box at the bottom of the dialog, select the COM Conduit radio option button. Enter the full path to the VB IDE in the COM client field.

Leave all the other fields blank or with the default values. These settings were shown earlier in Figure 4-4. Press the OK button to register the new settings, and restart the HotSync manager. Then exit the configuration tool.

Now put the Palm device into the cradle and press the HotSync button. Although the synchronization process runs normally, the VB IDE doesn’t activate. That is because the HotSync manager could not find an application on the Palm device with a Creator ID of Ch4a.

You will need to download our sample application for this chapter and install the application file Ch4a.prc. After the application is installed, perform a HotSync one more time. This time, the HotSync manager on the desktop displays the message Status: Synchronizing COMConduit, and the VB IDE pops up.

Now you can test your environment by opening SimpleDB.vbp in the CDK Tutorial folder. This VB project opens the native Memo application, and reads all the records that match a search term. Set a breakpoint in the button click event, and press F8 to step through the program. Note that Palm device displays Synchronizing Memo Pad, because the Memo database has been opened during a HotSync session. You are now communicating as a conduit with the Palm device from VB!

If the VB IDE doesn’t appear, put the HotSync manager into its verbose mode. First, stop the HotSync manager by right-clicking on its icon in the Windows system tray, and select Exit. Next, restart the HotSync manager with the -v option from the command line. After synchronizing, you can review the diagnostic log for errors. To do this, right-click on the icon and select View Log.

If the SimpleDB project doesn’t connect to the Palm, or exhibits other errors, check that the Palm conduit references are set correctly (these are shown later in this chapter in Figure 4-7). You do this from the VB IDE by choosing the References option from the Project menu. If these references are missing, try registering those ActiveX libraries by hand and restarting VB.

---

^[29] You want CDK release 4.01 DR1, which was the latest release available as of this writing. This release is the first that exposes a COM interface specifically for VB development.