Amateur Radio Station - Mont Vernon, NH, USA

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
compensatedin
any way, by QRZ. I'd be happy to add support for
other online lookup sources, so feel free to make suggestions.

Installation
Instructions

Download and unzip the archive using the link above. Make sure
MixW is not running. Place the unzipped file, which is
namedmixcallbook.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:

From MixW's menu bar selectConfigureand
thenCallbook... From
within the Callbook settings dialog, selectMixW
custom DLLfor
callbook type. SeeConfiguring
QRZ Access, below, for more information
about what to enter in the Database Path field of MixW's "Callbook
Settings" dialog.

Enable "Auto search in callbook" via MixW's
Options menu. To do this, from MixW's menu bar selectOptionsand
then click onAuto
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 Configureand
thenCallbook...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 fromHB9BZA'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.datand
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 (notmixwcallbook.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 tohttps://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,
pleasedo
notsend
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.