In this chapter:
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 |
You can launch a sync with several different flags that give you information on what is occurring. These useful flags are:
-v
Verbose mode
-L1
Different verbose mode
-L2
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 |
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 |
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 |
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:
· GetConduitName
· GetConduitVersion
· OpenConduit
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.
Test with POSE |
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 |
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 |
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.