Online Callbook DLL for MixW
Performs on-line callsign lookups from within MixW

Now!  Updated for QRZ V2 support (1 Jan 2009)
and fixes a bug in handling callsigns containing a slash character ("/")

This add-in for the digital-mode program MixW will automatically do a callsign lookup from qrz.com and fill select information into your MixW log entry.  It also optionally checks to see if the station is a known LoTW user, and notes this by placing [L] in the Mgr field in the MixW log.  You can choose one of two sources to use for callsign data:

• QRZ.COM's public web pages -- These are the same, freely accessible, pages that you use to lookup a callsign via your web browser. QRZ does not charge for this service. While it's nice that it's free, it relies on the format of the QRZ.COM web pages not changing in any way.  This makes this method easily broken.  Note that each lookup also requires retrieving a complete QRZ.COM web page (advertisements and all), which makes this method much slower.
  
  
• QRZ.COM's XML Data Service -- This service provides access to a fast, dedicated, port that is specifically designed for doing on-line callsign lookups. QRZ charges for access this service, but it's faster (especially during contests or for heavily accessed callsigns) and its far more accurate. See http://online.qrz.com for more details about their XML Database Service.

The fields that are filled-in by this DLL are: Name, QTH, Loc, and Mgr. For US contacts, the QTH field is filled-in with city and state.  For non-US contacts, the QTH field is filled-in with the country.  For US contacts looked up using the QRZ.COM XML Data service, the DLL also fills-in the State and County fields.

A Note From K1PGV To All Users (please read):

The December 2008 changes to the format of the QRZ.COM web pages have made it much more difficult to perform reliable lookups using the "free" method.  Even small, seemingly invisible, changes to the format of the QRZ.COM web pages can cause free lookups to stop working. While I'll attempt to support free lookups via the DLL as long as practical, I can't guarantee that I'll be willing to chase small format changes to keep free lookups working with the DLL forever. Thus, I strongly recommend that all users convert to using the paid QRZ.COM XML Data Service.

Please Note: K1PGV has no association with, and is not compensated in any way, by QRZ.  I'm considering adding support for other online lookup sources, so feel free to make suggestions.

Click here to Download Online Callbook DLL for MixW V0.14 (1 Jan 2009... yes, it's free)
(see the revision history for this utility at the bottom of the page)

Installation Instructions

Download and unzip the archive using the link above. Make sure MixW is not running.  Place the unzipped file, which is named mixcallbook.dll, into the top-level of your MixW directory (this is typically c:\Program Files\MixW).  You'll know you're in the right directory, because the correct directory contains the file MixW2.exe.

After putting the DLL in the proper directory, you must do two things to enable callbook lookups in MixW:

1. From MixW's menu bar select Configure and then Callbook...  From within the Callbook settings dialog, select MixW custom DLL for callbook type.  Please be sure the Database path field is empty (that is, blank) --  this will cause the DLL to use QRZ's free lookup service.  (If you want to use QRZ's XML Data service, see Using QRZ's XML Data Service, below).
   
   
2. Enable "Auto search in callbook" via MixW's Options menu.  To do this, from MixW's menu bar select Options and then click on Auto search in callbook (as a result, Auto search in callbook should have a check mark next to it).

You must do both of the above things to get callbook lookups to work.

To enable callbook lookups for stations with which you've previously had QSOs, disable (that is uncheck) "Auto search in logfile" in the MixW Options menu.  I recommend you do this for the most consistent behavior -- this will be the setting that most users want.

Enabling (optional) LoTW Lookup Support: To enable optional LoTW lookup support, you need to download the list of known LoTW users from HB9BZA's website. HB9BZA has several versions of the file, so please note carefully: The version you want to download is the version labeled "All known users, for RXCLUS -- Text (1 call/line, no comments)" -- Name the downloaded file lotwusers.dat and put it in the top-level of your MixW directory (the same directory in which you put the mixcallbook.dll file). Be sure to restart MixW after installing the LoTW users file -- The DLL only checks to see if the file exists during MixW startup.  While you're thinking about it, you might want to thank HB9BZA for his efforts by sending him a copy of your LoTW QSL log (see "How To Help" on his website) to contribute to the project.

Using (optional) QRZ's XML Data Service: Skip this section if you want to use the standard free QRZ callsign lookup.  To optionally enable callsign lookups via QRZ's XML Data service, you must have previously paid QRZ for a subscription. To enable online lookups via the QRZ XML Data service, put your username and password in the following format in the Database path field of MixW's Callbook settings dialog:

QRZ:"username/password"

Where:

Please note that the quotation marks are part of the syntax.  You must put quotation marks at the beginning and end of your username and password string, and the username and password must be seprated by a slash character.  No spaces are allowed anywhere in the string.

For example, if your username is K1PGV and your password is Olivia, you sould select Configure and then Callbook... from MixW's menu bar.  Then, you'd setup the callbook settings dialog to look like the following:

Setup for using QRZ XML Data Service (paid) lookups --
For free lookups Database path must be blank

The Callbook DLL will login to online.qrz.com automatically when you perform the first lookup after you've put your username/password in the Database path field.  So, to make sure things are working correctly, after you've configured the K1PGV Callbook DLL with your username and password for the first time, immediately try to lookup a callsign (just enter the callsign in the blank MixW log entry and presss the "tab" key). There will be a slight delay on this first lookup (only) while you're logged into the XML Data service. If the log entry is filled-in with name, QTH, and manager data... it works!  If you get an error message, correct the problem and try again.

Testing Your Installatioin and Diagnosing Problems

The easiest way to test if things are working correctly is to setup the Callbook DLL for free QRZ lookups (be sure the Database path field in the Callbook settings dialog is blank).  Start MixW and enter a callsign into a new log entry (you can just type it in and press the "tab" key), and see if the appropriate fields get automagically filled-in.  Try my call, K1PGV.  Within a couple of seconds, you should get my first name, town and state, grid locator, and some QSL info filled into the Mgr field.  If you've properly set-up LoTW lookup support, you'll see a [L] (that's a capital L in square brackets) as the first three characters in the Mgr field, followed by whatever info I've currently listed in QRZ.COM.  Also note that when you lookup K1PGV, the version number of the callbook DLL that you have installed is filled-in to the "Dom" field (nothing is usually filled-in this field using the free QRZ lookup method, so I decided to use it as a handy place to return the version, but only when you lookup K1PGV).

If you have a problem, try the following steps:

You get the message "QRZ.COM web page format appears to have changed"?  You only get this using the free lookup option.  Try the request again.  You can sometimes get this message if accessing the QRZ.COM web site only returns a partial page (or if QRZ.COM is very slow).  If you get this message consistently, and no lookups succeed, that means the QRZ.COM web page format has almost certainly changed.  Ensure the version of the K1PGV Online Callbook Lookup DLL that you're using is the latest.  If it is, send email to K1PGV and see what an update will be available.

Nothing showing up at all?  Are you sure you put the DLL in the right place?  It should be in the same directory as the file named MixW2.exe.  Is the DLL named correctly?  Note that the correct name is mixcallbook.dll (not mixwcallbook.dll, like you might assume).  Did you enable callbook lookups in the MixW options menu?  Did you select MIxW custom DLL in the Config Callbook menu?  Are you connected to the internet?  Is QRZ.COM current accessible?  Lookups usually take about 2 seconds, but if your internet connection is particularly slow, or if QRZ.COM is very busy, it might take as much as a minute. I actually went for coffee at one point waiting to lookup XT2C during their dxpedition (that's one of the reasons I added support for paid lookups).

Callbook lookups work but LoTW lookups don't work or don't work correctly? Please re-read the instructions and be sure you downloaded the correct version of the file from HB9BZA. Did you name the file correctly?  Note that you need to change the name of the file you download from HB9BZA's website from lotw1.txt (which is what HB9BZA calls it) to lotwusers.dat.  Did you put the file in the right place?  It must be in the same directory as mixcallbook.dll and MixW2.exe.

Callbook lookups work for some items but not for all, or callbook lookups are returning weird, strange, or incorrect data?  Free QRZ lookup support is highly dependent on the format of the QRZ.COM web pages.  If QRZ.COM changes how the callbook lookup web pages are layed out, the DLL may not be able to figure out the new format.  Not having to be dependent on the web page format is one advantage of using the QRZ XML Data Service.  Report the problem (see "Reporting Bugs" below) and check back here for updates.

You can't get lookups to work via the QRZ XML Data service? First, be sure you've got free lookups working.  After that, be sure you're QRZ XML Data Service account is valid.  You can do this by going to http://online.qrz.com/bin/online and logging in.  If that doesn't work, the problem is between you and QRZ.  If you can login to online.qrz.com but the callbook lookups aren't working, be sure that you've supplied the right username and password, in the correct format, in the Database path field of MixW's Callbook options dialog.  The error messages from the K1PGV Callbook DLL should be pretty clear about any login problems.  If you get back a message that says something cryptic, see the section "You've tried everything but..." below.

You get a pop-up message with the dialog box title "baaa"?  Ooops!  You were never supposed to see those.  They were internal debugging messages left in early versions of the DLL.  Download the latest version of the DLL from this page.  Hopefully, the new version will solve whatever problem the "baa" message was attempting to report (and if it doesn't, at least it'll give you a better error message).

You get a pop-up message that includes the phrase "Internal Error"?  Most internal errors are for really weird situations that I don't anticipate every happening.  Retry whatever it is that you were doing when you got the error.  If you still get the error, please carefully note the exact error message text (there's usually a number in the text such as "Internal Error3", and then report the problem to K1PGV.  See "Reporting Bugs" below.

You've tried everything, but you still have a problem and you're completely stumped?  Hey, you're probably not doing anything wrong.  It's more likely that you found a bug in the DLL.  And when you do find a bug, I'd really like to know about it so I can fix it for everyone who uses the DLL.  See "Reporting Bugs" below for how you can let me know you've discovered a problem.

Reporting Bugs:  Send me an email (shown at the bottom of this page) describing the problem or issue that you're having as clearly and in as much detail as possible.  Contrary to prior practice, please do not send problem reports, questions, or comments to the MixW Yahoo group.  They've made it abundantly clear to me that they don't want to see these posts in that group.

Frequently Asked Questions

Why does the DLL return the the country in the QTH field for entities outside the USA? It should return the city!  Yes, I know, sorry.  But I can't fix it -- I've tried. Here's why: For addresses outside the USA, QRZ.COM returns the city, state/province/canton/prefecture, and postal code all together, as one string (yes, this is true even for addresses in Canada). The DLL has to parse this data to extract the city. Given the differences in worldwide address formats (and the way various hams have chosen to enter their addresses into QRZ.COM), I haven't been able to develop a reliable method for parsing the data.  If you have any ideas, feel free to email me.

When I look in the callbook dialog, I see that you return the QTH information in what it labels as the "City" field. Why?   MixW's callbook dialog box incorrectly labels the QTH field as City.  Note that the field in the log book record itself (and the exported ADIF record) is QTH. 

Why don't you return the city in the QTH field and the state/province/canton/prefecture in the "DOM" field?  When I look at the log grid in MixW, I want to see something identifiable in the QTH field.  The city isn't enough for me. In terms of the DOM field, this translates to the ADIF field named STATE.  Starting with K1PGV Online Callbook DLL V0.12, when using the XML Data Service (paid) interface, for US call signs I return the US state in the STATE field and also the county name in the COUNTY field.  For non-US addresses: See the question "Why does the DLL return the country in the QTH field and not the city and/or province/canton/prefecture."

Why do you put the [L] indicating LoTW use in the MGR field? I just have to remove this when I send my log to DxKeeper (or whatever).  Can you put it in the NOTES field instead?  I wish I could, but I can't.  There appears to be a bug or restriction in MixW.  Information returned from a callbook DLL is not copied to the NOTES field.  I've written to Nick/Denis (the guys who write and maintain MixW) about this, but they don't seem to understand or agree that this is a the problem.  Sorry!

K1PGV Online Callbook DLL for MixW Revision History

Comments/Complaints/Questions/Compliments/Suggestions?

Feel free to send me email: