Technology tips, tricks, and tidbits from a Systems Librarian

Tag Archives: Zebra

If you have technical experience in libraries, you’ve probably heard of Z39.50 (https://en.wikipedia.org/wiki/Z39.50). It’s an old standard, but it’s something libraries still use.

Koha, the open source ILS/LMS, uses Indexdata’s Zebra as its search engine, and it communicates with it using Z39.50 to fetch records in MARC format (another old standard still in use).

MarcEdit is a program used for editing MARC records, and it integrates with some of Koha’s HTTP APIs for adding and updating bibliographic MARC records. It also uses Zebra for searching Koha’s database of MARC records.

I was reading Koha’s listserv when I encountered someone having troubles connecting to Zebra from MarcEdit. I had the same troubles years ago, so I decided to give it another shot now that I’m a lot more experienced with Koha, Zebra, Z39.50, MARC, networking, and really all things IT.

I followed the instructions in the Koha file for exposing Zebra over TCP, but MarcEdit was still failing to connect. Unfortunately, it didn’t really give me any useful information about why it was failing. So I decided to download a Z39.50 client and see if I could get down lower and see what was happening under the hood.

I’ve been using yaz-client (http://www.indexdata.com/yaz/doc/yaz-client.html) for years, as it comes bundled with the YAZ libraries used by Zebra. However, I’ve always been using it on the Linux servers running Koha. In this case, I wanted to connect from my Windows desktop…

I still couldn’t connect to Zebra using yaz-client.exe, but now it was clear that it was a connection problem.

I tried using yaz-client on the Linux server that hosted Zebra, and it worked fine. It was clearly a networking issue… the default TCP port for Zebra (ie 9998) was probably being blocked by my network router. So I looked around for a free port using ‘netstat -ln | grep “3000”‘. Port 3000 wasn’t being used by anything else, so I changed the Zebra configuration, restarted my Zebra server, and tried to connect to Zebra using yaz-client.exe on Windows again.

This time the client connected successfully and I had anonymous read-only access to Zebra!

In hindsight, I should have tried port 210 which is the official port for Z39.50 communications or port 7090 which is also sometimes used for Z39.50 servers. But this was good enough for my temporary experiment. I tried again in MarcEdit, and it worked! I was now able to search for records in Koha, download them as MARC21, edit them in MarcEdit, and then update them in Koha using one of Koha’s HTTP APIs!

Now, I was connecting over a private local network. If you were to forward that port on your router so that it was Internet accessible, I would highly recommend changing the default username and password for Zebra!

Anyway, even if you’re not using Koha or MarcEdit or Zebra, you can still use yaz-client on Linux and yaz-client.exe on Windows to connect to all sorts of other Z39.50 servers like the ones at the Library of Congress, LibrariesAustralia, the National Library of Australia, and so on.

This can be useful when you’re trying to troubleshoot Z39.50 connection issues or if you just want to have more control over your Z39.50 requests than what you have baked into your ILS/LMS. Maybe you’re trying to fetch a record from the Library of Congress and you know it’s there… but your ILS/LMS doesn’t seem able to find it. Whip out yaz-client and check it out yourself!

Bib1.att lists and maps bib-1 attributes (default from the library of congress spec and special added ones for Koha)
Ccl.properties maps CCL to BIB1/PQF
Record.abs maps MARC fields to BIB1

Also, since it’s really hard to find information about how to construct PQF queries using BIB1…

There are 6 types of Bib-1 attributes. Each type has a variety of codes within that type. To create a query, you would type something like the following into Yaz or whatever else you’re using that utilizes PQF:

f @attr 1=4 computer

f stands for find in yaz

@attr stands for attribute (you need to write one of these for each attribute you’re creating)
1=4 stands for type 1: use attributes with a code of 4 for title
1=4 -> use attribute=title

It’s actually quite straightforward, but it’s quite rare to find it spelled out for you on the Web!