Order the book from O'Reilly

Previous PageTable Of ContentsIndexNext Page

In this chapter:

 14.  Debugging Conduits

Two of the most important tools you have in your debugging arsenal are a number of flags you can set during a sync and source-level debugging in CodeWarrior. After we discuss these, we give some advice on specific problems you might encounter.

Last but not least, we will look at how to clean things up. Mucking about in your conduit code is a good way to mess things up; we show you how to tidy up the registry when you are through.

HotSync Flags

Top Of Page

You can launch a sync with several different flags that give you information on what is occurring. These useful flags are:

Verbose mode

Different verbose mode

Different verbose mode with packet information

Besides these flags there is another flag, -c, that you can use to verify your connection.

Running HotSync in Verbose Mode with -v

If you want to run HotSync in verbose mode, you set the -v flag by hand from the Run dialog:

c:\PalmDesktopDir\hotsync.exe -v

If you are already running HotSync, you need to exit before you can launch it by hand. Just choose Exit from the menu (see Figure 14-1).

-Figure 14- 1. Exiting the running version of HotSync

Once you are in HotSync verbose mode, the log contains a great deal of additional information regarding its activities. Here's an example verbose log (abridged for space):

---Initializing User Manager---
---Discovering Communication State---
---Identifying Viewer user---
Found user name
---Establishing Sync Locale---
---Performing HotSync---
   Validating User.
   User match exists.
HotSync started 07/31/98 11:52:13
Setting up local HotSync environment.
   User is  Fen Rhodes
ROM Listing
   System                         0001 70737973 02/20/1998 02/20/1998 0003
   AMX                            0001 70737973 02/20/1998 02/20/1998 0003
   UIAppShell                     0001 70737973 02/20/1998 02/20/1998 0003
...
   Mail                           0002 6D61696C 02/20/1998 02/20/1998 0003
   Expense                        0001 65787073 02/20/1998 02/20/1998 0003
RAM Listing
   Unsaved Preferences            0000 70737973 04/14/1998 07/30/1998 0001
   Net Prefs                      0000 6E65746C 04/14/1998 06/29/1998 0001
...
   Sales                          0001 536C6573 07/30/1998 07/30/1998 0001
   Sles_Customers                 0000 536C6573 07/30/1998 07/30/1998 0000
   Sles_Orders                    0000 536C6573 07/30/1998 07/30/1998 0000
   Sles_Products                  0000 536C6573 07/30/1998 07/30/1998 0000
Attempting to Sync with Conduit:  datcn20.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component0
   Sync type is Fast
Local path is C:\Pilot\RhodesF\datebook\
   Remote name 0 is DatebookDB
   Loading   datcn20.dll   conduit
OK Date Book
   Conduit successful
Attempting to Sync with Conduit:  addcn20.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component1
   Sync type is Fast
Local path is C:\Pilot\RhodesF\address\
   Remote name 0 is AddressDB
   Loading   addcn20.dll   conduit
OK Address Book
   Conduit successful
Attempting to Sync with Conduit:  d:\poscond\todcnd21\debug\todcn20d.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component2
   Sync type is Fast
Attempting to Sync with Conduit:  memcn20.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component3
   Sync type is Fast
Local path is C:\Pilot\RhodesF\memopad\
   Remote name 0 is MemoDB
   Loading   memcn20.dll   conduit
OK Memo Pad
   Conduit successful
Attempting to Sync with Conduit:  bakcn20.dll
   No Registry Key
   Sync type is Backup
Local path is C:\Pilot\RhodesF\Backup\
   Remote name 0 is System MIDI Sounds
   Remote name 1 is Saved Preferences
   Remote name 2 is Graffiti ShortCuts 
   Remote name 3 is NetworkDB
   Remote name 4 is LauncherDB
   Loading   bakcn20.dll   conduit
OK System
   Set PC ID and last sync time on Palm organizer
Cleaning up local HotSync environment

The log has two very useful pieces of information:

A Different Verbose Mode with -L1

HotSync 3.0 and later versions have two additional verbose mode flags: -L1 and - L2. Although some of the messages printed when using the -v flag are printed when using either of these new flags, not all are. Therefore, you may want to use - L1 or -L2 in addition to the -v flag.

NOTE:

When you use the -L1 or -L2 flags, the HotSync.log file is located in the top-level directory. It is located with HotSync.exe (as opposed to its normal location within the user's directory).

Here's an example output from using the -L1 flag:

A Direct serial connection is pending  08/01/98 14:40:49
Establishing Connection with the Palm organizer
Direct Serial Connection: Baud rate = 57600 

Port speed is 57600 bps
Initialized Sync Manager Successfully 

---Initializing User Manager---
---Discovering Communication State---
---Identifying Viewer user---
 An account is found for Palm organizer user: Fen Rhodes 

The primary Hotsync PC for this user is unknown 

---Establishing Sync Locale---
---Performing HotSync---
   Validating User.
   User match exists.
HotSync started 08/01/98 14:40:52
Setting up local HotSync environment.
   User is  Fen Rhodes
Attempting to Sync with Conduit:  datcn20.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component0
   Sync type is Fast
Local path is C:\Pilot\RhodesF\datebook\
   Remote name 0 is DatebookDB
   Loading   datcn20.dll   conduit
   Conduit failed
Attempting to Sync with Conduit:  addcn20.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component1
   Sync type is Fast
Local path is C:\Pilot\RhodesF\address\
   Remote name 0 is AddressDB
   Loading   addcn20.dll   conduit
   Conduit failed
Attempting to Sync with Conduit:  d:\poscond\todcnd21\debug\todcn20d.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component2
   Sync type is Fast
Local path is C:\Pilot\RhodesF\todo\
   Remote name 0 is ToDoDB
   Loading   d:\poscond\todcnd21\debug\todcn20d.dll   conduit

Trying to open database: ToDoDB 
 08/01/98 14:41:08
OK To Do List
   Conduit successful
Attempting to Sync with Conduit:  memcn20.dll
   Key is Software\U.S. Robotics\Pilot Desktop\Component3
   Sync type is Fast
Local path is C:\Pilot\RhodesF\memopad\
   Remote name 0 is MemoDB
   Loading   memcn20.dll   conduit
   Conduit failed
Attempting to Sync with Conduit:  C:\SalesCond\Debug\SalesCond.DLL
   Key is Software\U.S. Robotics\Pilot Desktop\Component4
   Sync type is Do Nothing
Local path is C:\Pilot\RhodesF\Sales\
   Remote name 0 is CustomerDB
   Invalid conduit version
   Loading   C:\SalesCond\Debug\SalesCond.DLL   conduit
Sales - sync configured to Do Nothing
   Conduit successful
Attempting to Sync with Conduit:  bakcn20.dll
   No Registry Key
   Sync type is Backup
Local path is C:\Pilot\RhodesF\Backup\
   Remote name 0 is System MIDI Sounds
   Remote name 1 is Saved Preferences
   Remote name 2 is Graffiti ShortCuts 
   Remote name 3 is NetworkDB
   Remote name 4 is LauncherDB
   Loading   bakcn20.dll   conduit

The -L1 flag includes, among other things, the baud rate at which the connection was made.

A Different Verbose Mode with Packets Using -L2

The -L2 flag includes all the output from -L1 plus a trace of all the packets sent to and received from the handheld. Please note that the log becomes quite large. Here's a small excerpt of some output:

A Direct serial connection is pending  08/01/98 14:47:38
Establishing Connection with the Palm organizer
Direct Serial Connection: Baud rate = 57600 

Port speed is 57600 bps
Sending Command ReadSysInfo . Packet size = 8
Packet Trace: 
12 01 20 04 00 01 00 02                                | .. .....

Response Received. Packet size = 34
Packet Trace: 
92 02 00 00 20 0E 03 00   30 00 00 01 00 00 00 04      | .... ...0.......
00 01 00 00 21 0C 00 01   00 02 00 03 00 00 00 00      | ....!...........
 
Initialized Sync Manager Successfully 

---Initializing User Manager---
---Discovering Communication State---
Sending Command (null) . Packet size = 14
Packet Trace: 
39 01 22 0A 00 80 68 74   61 6C 68 74 63 70            | 9."...htalhtcp

Response Received. Packet size = 4
Packet Trace: 
B9 00 00 05                                            | ....
 
Sending Command ReadFeature . Packet size = 10
Packet Trace: 
38 01 20 06 6E 65 74 6C   00 00                        | 8. .netl..

Response Received. Packet size = 10
Packet Trace: 
B8 01 00 00 20 04 02 00   30 00                        | .... ...0.

We can't think of a reason you'd need to see the packets going back and forth between HotSync and the handheld, but we've provided this option for completeness.

Quick-Connect Mode

HotSync 3.0 and later versions have a -c flag that immediately disconnects from the Palm OS handheld after connecting and obtaining the user name. This is a handy way to verify your connection to the handheld.

Rebuilding the Registry

Occasionally, you may find that your Conduit Registry is totally fouled or that you've unregistered (or changed) one or more of the default conduits.

To repopulate the Conduit Registry with the default settings for each of the default conduits, first use CondCfg to delete the entries for the default conduits and then use the -r flag of HotSync, which adds back entries for each of the default conduits:

hotsync.exe -r

You can accomplish the same thing while using the debug version of things. Simply use the -r flag with the debug version of HotSync:

hotsyncd.exe -r

This repopulates the registry with entries for the debug versions of each of the built-in conduits rather than entries for the release versions.

Source-Level Debugging

Top Of Page

Source-level debugging can be an invaluable aid to finding problems in your code. It does require careful setup and building, however. First, you need to build and run a debug version (which requires special libraries). Next, you need to set your breakpoints. In the following sections, we describe how to do this.

Building a Debug Version

To build a debug version of your conduit, select Set Active Configuration in the Build menu. This specifies the debug rather than the release version of the conduit. To complete the build of a debug version, you also need to link with debug versions of the libraries. These libraries end in d.lib (for example, hotsyncd.lib is the debugging version of hotsync.lib). You can specify the debug versions of your libraries in the Link panel of the Project Settings dialog.

Running a Debug Version

To run a debug version of your conduit, you need to do a number of things:

1. Run a debug version of HotSync (hotsyncd.exe).

2. Debug versions of the DLLs need to be in the HotSync directory. A release version of HotSync won't load a conduit built to run with debug. The 3.0 Conduit SDK ships with debug versions of HotSync and the DLLs. Copy them to the directory, where they can reside with the nondebug versions.

3. Run CondCfg, so that the entry for your conduit points to the debug directory rather than the release directory. Use path\debug\MyConduit.DLL rather than path\release\MyConduit.DLL.

4. In the Debug panel of the Project Settings dialog, specify the full pathname to hotsyncd.exe as the executable (see Figure 14-2).

Figure 14- 2. Specifying the application to run when debugging the conduit

Setting Breakpoints

To set breakpoints in your code, you right-click on a line and choose Insert/Remove Breakpoint, as shown in Figure 14-3.

Figure 14- 3. Setting a breakpoint in your code at a particular line

Once you have gotten this far, you are almost ready to roll. You have just two more steps:

1. Exit the HotSync Manager if it's currently running.

2. Choose Go from the Start Debug submenu of the Build menu. You can also use the F5 function key as a shortcut.

Avoiding Timeouts While Debugging

Top Of Page

When you are debugging a conduit, there are two timeouts that you need to avoid. The first is an automatic-off timeout, the second a HotSync one.

Auto-off Timeout

There is a timeout that causes the handheld to go to sleep after a certain time (a power-saving feature). If you're in the middle of single-stepping through your conduit and the handheld goes to sleep, you'll have one thoroughly ruined debugging session. To avoid this problem, use the ..3 shortcut (see "Device Reset" on page 284 for a full discussion). It stops the Palm OS handheld from going to sleep.

NOTE:

Until you do a reset, the Palm OS handheld won't go to sleep again automatically. Try not to wander away from your debugging to other things. If you do, when you come back to your debugging after a good night's sleep, your batteries will quite likely have expired.

HotSync Timeout

The other timeout you need to worry about is the timeout of the HotSync protocol. If you are stopped at a breakpoint while in the middle of a synchronization, the HotSync application is not sending information to the handheld. The handheld then thinks that the connection has been lost and ends the HotSync session.

Opening the secret handheld option

To convince the handheld not to give up, you need to use a secret option that lies hidden within the handheld HotSync application. To get to it, you open the HotSync application on the device. Next, carefully place the handheld in a brown paper bag and wave it over your head while screaming like a chicken-okay, just kidding. What you really do is:

1. Hold down the scroll-up button on a Palm OS 3.0 device or both the scroll-up and scroll-down keys on a pre-3.0 device.

NOTE:

In POSE (on Windows only), you can simulate pressing the scroll-up and scroll-down keys by holding down the keyboard Page Up and Page Down keys.

2. While holding the key(s), tap in the top-right corner of the screen.

The secret alert

You should see an alert, as shown in Figure 14-4. Now HotSync is your dutiful servant, waiting forever and never timing out. If you quit the HotSync application and reopen it, this option is reset; the HotSync application can again timeout.

Figure 14- 4. HotSync secret alert

Conduit Problems You Might Have

Top Of Page

The following are two of the most common problems you may come across when debugging a conduit.

When an Installed Conduit Doesn't Run

A problem that you might encounter is having a conduit that appears to be installed but doesn't get called during a sync session. First, check the presyncing setup by choosing the Custom menu of HotSync. If your conduit doesn't show up in the list, check the items in the following sections.

A mismatched HotSync and conduit

If you use a release version of one with a debug version of the other, the conduit is not called. Make sure that a debug version of your conduit is linked with debug versions of the DLL and that release versions are linked with release versions.

The DLL isn't where it's supposed to be

If you provide a full pathname for your conduit, make sure it's there. If you specify only the conduit name (MyConduit.DLL), the conduit must be in the DLL path (a common place to put it is in the same directory as HotSync.exe).

Select the conduit and press the Change... button to have your ConfigureConduit routine called. If it doesn't work-you know because your ConfigureConduit dialog doesn't appear-here are some possible reasons:

Required functions not present

Check that your  ConfigureConduit (or, for HotSync 3.0, CfgConduit) routine is in your conduit and declared as __declspec(dllexport).

Also, make sure that the following are present and exported:

HotSync hasn't been restarted

After you make changes to the registry using CfgCond.exe, you should restart HotSync to make sure it rereads the registry.

Once you've got your configuration dialog up, you know that HotSync has found your DLL and called your code successfully. Now if you try to Sync and your conduit doesn't run, it's almost certainly because of one of the two following reasons:

Your conduit requires a matching creator ID

Run HotSync in verbose mode to check the Creator ID of your application. Check that ID against the creator registered for the conduit (in CondCfg.exe). They must match.

Conduit configured to do nothing

Your conduit may be configured to do nothing (check the Custom/Change dialog from the HotSync menu). Even if your conduit is configured to do nothing, the OpenConduit entry point should still be called. You can set a breakpoint and see whether it is being called or alternatively check the verbose HotSync log.

When the Handheld Crashes After Syncing

Each application with an associated conduit that ran during a sync is sent the sysAppLaunchCmdSyncNotify launch code. When this launch code is sent, the application does not have any global variables available to it and therefore must not try to access them. If it does, it will most certainly crash in a large flaming wreck.

To ensure this doesn't happen to you, have your PilotMain check the incoming launch code, and verify that it doesn't access global variables directly or indirectly.

NOTE:

We had a problem when building the conduit: it kept crashing. Here is the story. Earlier in our code we had added the ability to keep track of what ROM version the application is running on. We did this by modifying RomVersionCompatible to save the ROM version in a global. Now, much later on when we are trying to get our conduit up and working, we are crashing. It turns out that our PilotMain was calling the RomVersionCompatible first, before checking the launch code. The result: our application kept crashing. Don't make the same mistake.

Test with POSE

Top Of Page

A good way to catch problems in your conduit code is by using POSE. It's possible to sync with POSE running on a different machine (in which case the cable is on the machine running your conduit) or on the same machine (in which case the cable is going out one serial port and in another). For example, this is how we debugged our handheld application that was crashing after a sync. We set a breakpoint in PilotMain and waited for it to get called at the end of the sync process; single-stepping through the code finally showed the problem. If that wasn't enough to convince you, remember that it saves batteries and doesn't require a cradle, either.

NOTE:

Some laptops have only one serial port. Consider augmenting the built-in serial card with a serial PC card (we use a Socket serial card that costs about $125-see http://www.socketcom.com.

NOTE:

If you're using the Mac OS version of POSE, make sure that the POSE window is frontmost while you are syncing. This gives the emulator more CPU time during the sync. Trust us, it needs it.

Turn Off Other Conduits During Testing

Top Of Page

It is also a very good idea to turn other conduits off during your test cycle. This gives you a much faster sync cycle. To do this, have the other conduits "Do Nothing" as their default sync action. That will make them very sleepy, and they won't wake up during the sync.

Use the Log, Luke

Top Of Page

The HotSync log is your friend. During your development, have your code log everything that's going on during the sync. It's one of the easiest ways to see what's happening and hence find out where problems are.

That's it. You should now have a fully debugged conduit to go with your fully debugged Palm application. This is the end of the book, so that means you know everything you need to know. Have fun, and good Palm programming to you.


Palm Programming: The Developer's Guide
Copyright © 1999, O'Rielly and Associates, Inc.
Published on the web by permission of O'Rielly and Associates, Inc. Contents modified for web display.

Previous PageTop Of PageTable Of ContentsIndexNext Page