The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Search-Z3950-0.05
River stage zero No dependents
++
/ Search::Z3950

NAME

Search::Z3950 - Simple Z39.50 searching for ordinary folk

SYNOPSIS

    $z = Search::Z3950->new(
        host => $host,
        port => $port,
        user => $user,
        password => $pwd,
        databaseName => $dbname,
        delay => 0.5,  # half a second
        search_types => [
            {
                name => 'title',
                host => 'z3950.loc.gov',
                port => 7090,
                ... other Z39.50 params here ...
            },
            ...
        ],
    );
    $results = $z->search('title' => 'water method man');
    $numrecs = $results->count();
    for (1..$numrecs) {
        $rec = $results->record($_);
        ...
    }
    ...

DESCRIPTION

Search::Z3950 aims to simplify the coding of Z39.50 clients in Perl by reducing the amount of information the programmer needs to to know about the Z39.50 protocol. (Z39.50 is a standard for information retrieval commonly used by libraries.)

For each Z39.50 server and database (a Z39.50 "service" or "target"), a set of desired search types is written once by someone who knows Z39.50 search syntax and the requirements of the particular service. These search types are typically stored in a configuration file (e.g., the YAML file services.yml included in the Search-Z3950 distribution). All the Perl programmer has to know is the search type's name (e.g., 'author') and whether it accepts multiple-word search strings.

PUBLIC METHODS

new
    $z = Search::Z3950->new(%args);

Construct a new Search::Z3950 object. The following named arguments may be provided:

host

The host name or IP address of the Z39.50 server.

port

(Optional.) The port on which the Z39.50 server listens. The default is 210.

user

If the Z39.50 service requires authentication, you must supply a user name here.

password

If the Z39.50 service requires authentication, you must supply a password here.

databaseName

The name of the database to search. Some Z39.50 services provide access to many different databases, others to only one.

delay

See the description of the delay method below.

search_types

See the description of the search_types method below.

querytype

The type of query you'll be sending (i.e., the search syntax you'll be using). Different Z39.50 services allow for different query types; see the Library of Congress's Z39.50 web site (URL below) for details.

The two query types most likely to be supported are prefix (Prefix Query Notation, a kind of RPN) and ccl (Common Command Language). The query type ccl2rpn may be used to write searches in CCL and have them automatically translated into prefix notation before being sent to the Z39.50 server.

preferredRecordSyntax

The default value is Net::Z3950::RecordSyntax::USMARC() (i.e., 19). Using this default, records are returned (from the results object) as instances of the class MARC::Record.

A whole slew of other arguments may also be provided; these are passed on to the Net::Z3950::Connection object that's created for each service used.

    $results = $z->search('title' => 'rutabaga tales');

Perform a search, connecting to the Z39.50 server the first time it's called. Returns a Search::Z3950::ResultSet.

disconnect
    $z->disconnect;

Disconnect from the Z39.50 server.

host
    $host = $z->host();
    $z->host($host);

Get or set the host.

port
    $port = $z->port();
    $z->port($port);

Get or set the port.

delay
    $delay = $z->delay;
    $z->delay($delay);

Get or set the number of seconds to delay (i.e., sleep) before sending a request. The delay may be specified as an integer or a floating-point number. The delay will be done using Time::HiRes::usleep if it's available; otherwise, sleep is used and the delay is taken as an average.

For example, if the delay is specified as 1.5 seconds and Time::HiRes isn't available, sleep(1) will be called half the time and sleep(2) the other half.

search_types
    $searches = $z->search_types;
    $z->search_types($searches);

Get or set the search types available. The search types are specified as an array of hashes, each of which should have elements name, multiple, templates, and (optionally) description. (Search::Z3950 will ignore any other elements present in the hash.)

The multiple element indicates whether the search string should be broken down into separate search terms when it consists of multiple words (separated by whitespace).

For example, given this set of search types:

    [
        {
            'name' => 'isbn',
            'description' => 'Search by ISBN',
            'multiple' => 0,
            'templates' => ...
        }
        {
            'name' => 'authed',
            'description' => 'Search by author, editor, etc.',
            'multiple' => 1,
            'templates' => ...
        },
    ]

An ISBN search should specify only one ISBN:

    $z->search('isbn' => '0721655342');

While an author/editor search may contain several words:

    $z->search('author' => 'ulysses fishwick');

This latter example would result in a search something like this:

    au=ulysses and au=fishwick

Depending on the search syntax desired, of course.

WARNING: Multiple search terms aren't allowed yet. Trying to do a search that would entail making multiple search terms will result in an exception being thrown.

PREREQUISITES

Net::Z3950 (which in turn requires the yaz toolkit).

FILES

services.yml

This is a YAML file that defines a number of Z39.50 services (also known as "targets"). The Search-Z3950 distribution uses this file only for testing purposes, but you may copy it and adapt it for your own purposes. See the code in t/test-base.pl for an example of how to use it.

NOTE: The fields `name', `abbrev', `location', and `searches' are used only for testing purposes and may be deleted from the copy you make for your own purposes.

BUGS

At this point, Search::Z3950 really doesn't do a very good job of insulating the Perl programmer from Z39.50 details.

TO DO

  • Allow for multiple search terms!

  • Better error checking when connecting.

  • Include a simple client as an example.

  • Make Search::Z3950::Database and Search::Z3950::SearchType modules to simplify the specification of Z39.50 databases and search types?

  • Enable asynchronous operation??

SEE ALSO

Net::Z3950, Search::Z3950::ResultSet.

VERSION

0.05

AUTHOR

Paul Hoffman (nkuitse AT cpan DOT org)

CREDITS

Many thanks to Mike Taylor (mike AT zoom DOT z3950 DOT org) for Net::Z3950, without whom Search::Z3950 wouldn't exist.

The good folks who created the ZOOM abstract API (see http://zoom.z3950.org/), of which Net::Z3950 is a binding.

Index Data of Copenhagen for the yaz toolkit, upon which Net::Z3950 is built.

Finally, thanks to ISO, NISO, and the Library of Congress for the Z39.50 standard (see http://lcweb.loc.gov/z3950/agency/).

COPYRIGHT

Copyright 2003 Paul M. Hoffman. All rights reserved.

This program is free software; you can redistribute it and modify it under the same terms as Perl itself.