Z39.50 is an international standard computer protocol for exchanging data, including bibliographic records. To be precise, "Z39.50" is actually the standard identified as ISO 23950 or ANSI/NISO Z39.50. The standard specifies a client/server-based protocol for searching and retrieving information (like MARC records) from remote databases. You can find more information from the Library of Congress' Z39.50 home page, http://www.loc.gov/z3950/agency/.

If you have chosen to use Koha with MARC support turned on, Koha includes a Z39.50 client for retrieving MARC records from libraries which maintain a Z39.50 server. The Koha code currently requires that the Event Perl module be installed on the Koha server; since the Event module will not work on Windows or Mac OS X, Koha's Z39.50 search feature is not available when Koha is installed on either of these operating systems. The next version of Koha should correct this deficiency, as it will incorporate next-generation Z39.50 technology. For now, however, the following instructions only apply to Koha installations on Linux/Unix systems.

You start the Z39.50 search process by choosing :"Add biblio" from the "Catalogue" link. This is the first step in any cataloguing chore.

Figure 4.18. Add Biblio first screen

This screen provides you with an opportunity to search your existing catalogue records and any records in your MARC reservoir before you add a new record. The purpose of this initial search is to avoid instances of duplicate records. For example, if you wanted to catalogue a book entitled Spy Catcher, you would enter that title in the "Title" search field and might get a result like this:

Figure 4.19. Add Biblio search result

If nothing in the results screen matches the item you want to catalogue, you can click on the "Add New Biblio" button (and choose a Biblio Framework from the pull-down menu) to proceed to the next step. Likewise, if you are sure the item you want to add to the catalogue does not exist in either your current catalogue or your MARC reservoir, you can skip the search step and click on the "Create Empty Biblio" button on the first Add Biblio screen. Either way, you now come to the cataloging screen for adding a MARC record:

Figure 4.20. Add Biblio cataloging screen

The appearance of this screen is controlled by the Biblio Frameworks that were set up when you defined your Koha parameters. The MARC record may be subdivided across as many as ten different screens, which can be accessed by clicking on the tabs (numbered beginning with "0") along the left side of the page. Above these tabs are two buttons: "Add biblio" (used to add the record to the catalogue when you have finished entering information) and "z3950 search." This second button is the one that we are now going to explain.

The Z39.50 client will search for items by either ISBN, author, or title. An ISBN search will, of course, return the most relevant search results, but the other search methods are provided for items that do not have an ISBN. Let us assume that you now have an new book you want to catalogue -- Donna Tartt's The Little Friend -- and you have already searched your catalogue and come to the screen above for adding a new MARC bibliographic record. To use Z39.50 to search for a record from other libraries, insert the ISBN in the ISBN field and click on the "z3950 search" button:

Figure 4.21. Z39.50 Searching

Notice that the ISBN is entered without any hyphens. Clicking on the "z3950 search" button opens a pop-up window that reports on the progress of the search, beginning by reporting "Still ?? requests to go." As results are found, the "??" will be replaced by the number of Z39.50 servers remaining to be searched, and finally a list of all the retrieved results will be displayed.

Once Koha has searched through the list of Z39.50 servers that were setup in your Koha parameters, the pop-up window will display the search results.

Figure 4.22. Z39.50 Search Results

At this point, all of the retrieved records have been added to your MARC reservoir. You can now choose from the list and click on the "Import this biblio" link next to your choice to automatically use that record to fill in the MARC values on your cataloging screen.

Figure 4.23. Z39.50 Imported Biblio

After editing the MARC bibliographic record to include your local information (such as the Koha Itemtype in our example) and making any other changes, click on the "Add biblio" button to save the MARC record and proceed to entering the item information.

There are two ways to import MARC record (ISO2709) files into your Koha catalogue. One is to upload them into the MARC reservoir and draw them one-by-one from the reservoir into the regular catalogue. This function is accessed through the Parameters page, and is therefore explained in Chapter 1, Section 4.2.

The second way involves running the bulkmarcimport.pl script from a terminal command line, and is therefore harder to use. This second method has the advantage, however, of importing the entire MARC record from the file, while the MARC reservoir upload will only import the MARC tags that are not ignored in your default Biblio Framework. Since this may be important at times, we will look briefly at bulkmarcimport.pl.

First of all, bulkmarcimport.pl is an "extra script," and not part of the "normal" Koha code. It is really intended for special circumstances, but Koha users have found that it can be modified to enable routine uploading of batches of MARC records prepared outside of Koha. In any case, the user must take steps to pass certain information to the script so it can find the rest of the Koha code, particularly the Koha Perl modules. If this is not done, you will get a Can't locate C4/Context.pm in @INC error message, indicating that Perl cannot find the path to your Koha modules in its special @INC variable.

There are two ways to tell Perl how to find the Koha modules: you can either modify the @INC variable in the bulkmarcimport.pl script, or you can set the PERL5LIB and KOHA_CONF environment variables before you run bulkmarcimport.pl.

To modify the @INC variable from within the script, add this line to the list of "use" statements at the beginning of the script:

use lib "/path/to/koha/intranet/modules";

Change /path/to/ to whatever is the actual path to your Koha files.

The method for setting the PERL5LIB and KOHA_CONF environment variables will depend on the shell you are using in your terminal. If you are using bash or a Bourne-style shell, do:

export KOHA_CONF=/path/to/koha.conf
export PERL5LIB=/path/to/koha/intranet/modules

For C-style shells, do:

setenv KOHA_CONF /path/to/koha.conf
setenv PERL5LIB /path/to/koha/intranet/modules

Or if you are using Windows, do:

set KOHA_CONF=c:\path\to\koha.conf
set PERL5LIB=c:\path\to\koha/intranet/modules

Once you have set the variables, you can run the script. Remember, though, that these special environment variable settings will be lost when you close the shell. If you are going to use bulkmarcimport.pl frequently, it is best to add the "use lib" line to the script itself.

The bulkmarcimport.pl script does not do any sophisticated data manipulation; it simply reads an ISO2709 file record by record, puts aside any item (holdings) information, imports the basic bibliographic information, and then adds the item information. If you need to do any manipulation of the ISO2709 records, this should either be done before running the script, or the process of modifying the records can be inserted into the script.

If you invoke the bulkmarcimport.pl script without any options, you get a help message:

[root@localhost migration_tools]# ./bulkmarcimport.pl
small script to import an iso2709 file into Koha.
parameters :
        h : this version/help screen
        file /path/to/file/to/dump : the file to dump
        v : verbose mode. 1 means "some infos", 2 means "MARC dumping"
        n : the number of the record to import. If missing, all the file is imported
        t : test mode : parses the file, saying what he would do, but doing nothing.
        c : the char encoding. At the moment, only MARC21 and UNIMARC supported. MARC21 by default.
        d : delete EVERYTHING related to biblio in koha-DB before import  :tables :
                biblio,                 biblioitems,            subjects,           items
                additionalauthors,      bibliosubtitles,        marc_biblio,
                marc_subfield_table,    marc_word,              marc_blob_subfield
IMPORTANT : don't use this script before you've entered and checked twice (or more) your MARC parameters tables.
If you fail this, the import won't work correctly and you will get invalid datas.

SAMPLE : ./bulkmarcimport.pl -file /home/paul/koha.dev/local/npl -n 1

Be very careful when using the -d option; the script will not warn you that you are about to delete your existing data, it will just do it.

Here is another example of invoking bulkmarcimport.pl:

./bulkmarcimport.pl -d -c UNIMARC --file records.mrc

In this example, we are deleting all of the old data and importing a file of records called records.mrc, which uses UNIMARC character encoding.

(Send comments and remarks to <st.hedges AT gmail DOT com>. They will be added to this section.)