Online Callbook DLL For MixW

Performs on-line callsign lookups from within MixW

10 November 2012 -- Updated to support new QRZ.COM web wite address.

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. 

The data used by this DLL comes from QRZ.COM's XML Logbook Data Service -- This service provides access to a fast, dedicated, port that is specifically designed for doing on-line callsign lookups. There are two levels of service available:

  • Free Access:  Membership in QRZ.COM is free.  Any QRZ member can perform fast, reliable, online lookups using this DLL.  The fields filled-in by this DLL for free access are Name and QTH.  The QTH field is filled-in with the country.  If you configure optional (free) LoTW lookup support, that information is also provided.
  • Paid Access:  This is the premium online lookup service that returns complete data. QRZ.COM charges for this service  For more info, see http://www.qrz.com/XML/index.html  The fields that are filled-in by this DLL when the user has paid access are: Name, QTH, Loc, and Mgr.  For US contacts, the QTH field is filled-in with city and state and the State and County field are also filled-in. For non-US contacts, the QTH field is filled-in with the country.  If you configure optional (free) LoTW lookup support, that information is also provided.

 

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

As of 25 Sept 2009, QRZ.COM implemented a new policy that allows all of its members to perform limited XML-based lookups of callsign data.  This allows all users to benefit from the fast, reliable, lookup service they provide and eliminates the need to parse the QRZ.COM web pages.

QRZ.COM users who do not subscribe to the XML Logbook Data Service can retrieve only name and country.

QRZ.COM uses who are paid subscribers to the XML Logbook Data Service can retrieve full information, as before.

Because of this new feature, and the problems inherent in parsing an ever-changing web page, the K1PGV Online Callbook DLL for MixW no longer supports the traditional free lookup method that required parsing the QRZ.COM web page.  Therefore, to use the K1PGV Online Callbook DLL for MixW, you will need to be a member of QRZ.COM (which is free) and you will need to enter your QRZ.COM username and password in the callbook configuration field of MixW.  See "Configuring QRZ Access" below for configuration information. 

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

Click here to Download Online Callbook DLL for MixW V0.30 (10 November 2012... 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.  See Configuring QRZ Access, below, for more information about what to enter in the Database Path field of MixW's "Callbook Settings" dialog.
  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.

Configuring QRZ Access: This is required for all users.  To enable callsign lookups you must be a member of QRZ.COM and know your username and password.  You may optionally have paid for a subscription to QRZ's XML Logbook Data Service, but this is not required.  To enable online lookups, put your username and password in the following format in the Database path field of MixW's Callbook settings dialog:

QRZ:"username/password"

Where:

username -- is the username with which you've purchased your QRZ subscription.  This is typically your callsign

password
 -- is the password associated with your username.


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 separated 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 should 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 Logbook Data Service lookups --  Required for both free and paid access.

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 Logbook 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.


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 filelotwusers.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.

Testing Your Installation and Diagnosing Problems

Be sure you've entered your QRZ.COM username and password as described above under "Configuring QRZ Access".  This is required for all users, both free and paid.  Next, 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.  If you're using free QRZ.COM access, the QTH field will contain my country.  If you're using paid QRZ.COM support, you'll also see my 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:

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) tolotwusers.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 Logbook Data service? Be sure the username and password you've specified for QRZ.COM access is valid.  You can do this by going to https://secure.qrz.com/subscribe and logging in.  If that doesn't work, the problem is between you and QRZ.  If you can login to 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 paid XML Logbook Data Service 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

Version Number  Changes Implemented
 V0.3 Initial public release
 V0.4-V0.6 Various bug fixes and updates based on user feedback
 V0.8 Complete re-write of QRZ HTML page parsing, to make this parsing less dependent on specific page layout \ Add support for paid QRZ xml-based lookup service \ Add version resource to the DLL (duh!)
V0.9
Fix bug in handling names that start with the same letters as titles (Dr, Ing, etc) \ Do a better job of reporting failures to connect to QRZ.com
 V0.10 Changes to support lookups via the new format of QRZ.COM web pages (which changed on 26/27 August 2007).
 V0.12 Add support for QRZ V2 \ Return US state in STATE field and US county in COUNTY field for those using QRZ XML Data Service only.
 V0.13 Fix a bug, introduced in V0.12 above, that occurred when a callsign has a slash character "/" in it \ In the FREE version (only) when looking-up a callsign with a / suffix, return info for the base callsign (in other words, looking up K1PGV/W9 returns info for K1PGV).  Again, this new feature is only present in the free lookup version.
 V0.14  Fix ANOTHER bug in the new parsing code (ugh!)
 V0.15 Fix another bug in free parsing (for callsigns with no name in QRZ)    
V0.16 Accommodate change in QRZ.COM lookup path \ Quick changes to build in VS 2008    
V0.20 Add support for new free XML access \ Remove QRZ.COM page parsing code.    
V0.23 Swap from http://www.qrz.com/xml to new http://xml.qrz.com/xml to support fastest possible lookups.    
V0.25 Finalize fixes for two latent errors (after extended test with community)    
V0.30 Update to use http://xml.qrz.com for *all* QRZ accesses, including those for login and authentication.    


Comments/Complaints/Questions/Compliments/Suggestions?

Feel free to send me email:

K1PGV's email

Software License and Terms of Use

This software is provided to the community for personal, non-commercial use at no cost, but subject to the terms of the license agreement shown on the downloads page of this web site. Do not download or use any software from this web site unless you fully agree to these terms and conditions.