1 # $Id: ZOOM.pod,v 1.5 2005-11-16 15:36:16 mike Exp $
8 ZOOM - Perl extension implementing the ZOOM API for Information Retrieval
14 $conn = new ZOOM::Connection($host, $port)
15 $conn->option(preferredRecordSyntax => "usmarc");
16 $rs = $conn->search_pqf('@attr 1=4 dinosaur');
18 print $rs->record(0)->render();
21 print "Error ", $@->code(), ": ", $@->message(), "\n";
26 This module provides a nice, Perlish implementation of the ZOOM
27 Abstract API described and documented at http://zoom.z3950.org/api/
29 the ZOOM module is implemented as a set of thin classes on top of the
30 non-OO functions provided by this distribution's C<Net::Z3950::ZOOM>
32 turn is a thin layer on top of the ZOOM-C code supplied as part of
33 Index Data's YAZ Toolkit. Because ZOOM-C is also the underlying code
34 that implements ZOOM bindings in C++, Visual Basic, Scheme, Ruby, .NET
35 (including C#) and other languages, this Perl module works compatibly
36 with those other implementations. (Of course, the point of a public
37 API such as ZOOM is that all implementations should be compatible
38 anyway; but knowing that the same code is running is reassuring.)
40 The ZOOM module provides two enumerations (C<ZOOM::Error> and
41 C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
42 package itself, and eight classes:
52 Of these, the Query class is abstract, and has two concrete
57 Many useful ZOOM applications can be built using only the Connection,
58 ResultSet, Record and Exception classes, as in the example
61 A typical application will begin by creating an Connection object,
62 then using that to execute searches that yield ResultSet objects, then
63 fetching records from the result-sets to yield Record objects. If an
64 error occurs, an Exception object is thrown and can be dealt with.
66 More sophisticated applications might also browse the server's indexes
67 to create a ScanSet, from which indexed terms may be retrieved; others
68 might send ``Extended Services'' Packages to the server, to achieve
69 non-standard tasks such as database creation and record update.
70 Searching using a query syntax other than PQF can be done using an
71 query object of one of the Query subclasses. Finally, sets of options
72 may be manipulated independently of the objects they are associated
73 with using an Options object.
75 In general, method calls throw an exception if anything goes wrong, so
76 you don't need to test for success after each call. See the section
77 below on the Exception class for details.
79 =head1 UTILITY FUNCTION
81 =head2 ZOOM::diag_str()
83 $msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);
85 Returns a human-readable English-language string corresponding to the
86 error code that is its own parameter. This works for any error-code
88 C<ZOOM::Exception::code()>,
89 C<ZOOM::Connection::error_x()>
91 C<ZOOM::Connection::errcode()>,
92 irrespective of whether it is a member of the C<ZOOM::Error>
93 enumeration or drawn from the BIB-1 diagnostic set.
97 The eight ZOOM classes are described here in ``sensible order'':
98 first, the four commonly used classes, in the he order that they will
99 tend to be used in most programs (Connection, ResultSet, Record,
100 Exception); then the four more esoteric classes in descending order of
101 how often they are needed.
103 With the exception of the Options class, which is an extension to the
104 ZOOM model, the introduction to each class includes a link to the
105 relevant section of the ZOOM Abstract API.
107 =head2 ZOOM::Connection
109 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
110 print("server is '", $conn->option("serverImplementationName"), "'\n");
111 $conn->option(preferredRecordSyntax => "usmarc");
112 $conn->option_binary(iconBlob => "foo\0bar");
113 $rs = $conn->search_pqf('@attr 1=4 mineral');/usr/local/src/mike/records/acc-ounts/cheques-
114 $ss = $conn->scan('@attr 1=1003 a');
115 if ($conn->errcode() != 0) {
116 die("somthing went wrong: " . $conn->errmsg())
120 This class represents a connection to an information retrieval server,
121 using an IR protocol such as ANSI/NISO Z39.50, SRW (the
122 Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
123 OpenSearch. Not all of these protocols require a low-level connection
124 to be maintained, but the Connection object nevertheless provides a
125 location for the necessary cache of configuration and state
126 information, as well as a uniform API to the connection-oriented
127 facilities (searching, index browsing, etc.), provided by these
130 See the description of the C<Connection> class in the ZOOM Abstract
132 http://zoom.z3950.org/api/zoom-current.html#3.2
138 $conn = new ZOOM::Connection("indexdata.dk", 210);
139 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
140 $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
141 $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
143 Creates a new Connection object, and immediately connects it to the
144 specified server. If you want to make a new Connection object but
145 delay forging the connection, use the C<create()> and C<connect()>
148 This constructor can be called with two arguments or a single
149 argument. In the former case, the arguments are the name and port
150 number of the Z39.50 server to connect to; in the latter case, the
151 single argument is a YAZ service-specifier string of the form
157 [I<scheme>:]I<host>[:I<port>][/I<databaseName>]
161 In which the I<host> and I<port> parts are as in the two-argument
162 form, the I<databaseName> if provided specifies the name of the
163 database to be used in subsequent searches on this connection, and the
164 optional I<scheme> (default C<tcp>) indicates what protocol should be
165 used. At present, the following schemes are supported:
175 Z39.50 connection encrypted using SSL (Secure Sockets Layer). Not
176 many servers support this, but Index Data's Zebra is one that does.
180 Z39.50 connection on a Unix-domain (local) socket, in which case the
181 I<hostname> portion of the string is instead used as a filename in the
186 SRW connection using SOAP over HTTP.
190 Support for SRU will follow in the fullness of time.
196 =head4 error_x() / errcode() / errmsg() / addinfo()
198 =head4 option() / option_binary()
200 =head4 search() / search_pqf()
208 =head2 ZOOM::ResultSet
216 =head2 ZOOM::Exception
218 In general, method calls throw an exception (of class
219 C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
220 for success after each call. Exceptions are caught by enclosing the
221 main code in an C<eval{}> block and checking C<$@> on exit from that
222 block, as in the code-sample above.
224 There are a small number of exceptions to this rule.
245 The ZOOM module provides two enumerations that list possible return
246 values from particular functions. They are described in the following
251 if ($@->code() == ZOOM::Error::QUERY_PQF) {
252 return "your query was not accepted";
255 This class provides a set of manifest constants representing some of
256 the possible error codes that can be raised by the ZOOM module. The
257 methods that return error-codes are
258 C<ZOOM::Exception::code()>,
259 C<ZOOM::Connection::error_x()>
261 C<ZOOM::Connection::errcode()>.
263 The C<ZOOM::Error> class provides the constants
273 C<UNSUPPORTED_PROTOCOL>,
274 C<UNSUPPORTED_QUERY>,
283 each of which specifies a client-side error. Since errors may also be
284 diagnosed by the server, and returned to the client, error codes may
285 also take values from the BIB-1 diagnostic set of Z39.50, listed at
286 the Z39.50 Maintenance Agency's web-site at
287 http://www.loc.gov/z3950/agency/defns/bib1diag.html
289 All error-codes, whether client-side from the C<ZOOM::Error>
290 enumeration or server-side from the BIB-1 diagnostic set, can be
291 translated into human-readable messages by passing them to the
292 C<ZOOM::diag_str()> utility function.
296 if ($conn->last_event() == ZOOM::Event::CONNECT) {
297 print "Connected!\n";
300 In applications that need it - mostly complex multiplexing
301 applications - The C<ZOOM::Connection::last_event()> method is used to
302 return an indication of the last event that occurred on a particular
303 connection. It always returns a value drawn from this enumeration,
304 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
305 C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
308 You almost certainly don't need to know about this. Frankly, I'm not
309 sure how to use it myself.
313 The ZOOM abstract API,
314 http://zoom.z3950.org/api/zoom-current.html
316 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
318 The C<Net::Z3950> module, which this one supersedes.
320 The documentation for the ZOOM-C module of the YAZ Toolkit, which this
321 module is built on. Specifically, its lists of options are useful.
322 http://indexdata.com/yaz/doc/zoom.tkl
324 The BIB-1 diagnostic set of Z39.50,
325 http://www.loc.gov/z3950/agency/defns/bib1diag.html
329 Mike Taylor, E<lt>mike@indexdata.comE<gt>
331 =head1 COPYRIGHT AND LICENCE
333 Copyright (C) 2005 by Index Data.
335 This library is free software; you can redistribute it and/or modify
336 it under the same terms as Perl itself, either Perl version 5.8.4 or,
337 at your option, any later version of Perl 5 you may have available.