1. ZIG Tutorial San Antonio TX ZETA Perl Module Luca Lelli January 19, 2000l.lelli@finsiel.it

2. Summary ZETA Suite by Finsiel S.p.A. Perl Module description Available Methods Perl Module installation

3. Finsiel Zeta Suite Components Zeta Development Toolkit A Z39.50 development toolkit including ANSI C libraries, Perl Module, command line Client for testing Zeta Target A 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 Proxy a 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 Gateway A 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

4. Client HTTP TCP/IP On development Explain Gateway HTTP-Z39.50 Existing Client Z39.50 access control resource control Z39.50 extended services search & retrieval Inter library loan electronic document delivery union catalog profile Z39.50 OPAC holding profile Integration Finsiel Zeta Suite Services

5. Finsiel Zeta Suite Hw/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

6. 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

7. 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

8. 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

9. 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 error has succeeded); in the latter case $reason contains more detailed information

10. 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"; }

11. 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

12. 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

13. Building Queries The 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"

14. 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.

15. 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.

16. 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.

17. 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.

18. 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.

19. 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”; }

20. 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); }

21. 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;

22. 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.

23. 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"; ………………………..