1 # $Id: ZOOM.pod,v 1.19 2005-12-13 15:30:26 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 $rs = $conn->search_pqf('@attr 1=4 mineral');
113 $ss = $conn->scan('@attr 1=1003 a');
114 if ($conn->errcode() != 0) {
115 die("somthing went wrong: " . $conn->errmsg())
119 This class represents a connection to an information retrieval server,
120 using an IR protocol such as ANSI/NISO Z39.50, SRW (the
121 Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
122 OpenSearch. Not all of these protocols require a low-level connection
123 to be maintained, but the Connection object nevertheless provides a
124 location for the necessary cache of configuration and state
125 information, as well as a uniform API to the connection-oriented
126 facilities (searching, index browsing, etc.), provided by these
129 See the description of the C<Connection> class in the ZOOM Abstract
131 http://zoom.z3950.org/api/zoom-current.html#3.2
137 $conn = new ZOOM::Connection("indexdata.dk", 210);
138 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
139 $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
140 $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
142 Creates a new Connection object, and immediately connects it to the
143 specified server. If you want to make a new Connection object but
144 delay forging the connection, use the C<create()> and C<connect()>
147 This constructor can be called with two arguments or a single
148 argument. In the former case, the arguments are the name and port
149 number of the Z39.50 server to connect to; in the latter case, the
150 single argument is a YAZ service-specifier string of the form
156 [I<scheme>:]I<host>[:I<port>][/I<databaseName>]
160 In which the I<host> and I<port> parts are as in the two-argument
161 form, the I<databaseName> if provided specifies the name of the
162 database to be used in subsequent searches on this connection, and the
163 optional I<scheme> (default C<tcp>) indicates what protocol should be
164 used. At present, the following schemes are supported:
174 Z39.50 connection encrypted using SSL (Secure Sockets Layer). Not
175 many servers support this, but Index Data's Zebra is one that does.
179 Z39.50 connection on a Unix-domain (local) socket, in which case the
180 I<hostname> portion of the string is instead used as a filename in the
185 SRW connection using SOAP over HTTP.
189 Support for SRU will follow in the fullness of time.
191 If an error occurs, an exception is thrown. This may indicate a
192 networking problem (e.g. the host is not found or unreachable), or a
193 protocol-level problem (e.g. a Z39.50 server rejected the Init
196 =head4 create() / connect()
198 $options = new ZOOM::Options();
199 $options->option(implementationName => "my client");
200 $conn = create ZOOM::Connection($options)
201 $conn->connect($host, 0);
203 The usual Connection constructor, C<new()> brings a new object into
204 existence and forges the connection to the server all in one
205 operation, which is often what you want. For applications that need
206 more control, however, these two method separate the two steps,
207 allowing additional steps in between such as the setting of options.
209 C<create()> creates and returns a new Connection object, which is
210 I<not> connected to any server. It may be passed an options block, of
211 type C<ZOOM::Options> (see below), into which options may be set
212 before or after the creation of the Connection. The connection to the
213 server may then be forged by the C<connect()> method, the arguments of
214 which are the same as those of the C<new()> constructor.
216 =head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
218 ($errcode, $errmsg, $addinfo, $diagset) = $conn->error_x();
219 $errcode = $conn->errcode();
220 $errmsg = $conn->errmsg();
221 $addinfo = $conn->addinfo();
222 $diagset = $conn->diagset();
224 These methods may be used to obtain information about the last error
225 to have occurred on a connection - although typically they will not
226 been used, as the same information is available through the
227 C<ZOOM::Exception> that is thrown when the error occurs. The
233 methods each return one element of the diagnostic, and
235 returns all four at once.
237 See the C<ZOOM::Exception> for the interpretation of these elements.
239 =head4 option() / option_binary()
241 print("server is '", $conn->option("serverImplementationName"), "'\n");
242 $conn->option(preferredRecordSyntax => "usmarc");
243 $conn->option_binary(iconBlob => "foo\0bar");
244 die if length($conn->option_binary("iconBlob") != 7);
246 Objects of the Connection, ResultSet, ScanSet and Package classes
247 carry with them a set of named options which affect their behaviour in
248 certain ways. See the ZOOM-C options documentation for details:
250 Connection options are listed at
251 http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
253 These options are set and fetched using the C<option()> method, which
254 may be called with either one or two arguments. In the two-argument
255 form, the option named by the first argument is set to the value of
256 the second argument, and its old value is returned. In the
257 one-argument form, the value of the specified option is returned.
259 For historical reasons, option values are not binary-clean, so that a
260 value containing a NUL byte will be returned in truncated form. The
261 C<option_binary()> method behaves identically to C<option()> except
262 that it is binary-clean, so that values containing NUL bytes are set
263 and returned correctly.
265 =head4 search() / search_pqf()
267 $rs = $conn->search(new ZOOM::Query::CQL('title=dinosaur'));
268 # The next two lines are equivalent
269 $rs = $conn->search(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
270 $rs = $conn->search_pqf('@attr 1=4 dinosaur');
272 The principal purpose of a search-and-retrieve protocol is searching
273 (and, er, retrieval), so the principal method used on a Connection
274 object is C<search()>. It accepts a single argument, a C<ZOOM::Query>
275 object (or, more precisely, an object of a subclass of this class);
276 and it creates and returns a new ResultSet object representing the set
277 of records resulting from the search.
279 Since queries using PQF (Prefix Query Format) are so common, we make
280 them a special case by providing a C<search_prefix()> method. This is
281 identical to C<search()> except that it accepts a string containing
282 the query rather than an object, thereby obviating the need to create
283 a C<ZOOM::Query::PQF> object. See the documentation of that class for
284 information about PQF.
288 Many Z39.50 servers allow you to browse their indexes to find terms to
289 search for. This is done using the C<scan> method, which creates and
290 returns a new ScanSet object representing the set of terms resulting
293 C<scan()> takes a single argument, but it has to work hard: it
294 specifies both what index to scan for terms, and where in the index to
295 start scanning. What's more, the specification of what index to scan
296 includes multiple facets, such as what database fields it's an index
297 of (author, subject, title, etc.) and whether to scan for whole fields
298 or single words (e.g. the title ``I<The Empire Strikes Back>'', or the
299 four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved
300 with words from other titles in the same index.
302 All of this is done by using a single term from the PQF query as the
303 C<scan()> argument. (At present, only PQF is supported, although
304 there is no reason in principle why CQL and other query syntaxes
305 should not be supported in future). The attributes associated with
306 the term indicate which index is to be used, and the term itself
307 indicates the point in the index at which to start the scan. For
308 example, if the argument is C<@attr 1=4 fish>, then
314 This is the BIB-1 attribute with type 1 (meaning access-point, which
315 specifies an index), and type 4 (which means ``title''). So the scan
316 is in the title index.
320 Start the scan from the lexicographically earliest term that is equal
321 to or falls after ``fish''.
325 The argument C<@attr 1=4 @attr 6=3 fish> would behave similarly; but
326 the BIB-1 attribute 6=3 mean completeness=``complete field'', so the
327 scan would be for complete titles rather than for words occurring in
330 This takes a bit of getting used to.
332 The behaviour is C<scan()> is affected by the following options, which
333 may be set on the Connection through which the scan is done:
337 =item number [default: 10]
339 Indicates how many terms should be returned in the ScanSet. The
340 number actually returned may be less, if the start-point is near the
341 end of the index, but will not be greater.
343 =item position [default: 1]
345 A 1-based index specifying where in the returned list of terms the
346 seed-term should appear. By default it should be the first term
347 returned, but C<position> may be set, for example, to zero (requesting
348 the next terms I<after> the seed-term), or to the same value as
349 C<number> (requesting the index terms I<before> the seed term).
351 =item stepSize [default: 0]
353 An integer indicating how many indexed terms are to be skipped between
354 each one returned in the ScanSet. By default, no terms are skipped,
355 but overriding this can be useful to get a high-level overview of the
362 $p = $conn->package();
363 $o = new ZOOM::Options();
364 $o->option(databaseName => "newdb");
365 $p = $conn->package($o);
367 Creates and returns a new C<ZOOM::Package>, to be used in invoking an
368 Extended Service. An options block may optionally be passed in. See
369 the C<ZOOM::Package> documentation.
375 Destroys a Connection object, tearing down any low-level connection
376 associated with it and freeing its resources. It is an error to reuse
377 a Connection that has been C<destroy()>ed.
379 =head2 ZOOM::ResultSet
381 $rs = $conn->search_pqf('@attr 1=4 mineral');
384 $rec = $rs->record($i-1);
385 print $rec->render();
388 A ResultSet object represents the set of zero or more records
389 resulting from a search, and is the means whereby these records can be
390 retrieved. A ResultSet object may maintain client side cache or some,
391 less, none, all or more of the server's records: in general, this is
392 supposed to an implementaton detail of no interest to a typical
393 application, although more sophisticated applications do have
394 facilities for messing with the cache. Most applications will only
395 need the C<size()>, C<record()> and C<sort()> methods.
397 There is no C<new()> method nor any other explicit constructor. The
398 only way to create a new ResultSet is by using C<search()> (or
399 C<search_prefix()>) on a Connection.
401 See the description of the C<Result Set> class in the ZOOM Abstract
403 http://zoom.z3950.org/api/zoom-current.html#3.4
409 $rs->option(elementSetName => "f");
411 Allows options to be set into, and read from, a ResultSet, just like
412 the Connection class's C<option()> method. There is no
413 C<option_binary()> method for ResultSet objects.
415 ResultSet options are listed at
416 http://indexdata.com/yaz/doc/zoom.resultsets.tkl
420 print "Found ", $rs->size(), " records\n";
422 Returns the number of records in the result set.
424 =head4 record() / record_immediate()
426 $rec = $rs->record(0);
427 $rec2 = $rs->record_immediate(0);
428 $rec3 = $rs->record_immediate(1)
429 or print "second record wasn't in cache\n";
431 The C<record()> method returns a C<ZOOM::Record> object representing
432 a record from result-set, whose position is indicated by the argument
433 passed in. This is a zero-based index, so that legitimate values
434 range from zero to C<$rs->size()-1>.
436 The C<record_immediate()> API is identical, but it never invokes a
437 network operation, merely returning the record from the ResultSet's
438 cache if it's already there, or an undefined value otherwise. So if
439 you use this method, B<you must always check the return value>.
443 $rs->records(0, 10, 0);
445 print $rs->record_immediate($i)->render();
448 @nextseven = $rs->records(10, 7, 1);
450 The C<record_immediate()> method only fetches records from the cache,
451 whereas C<record()> fetches them from the server if they have not
452 already been cached; but the ZOOM module has to guess what the most
453 efficient strategy for this is. It might fetch each record, alone
454 when asked for: that's optimal in an application that's only
455 interested in the top hit from each search, but pessimal for one that
456 wants to display a whole list of results. Conversely, the software's
457 strategy might be always to ask for blocks of a twenty records:
458 that's great for assembling long lists of things, but wasteful when
459 only one record is wanted. The problem is that the ZOOM module can't
460 tell, when you call C<$rs->record()>, what your intention is.
462 But you can tell it. The C<records()> method fetches a sequence of
463 records, all in one go. It takes three arguments: the first is the
464 zero-based index of the first record in the sequence, the second is
465 the number of records to fetch, and the third is a boolean indication
466 of whether or not to return the retrieved records as well as adding
467 them to the cache. (You can always pass 1 for this if you like, and
468 Perl will discard the unused return value, but there is a small
469 efficiency gain to be had by passing 0.)
471 Once the records have been retrieved from the server
472 (i.e. C<records()> has completed without throwing an exception), they
473 can be fetched much more efficiently using C<record()> - or
474 C<record_immediate()>, which is then guaranteed to succeed.
480 Resets the ResultSet's record cache, so that subsequent invocations of
481 C<record_immediate()> will fail. I struggle to imagine a real
482 scenario where you'd want to do this.
486 if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) {
490 Sorts the ResultSet in place (discarding any cached records, as they
491 will in general be sorted into a different position). There are two
492 arguments: the first is a string indicating the type of the
493 sort-specification, and the second is the specification itself.
495 The C<sort()> method returns 0 on success, or -1 if the
496 sort-specification is invalid.
498 At present, the only supported sort-specification type is C<yaz>.
499 Such a specification consists of a space-separated sequence of keys,
500 each of which itself consists of two space-separated words (so that
501 the total number of words in the sort-specification is even). The two
502 words making up each key are a field and a set of flags. The field
503 can take one of two forms: if it contains an C<=> sign, then it is a
504 BIB-1 I<type>=I<value> pair specifying which field to sort
505 (e.g. C<1=4> for a title sort); otherwise it is sent for the server to
506 interpret as best it can. The word of flags is made up from one or
507 more of the following: C<s> for case sensitive, C<i> for case
508 insensitive; C<<> for ascending order and C<E<gt>> for descending
511 For example, the sort-specification in the code-fragment above will
512 sort the records in C<$rs> case-insensitively in descending order of
513 title, with records having equivalent titles sorted case-sensitively
514 in ascending order of subject. (The BIB-1 access points 4 and 21
515 represent title and subject respectively.)
521 Destroys a ResultSet object, freeing its resources. It is an error to
522 reuse a ResultSet that has been C<destroy()>ed.
526 $rec = $rs->record($i);
527 print $rec->render();
529 $marc = new_from_usmarc MARC::Record($raw);
530 print "Record title is: ", $marc->title(), "\n";
532 A Record object represents a record that has been retrived from the
535 There is no C<new()> method nor any other explicit constructor. The
536 only way to create a new Record is by using C<record()> (or
537 C<record_immediate()>, or C<records()>) on a ResultSet.
539 In general, records are ``owned'' by their result-sets that they were
540 retrieved from, so they do not have to be explicitly memory-managed:
541 they are deallocated (and therefore can no longer be used) when the
542 result-set is destroyed.
544 See the description of the C<Record> class in the ZOOM Abstract
546 http://zoom.z3950.org/api/zoom-current.html#3.5
554 Returns a human-readable representation of the record. Beyond that,
555 no promises are made: careful programs should not make assumptions
556 about the format of the returned string.
558 This method is useful mostly for debugging.
564 $marc = new_from_usmarc MARC::Record($raw);
566 Returns an opaque blob of data that is the raw form of the record.
567 Exactly what this is, and what you can do with it, varies depending on
568 the record-syntax. For example, XML records will be returned as,
569 well, XML; MARC records will be returned as ISO 2709-encoded blocks
570 that can be decoded by software such as the fine C<Marc::Record>
571 module; GRS-1 record will be ... gosh, what an interesting question.
572 But no-one uses GRS-1 any more, do they?
574 =head4 clone() / destroy()
576 $rec = $rs->record($i);
577 $newrec = $rec->clone();
579 print $newrec->render();
582 Usually, it's convenient that Record objects are owned by their
583 ResultSets and go away when the ResultSet is destroyed; but
584 occasionally you need a Record to outlive its parent and destroy it
585 later, explicitly. To do this, C<clone()> the record, keep the new
586 Record object that is returned, and C<destroy()> it when it's no
587 longer needed. This is B<only> situation in which a Record needs to
590 =head2 ZOOM::Exception
592 In general, method calls throw an exception (of class
593 C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
594 for success after each call. Exceptions are caught by enclosing the
595 main code in an C<eval{}> block and checking C<$@> on exit from that
596 block, as in the code-sample above.
598 There are a small number of exceptions to this rule: the three
599 record-fetching methods in the C<ZOOM::ResultSet> class,
601 C<record_immediate()>,
604 can all return undefined values for legitimate reasons, under
605 circumstances that do not merit throwing an exception. For this
606 reason, the return values of these methods should be checked. See the
607 individual methods' documentation for details.
609 An exception carries the following pieces of information:
615 A numeric code that specifies the type of error. This can be checked
616 for equality with known values, so that intelligent applications can
617 take appropriate action.
621 A human-readable message corresponding with the code. This can be
622 shown to users, but its value should not be tested, as it could vary
623 in different versions or under different locales.
625 =item additional information [optional]
627 A string containing information specific to the error-code. For
628 example, when the error-code is the BIB-1 diagnostic 109 ("Database
629 unavailable"), the additional information is the name of the database
630 that the application tried to use. For some error-codes, there is no
631 additional information at all; for some others, the additional
632 information is undefined and may just be an human-readable string.
634 =item diagnostic set [optional]
636 A short string specifying the diagnostic set from which the error-code
637 was drawn: for example, C<ZOOM> for a ZOOM-specific error such as
638 C<ZOOM::Error::MEMORY> ("out of memory"), and C<BIB-1> for a Z39.50
639 error-code drawn from the BIB-1 diagnostic set.
643 In theory, the error-code should be interpreted in the context of the
644 diagnostic set from which it is drawn; in practice, nearly all errors
645 are from either the ZOOM or BIB-1 diagnostic sets, and the codes in
646 those sets have been chosen so as not to overlap, so the diagnostic
647 set can usually be ignored.
649 See the description of the C<Exception> class in the ZOOM Abstract
651 http://zoom.z3950.org/api/zoom-current.html#3.7
657 die new ZOOM::Exception($errcode, $errmsg, $addinfo, $diagset);
659 Creates and returns a new Exception object with the specified
660 error-code, error-message, additional information and diagnostic set.
661 Applications will not in general need to use this, but may find it
662 useful to simulate ZOOM exceptions. As is usual with Perl, exceptions
663 are thrown using C<die()>.
665 =head4 code() / message() / addinfo() / diagset()
667 print "Error ", $@->code(), ": ", $@->message(), "\n";
668 print "(addinfo '", $@->addinfo(), "', set '", $@->diagset(), "')\n";
670 These methods, of no arguments, return the exception's error-code,
671 error-message, additional information and diagnostic set respectively.
677 Returns a human-readable rendition of an exception. The C<"">
678 operator is overloaded on the Exception class, so that an Exception
679 used in a string context is automatically rendered. Among other
680 consequences, this has the useful result that a ZOOM application that
681 died due to an uncaught exception will emit an informative message
686 $ss = $conn->scan('@attr 1=1003 a');
688 ($term, $occ) = $ss->term($n-1);
689 $rs = $conn->search_pqf('@attr 1=1003 "' . $term . "'");
690 assert($rs->size() == $occ);
692 A ScanSet represents a set of candidate search-terms returned from an
693 index scan. Its sole purpose is to provide access to those term, to
694 the corresponding display terms, and to the occurrence-counts of the
697 There is no C<new()> method nor any other explicit constructor. The
698 only way to create a new ScanSet is by using C<scan()> on a
701 See the description of the C<Scan Set> class in the ZOOM Abstract
703 http://zoom.z3950.org/api/zoom-current.html#3.6
709 print "Found ", $ss->size(), " terms\n";
711 Returns the number of terms in the scan set. In general, this will be
712 the scan-set size requested by the C<number> option in the Connection
713 on which the scan was performed [default 10], but it may be fewer if
714 the scan is close to the end of the index.
716 =head4 term() / display_term()
718 $ss = $conn->scan('@attr 1=1004 whatever');
719 ($term, $occurrences) = $ss->term(0);
720 ($displayTerm, $occurrences2) = $ss->display_term(0);
721 assert($occurrences == $occurrences2);
722 if (user_likes_the_look_of($displayTerm)) {
723 $rs = $conn->search_pqf('@attr 1=4 "' . $term . '"');
724 assert($rs->size() == $occurrences);
727 These methods return the scanned terms themselves. C<term()> returns
728 the term is a form suitable for submitting as part of a query, whereas
729 C<display_term()> returns it in a form suitable for displaying to a
730 user. Both versions also return the number of occurrences of the term
731 in the index, i.e. the number of hits that will be found if the term
732 is subsequently used in a query.
734 In most cases, the term and display term will be identical; however,
735 they may be different in cases where punctuation or case is
736 normalised, or where identifiers rather than the original document
741 print "scan status is ", $ss->option("scanStatus");
743 Allows options to be set into, and read from, a ScanSet, just like
744 the Connection class's C<option()> method. There is no
745 C<option_binary()> method for ScanSet objects.
747 ScanSet options are also described, though not particularly
749 http://indexdata.com/yaz/doc/zoom.scan.tkl
755 Destroys a ScanSet object, freeing its resources. It is an error to
756 reuse a ScanSet that has been C<destroy()>ed.
760 $p = $conn->package();
761 $p->option(action => "specialUpdate");
762 $p->option(recordIdOpaque => 145);
763 $p->option(record => content_of("/tmp/record.xml"));
767 This class represents an Extended Services Package: an instruction to
768 the server to do something not covered by the core parts of the Z39.50
769 standard (or the equivalent in SRW or SRU). Since the core protocols
770 are read-only, such requests are often used to make changes to the
771 database, such as in the record update example above.
773 Requesting an extended service is a four-step process: first, create a
774 package associated with the connection to the relevant database;
775 second, set options on the package to instruct the server on what to
776 do; third, send the package (which may result in an exception being
777 thrown if the server cannot execute the requested operations; and
778 finally, destroy the package.
780 Package options are listed at
781 http://indexdata.com/yaz/doc/zoom.ext.html
783 The particular options that have meaning are determined by the
784 top-level operation string specified as the argument to C<send()>.
785 For example, when the operation is C<update> (the most commonly used
786 extended service), the C<action> option may be set to any of
788 (add a new record, failing if that record already exists),
790 (delete a record, failing if it is not in the database).
792 (replace a record, failing if an old version is not already present)
795 (add a record, replacing any existing version that may be present).
797 For update, the C<record> option should be set to the full text of the
798 XML record to added, deleted or replaced. Depending on how the server
799 is configured, it may extract the record's unique ID from the text
800 (i.e. from a known element such as the C<001> field of a MARCXML
801 record), or it may require the unique ID to passed in explicitly using
802 the C<recordIdOpaque> option.
804 Extended services packages are B<not currently described> in the ZOOM
806 http://zoom.z3950.org/api/zoom-current.html
807 They will be added in a forthcoming version, and will function much
808 as those implemented in this module.
814 $p->option(recordIdOpaque => "46696f6e61");
816 Allows options to be set into, and read from, a Package, just like
817 the Connection class's C<option()> method. There is no
818 C<option_binary()> method for Package objects.
820 Package options are listed at
821 http://indexdata.com/yaz/doc/zoom.ext.tkl
825 $p->send("createdb");
827 Sends a package to the server associated with the Connection that
828 created it. Problems are reported by throwing an exception. The
829 single parameter indicates the operation that the server is being
830 requested to perform, and controls the interpretation of the package's
831 options. Valid operations include:
837 Request a copy of a nominated object, e.g. place an ILL request.
841 Create a new database, the name of which is specified by the
842 C<databaseName> option.
846 Drop an existing database, the name of which is specified by the
847 C<databaseName> option.
851 Commit changes made to the database within a transaction.
855 Modify the contents of the database by adding, deleting or replacing
856 records (as described above in the overview of the C<ZOOM::Package>
861 I have no idea what this does.
865 Although the module is capable of I<making> all these requests, not
866 all servers are capable of I<executing> them. Refusal is indicated by
867 throwing an exception. Problems may also be caused by lack of
868 privileges; so C<send()> must be used with caution, and is perhaps
869 best wrapped in a clause that checks for execptions, like so:
871 eval { $p->send("create") };
872 if ($@ && $@->isa("ZOOM::Exception")) {
873 print "Oops! ", $@->message(), "\n";
881 Destroys a Package object, freeing its resources. It is an error to
882 reuse a Package that has been C<destroy()>ed.
886 $q = new ZOOM::Query::CQL("creator=pike and subject=unix");
887 $q->sortby("1=4 >i 1=21 >s");
888 $rs = $conn->search($q);
891 C<ZOOM::Query> is a virtual base class from which various concrete
892 subclasses can be derived. Different subclasses implement different
893 types of query. The sole purpose of a Query object is to be used in a
894 C<search()> on a Connection; because PQF is such a common special
895 case, the shortcut Connection method C<search_pqf()> is provided.
897 The following Query subclasses are provided, both of the providing the
898 same set of methods described below:
902 =item ZOOM::Query::PQF
904 Implements Prefix Query Format (PQF), also sometimes known as Prefix
905 Query Notation (PQN). This esoteric but rigorous and expressive
906 format is described in the YAZ Manual at
907 http://indexdata.com/yaz/doc/tools.tkl#PQF
909 =item ZOOM::Query::CQL
911 Implements the Common Query Language (CQL) of SRU, the Search/Retrieve
912 URL. CQL is a much friendlier notation than PQF, using a simple infix
913 notation. The queries are passed ``as is'' to the server rather than
914 being compiled into a Z39.50 Type-1 query, so only CQL-compliant
915 servers can support such querier. CQL is described at
916 http://www.loc.gov/standards/sru/cql/
917 and in a slight out-of-date but nevertheless useful tutorial at
918 http://zing.z3950.org/cql/intro.html
922 See the description of the C<Query> class in the ZOOM Abstract
924 http://zoom.z3950.org/api/zoom-current.html#3.3
930 $q = new ZOOM::Query::CQL('title=dinosaur'));
931 $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
933 Creates a new query object, compiling the query passed as its argument
934 according to the rules of the particular query-type being
935 instantiated. If compilation fails, an exception is thrown.
936 Otherwise, the query may be passed to the C<Connection> method
941 $q->sortby("1=4 >i 1=21 >s");
943 Sets a sort specification into the query, so that when a C<search()>
944 is run on the query, the result is automatically sorted. The sort
945 specification language is the same as the C<yaz> sort-specification
946 type of the C<ResultSet> method C<sort()>, described above.
948 B<It ought to be possible to sort by CQL query, too, but at present
949 limitations in the underlying ZOOM-C library make this impossible.>
955 Destroys a Query object, freeing its resources. It is an error to
956 reuse a Query that has been C<destroy()>ed.
960 $o1 = new ZOOM::Options();
961 $o1->option(user => "alf");
962 $o2 = new ZOOM::Options();
963 $o2->option(password => "fruit");
964 $opts = new ZOOM::Options($o1, $o2);
965 $conn = create ZOOM::Connection($opts);
966 $conn->connect($host); # Uses the specified username and password
968 Several classes of ZOOM objects carry their own sets of options, which
969 can be manipulated using their C<option()> method. Sometimes,
970 however, it's useful to deal with the option sets directly, and the
971 C<ZOOM::Options> class exists to enable this approach.
973 Option sets are B<not currently described> in the ZOOM
975 http://zoom.z3950.org/api/zoom-current.html
976 They are an extension to that specification.
988 =head4 option_binary()
992 =head4 bool() / int()
1000 =head4 set_callback()
1010 The ZOOM module provides two enumerations that list possible return
1011 values from particular functions. They are described in the following
1016 if ($@->code() == ZOOM::Error::QUERY_PQF) {
1017 return "your query was not accepted";
1020 This class provides a set of manifest constants representing some of
1021 the possible error codes that can be raised by the ZOOM module. The
1022 methods that return error-codes are
1023 C<ZOOM::Exception::code()>,
1024 C<ZOOM::Connection::error_x()>
1026 C<ZOOM::Connection::errcode()>.
1028 The C<ZOOM::Error> class provides the constants
1038 C<UNSUPPORTED_PROTOCOL>,
1039 C<UNSUPPORTED_QUERY>,
1049 each of which specifies a client-side error. These codes constitute
1050 the C<ZOOM> diagnostic set.
1052 Since errors may also be diagnosed by the server, and returned to the
1053 client, error codes may also take values from the BIB-1 diagnostic set
1054 of Z39.50, listed at the Z39.50 Maintenance Agency's web-site at
1055 http://www.loc.gov/z3950/agency/defns/bib1diag.html
1057 All error-codes, whether client-side from the C<ZOOM::Error>
1058 enumeration or server-side from the BIB-1 diagnostic set, can be
1059 translated into human-readable messages by passing them to the
1060 C<ZOOM::diag_str()> utility function.
1064 if ($conn->last_event() == ZOOM::Event::CONNECT) {
1065 print "Connected!\n";
1068 In applications that need it - mostly complex multiplexing
1069 applications - The C<ZOOM::Connection::last_event()> method is used to
1070 return an indication of the last event that occurred on a particular
1071 connection. It always returns a value drawn from this enumeration,
1072 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
1073 C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
1076 You almost certainly don't need to know about this. Frankly, I'm not
1077 sure how to use it myself.
1081 The ZOOM abstract API,
1082 http://zoom.z3950.org/api/zoom-current.html
1084 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
1086 The C<Net::Z3950> module, which this one supersedes.
1087 http://perl.z3950.org/
1089 The documentation for the ZOOM-C module of the YAZ Toolkit, which this
1090 module is built on. Specifically, its lists of options are useful.
1091 http://indexdata.com/yaz/doc/zoom.tkl
1093 The BIB-1 diagnostic set of Z39.50,
1094 http://www.loc.gov/z3950/agency/defns/bib1diag.html
1098 Mike Taylor, E<lt>mike@indexdata.comE<gt>
1100 =head1 COPYRIGHT AND LICENCE
1102 Copyright (C) 2005 by Index Data.
1104 This library is free software; you can redistribute it and/or modify
1105 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1106 at your option, any later version of Perl 5 you may have available.