ZIG Tutorial San Antonio TX

ZETA Perl ModuleZETA Perl Module

Luca LelliLuca Lelli

January 19, 2000 l.lelli@finsiel.it

Summary

• ZETA Suite by Finsiel S.p.A.

• Perl Module description

• Available Methods

• Perl Module installation

Finsiel Zeta SuiteComponents

• Zeta Development ToolkitA Z39.50 development toolkit including ANSI C libraries, Perl Module, command line Client for testing

• Zeta TargetA powerful Z39.50 server able to interface a large set of commercial DBMS/IRS with the catalogues. It supports Z39.50 V3 functionalities like: init, search, present, delete, close, scan, sort and item order

• Zeta Proxya fast and efficient intermediary between Z39.50 compliant clients and the Z39.50 Servers. It allows to perform parallel queries on multi-profiles targets

• HTTP/Z39.50 GatewayA lot of perl scripts able to tranform stateless http sessions in stateful z39.50 sessions

• Z39.50 Client A standalone Z39.50 Client for Windows environment

Client HTTP

TCP/IP

On development

Exp

lainGateway

HTTP-Z39.50

Existing

ClientZ39.50

access control

resource con

trol

Z39.50extended services

search &retrieval

Interlibrary

loan

electronicdocumentdelivery

unioncatalogprofile

Z39.50OPACholdingprofile

Integration

Finsiel Zeta SuiteServices

Finsiel Zeta SuiteHw/Sw Platforms

• Hardware/Operating System– Un*x (Solaris, Linux, HP-UX, AIX, IRIX, OSF)

– Microsoft Windows 95, 98, NT-4.0

• DBMS/IRS ZETA Target Drivers– Basis Plus 8.2

– MySQL 3.22 & Postgres 6.2

– Informix Dynamic Server (IDS) 9.13

– Fulcrum Search Server 7.x

– Any ODBC Compliant DBMS

Zeta on the Public Domain

• Zeta Perl: a module to facilitate implementation of Z39.50 client applications using the Perl language (i.e. Web Gateways, robots, …)

• Ziffy: Z39.50 APDUs sniffer. It can be used to ‘sniff’ the communication between Z39.50 peers and make human-readable the exchanged information

Available ...

Coming soon ...

• Zeta Robot: a Perl application for testing and inspecting Z39.50 server on the network. Particularly useful to check the conformance to the standard

• Zeta Gateway Generator: based on the Zeta Perl it facilitates creation and customization of HTTP/Z39.50 gateways

Zeta Perl Module

Home page at

http://zeta.tlcpi.finsiel.it/z3950/zetaperl/

• Released under GNU/GPL

• Simple access to Z39.50 V3 services via Perl 5 scripts

Functionalities

• It implements a client interface to Z39.50 V3 protocol, enabling perl applications to easily talk to Z39.50 servers

• Basic Z39.50 operations are offered to the perl programmers through an object oriented interface

• All operations are currently synchronous• It supports multi-associations at the same time• The primary object is Zeta::Connection which is

implemented as a blessed hash reference

Available Methods

• Init

• Search

• Present

• Close

• Delete

• Scan

• Sort

All methods put in the output $status variable (boolean)the result of the operation (1 for OK, 0 if an errorhas succeeded); in the latter case $reason containsmore detailed information

Simple Connection$Host = ”somehost.your.domain";

$Port = 210; # NISO Z39.50 database

$zc = Zeta::Connection::New ($Host, $Port);

if ($zc)

{

print "Connection established";

}

else

{

print "Connection failed";

}

Init$user = ‘’;

$passwd=“”;

$refid = “”;

($status, $reason, $result, $newid) =

$zc->Init ($user, $passwd, $refid);

It sends a request to the server to initialize the previously established connection identified by $zc. The first two parameters are optional and they can be used to transmit authentication information in case the target applies. The optional parameter $refid can be used to reference the association

Search$database=“opac”; $resultset=“zeta”;

$query=“1=4 dante @or@ 1=4 manzoni”; $attrid=“BIB1”;

($status, $reason, $found, $info) =

$zc->Search ($database, $resultset, $query, $attrid);

It sends a request to the server to perform the Z39.50 Type 1 query specified by $query. $database identifies the name of database. $resultset indicates the name to give to the query result, while $query is the query string (see below.) The last parameter $attrid indicates an attribute set

identifier associated to the query.Upon successful completion $found contains the number of hits of the created resultset

Building QueriesThe Perl module recognizes all the query strings constructed according to

the general definition:

$query = term1 operator term2, where

term = "AttributeType=AttributeValue Term”

operator = @and@ | @or@ | @andnot@

Terms can be grouped using parenthesis.

The string is converted in RPN Type-1 query according to Z39.50 definition. For example, if you want to search a term, say "Dante", in the

title field of your database, you must construct your query as follows:

$query = "1=4 Dante"

Present$resultset=“zeta”; $howmany=33;

$start=4; $format=“b”; $syntax=“grs1”;

($status, $reason, $returned, @records) =

$zc->Present ($resultset, $howmany, $start, $format, $syntax);

It tries to retrieve records from a previously created resultset. $howmany is the number of records to be retrieved, while $start is the start point.

$format indicates the Element Set Name (`b' for brief, `mb' for museum brief, `f' for full, etc.), and $syntax indicates the preferred record syntax (MARC, GRS-1). Upon successful completion @records contains the array of records returned.

Delete

$function=1;

$resultset=“zeta”;

($status, $reason) = $zc->Delete ($function, $resultset);

It sends a request to the server for deleting a particular $resultset, or all

resultsets previously created. If $function is set to 1 the operation will try to delete only $resultset. The value 2 should be used to delete all.

Close$code=1;

($status, $reason) = $zc->Close ($code);

It sends a request to the server in order to close a previously established

association. It does not check for any state information, therefore it may

be called at any time to communicate that the user is finished with the

Z39.50 association. $code is the reason code of the disconnection.

Scan

$database=“opac”; $term=“1=4 dan”;

$itemsno=50; $start=3;

($status, $reason, $returned, @entries) =

$zc->Scan ($database, $term, $itemsno, $start)

It sends a request to the server to scan an ordered term-list. $database

is the name of database and $term is the scan term with the same syntax of the Search method. $itemsno is the maximum number of items to retrieve and $start is the start point. Upon successful completion @entries contains the array of entries returned.

Sort

$resultset=“zeta”;

$criteria=“1=4”;

($status, $reason) = $zc->Sort ($resultset, $criteria)

It sends a request to the server for sorting a previously created $resultset.

$criteria indicates the sort sequences criteria.

An Example (1)#

# establish a connection with a Z39.50 Target over TCP/IP

#

$zc = Zeta::Connection::New ($target, $port);

if (! $zc)

{

die "\t<<-- Connection to $target:$port failed\n"

}

else

{

#

# initialize the association

#

($status, $reason, $result, $newrefid) =

$zc->Init ($user, $password, $refid);

if (! $status)

{

die "\t<<-- Init for user [$user/$password with reference id = $refid] failed due to $reason\n";

}

elsif (! $result)

{

die "\t<<-- Target rejected the request\n”;

}

An Example (2) # # try to create a result set # ($status, $reason, $found, $info) = $zc->Search ($database, $resultset, $query, $attrsetid); if (! $status) { die "\t<<-- Search failed due to $reason\n"; } else { print "\t<<-- $resultset created containing $found records\n”; } à # try to sort the result set previuosly created # ($status, $reason) = $zc->Sort ($resultset, $criteria); if (! $status) {

die "\t<<-- Sort failed due to $reason\n"; } else { print "\t<<-- Sort completed\n"; } # # close the association # ($status, $reason) = $zc->Close ($close);}

Installation and Use

To install Zeta Perl module, just change to the directory in which the Makefile.PL file is found and type the following:

# perl Makefile.PL

# make

# make install

you can load the Zeta Perl routines in your Perl scripts with the line:

use Zeta;

Need Testing first?Before or after you install this module, you can perform some tests to check the whole functionalities of the module with the following command:

# make test

However, in order to test the integrity and functionalities of the module you need to have a reachable z3950 target in somewhere on the net. The system wide configuration file, zetaperlrc, which comes with the package, contains default values for testing.

zetaperlrc• #• # You need to provide a reachable z39.50 target.• # Its name can be provided as a valid hostname or its IP address.• #• $target = "www.promemoria.net";• #• # Give here the port number of the target• #• $port = "2222";• #• # Database name• #• $database = "test";• #• # Resultset name• #• $resultset = "zeta";• #• # You need to provide a simple query in order to test• # the search and present methods.• # Your query must create a non empty result set.• #• $query = "1=1016 legno";

• ………………………..