1 # $Id: ZOOM.pod,v 1.25 2005-12-21 00:25:51 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>), two utility functions C<diag_str()> and C<event()> in
42 the C<ZOOM> 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 FUNCTIONS
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.
98 Lark's vomit. Do not read this section.
100 $which = ZOOM::event([ $conn1, $conn2, $conn3 ]);
102 Used only in complex asynchronous applications, this function takes a
103 reference to a list of Connection objects, waits until an event
104 occurs on any one of them, and returns an integer indicating which of
105 the connections it occurred on. The return value is a 1-based index
106 into the list; 0 is returned if no event occurs within the longest
107 timeout specified by the C<timeout> options of all the connections.
110 This function is not yet implemented.
114 The eight ZOOM classes are described here in ``sensible order'':
115 first, the four commonly used classes, in the he order that they will
116 tend to be used in most programs (Connection, ResultSet, Record,
117 Exception); then the four more esoteric classes in descending order of
118 how often they are needed.
120 With the exception of the Options class, which is an extension to the
121 ZOOM model, the introduction to each class includes a link to the
122 relevant section of the ZOOM Abstract API.
124 =head2 ZOOM::Connection
126 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
127 print("server is '", $conn->option("serverImplementationName"), "'\n");
128 $conn->option(preferredRecordSyntax => "usmarc");
129 $rs = $conn->search_pqf('@attr 1=4 mineral');
130 $ss = $conn->scan('@attr 1=1003 a');
131 if ($conn->errcode() != 0) {
132 die("somthing went wrong: " . $conn->errmsg())
136 This class represents a connection to an information retrieval server,
137 using an IR protocol such as ANSI/NISO Z39.50, SRW (the
138 Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
139 OpenSearch. Not all of these protocols require a low-level connection
140 to be maintained, but the Connection object nevertheless provides a
141 location for the necessary cache of configuration and state
142 information, as well as a uniform API to the connection-oriented
143 facilities (searching, index browsing, etc.), provided by these
146 See the description of the C<Connection> class in the ZOOM Abstract
148 http://zoom.z3950.org/api/zoom-current.html#3.2
154 $conn = new ZOOM::Connection("indexdata.dk", 210);
155 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
156 $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
157 $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
159 Creates a new Connection object, and immediately connects it to the
160 specified server. If you want to make a new Connection object but
161 delay forging the connection, use the C<create()> and C<connect()>
164 This constructor can be called with two arguments or a single
165 argument. In the former case, the arguments are the name and port
166 number of the Z39.50 server to connect to; in the latter case, the
167 single argument is a YAZ service-specifier string of the form
173 [I<scheme>:]I<host>[:I<port>][/I<databaseName>]
177 In which the I<host> and I<port> parts are as in the two-argument
178 form, the I<databaseName> if provided specifies the name of the
179 database to be used in subsequent searches on this connection, and the
180 optional I<scheme> (default C<tcp>) indicates what protocol should be
181 used. At present, the following schemes are supported:
191 Z39.50 connection encrypted using SSL (Secure Sockets Layer). Not
192 many servers support this, but Index Data's Zebra is one that does.
196 Z39.50 connection on a Unix-domain (local) socket, in which case the
197 I<hostname> portion of the string is instead used as a filename in the
202 SRW connection using SOAP over HTTP.
206 Support for SRU will follow in the fullness of time.
208 If an error occurs, an exception is thrown. This may indicate a
209 networking problem (e.g. the host is not found or unreachable), or a
210 protocol-level problem (e.g. a Z39.50 server rejected the Init
213 =head4 create() / connect()
215 $options = new ZOOM::Options();
216 $options->option(implementationName => "my client");
217 $conn = create ZOOM::Connection($options)
218 $conn->connect($host, 0);
220 The usual Connection constructor, C<new()> brings a new object into
221 existence and forges the connection to the server all in one
222 operation, which is often what you want. For applications that need
223 more control, however, these two method separate the two steps,
224 allowing additional steps in between such as the setting of options.
226 C<create()> creates and returns a new Connection object, which is
227 I<not> connected to any server. It may be passed an options block, of
228 type C<ZOOM::Options> (see below), into which options may be set
229 before or after the creation of the Connection. The connection to the
230 server may then be forged by the C<connect()> method, the arguments of
231 which are the same as those of the C<new()> constructor.
233 =head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
235 ($errcode, $errmsg, $addinfo, $diagset) = $conn->error_x();
236 $errcode = $conn->errcode();
237 $errmsg = $conn->errmsg();
238 $addinfo = $conn->addinfo();
239 $diagset = $conn->diagset();
241 These methods may be used to obtain information about the last error
242 to have occurred on a connection - although typically they will not
243 been used, as the same information is available through the
244 C<ZOOM::Exception> that is thrown when the error occurs. The
250 methods each return one element of the diagnostic, and
252 returns all four at once.
254 See the C<ZOOM::Exception> for the interpretation of these elements.
256 =head4 option() / option_binary()
258 print("server is '", $conn->option("serverImplementationName"), "'\n");
259 $conn->option(preferredRecordSyntax => "usmarc");
260 $conn->option_binary(iconBlob => "foo\0bar");
261 die if length($conn->option_binary("iconBlob") != 7);
263 Objects of the Connection, ResultSet, ScanSet and Package classes
264 carry with them a set of named options which affect their behaviour in
265 certain ways. See the ZOOM-C options documentation for details:
267 Connection options are listed at
268 http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
270 These options are set and fetched using the C<option()> method, which
271 may be called with either one or two arguments. In the two-argument
272 form, the option named by the first argument is set to the value of
273 the second argument, and its old value is returned. In the
274 one-argument form, the value of the specified option is returned.
276 For historical reasons, option values are not binary-clean, so that a
277 value containing a NUL byte will be returned in truncated form. The
278 C<option_binary()> method behaves identically to C<option()> except
279 that it is binary-clean, so that values containing NUL bytes are set
280 and returned correctly.
282 =head4 search() / search_pqf()
284 $rs = $conn->search(new ZOOM::Query::CQL('title=dinosaur'));
285 # The next two lines are equivalent
286 $rs = $conn->search(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
287 $rs = $conn->search_pqf('@attr 1=4 dinosaur');
289 The principal purpose of a search-and-retrieve protocol is searching
290 (and, er, retrieval), so the principal method used on a Connection
291 object is C<search()>. It accepts a single argument, a C<ZOOM::Query>
292 object (or, more precisely, an object of a subclass of this class);
293 and it creates and returns a new ResultSet object representing the set
294 of records resulting from the search.
296 Since queries using PQF (Prefix Query Format) are so common, we make
297 them a special case by providing a C<search_pqf()> method. This is
298 identical to C<search()> except that it accepts a string containing
299 the query rather than an object, thereby obviating the need to create
300 a C<ZOOM::Query::PQF> object. See the documentation of that class for
301 information about PQF.
303 =head4 scan() / scan_pqf()
305 $rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur'));
306 # The next two lines are equivalent
307 $rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
308 $rs = $conn->scan_pqf('@attr 1=4 dinosaur');
310 Many Z39.50 servers allow you to browse their indexes to find terms to
311 search for. This is done using the C<scan> method, which creates and
312 returns a new ScanSet object representing the set of terms resulting
315 C<scan()> takes a single argument, but it has to work hard: it
316 specifies both what index to scan for terms, and where in the index to
317 start scanning. What's more, the specification of what index to scan
318 includes multiple facets, such as what database fields it's an index
319 of (author, subject, title, etc.) and whether to scan for whole fields
320 or single words (e.g. the title ``I<The Empire Strikes Back>'', or the
321 four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved
322 with words from other titles in the same index.
324 All of this is done by using a Query object representing a query of a
325 single term as the C<scan()> argument. The attributes associated with
326 the term indicate which index is to be used, and the term itself
327 indicates the point in the index at which to start the scan. For
328 example, if the argument is the query C<@attr 1=4 fish>, then
334 This is the BIB-1 attribute with type 1 (meaning access-point, which
335 specifies an index), and type 4 (which means ``title''). So the scan
336 is in the title index.
340 Start the scan from the lexicographically earliest term that is equal
341 to or falls after ``fish''.
345 The argument C<@attr 1=4 @attr 6=3 fish> would behave similarly; but
346 the BIB-1 attribute 6=3 mean completeness=``complete field'', so the
347 scan would be for complete titles rather than for words occurring in
350 This takes a bit of getting used to.
352 The behaviour is C<scan()> is affected by the following options, which
353 may be set on the Connection through which the scan is done:
357 =item number [default: 10]
359 Indicates how many terms should be returned in the ScanSet. The
360 number actually returned may be less, if the start-point is near the
361 end of the index, but will not be greater.
363 =item position [default: 1]
365 A 1-based index specifying where in the returned list of terms the
366 seed-term should appear. By default it should be the first term
367 returned, but C<position> may be set, for example, to zero (requesting
368 the next terms I<after> the seed-term), or to the same value as
369 C<number> (requesting the index terms I<before> the seed term).
371 =item stepSize [default: 0]
373 An integer indicating how many indexed terms are to be skipped between
374 each one returned in the ScanSet. By default, no terms are skipped,
375 but overriding this can be useful to get a high-level overview of the
378 Since scans using PQF (Prefix Query Format) are so common, we make
379 them a special case by providing a C<scan_pqf()> method. This is
380 identical to C<scan()> except that it accepts a string containing the
381 query rather than an object, thereby obviating the need to create a
382 C<ZOOM::Query::PQF> object.
388 $p = $conn->package();
389 $o = new ZOOM::Options();
390 $o->option(databaseName => "newdb");
391 $p = $conn->package($o);
393 Creates and returns a new C<ZOOM::Package>, to be used in invoking an
394 Extended Service. An options block may optionally be passed in. See
395 the C<ZOOM::Package> documentation.
399 if ($conn->last_event() == ZOOM::Event::CONNECT) {
400 print "Connected!\n";
403 Returns a C<ZOOM::Event> enumerated value indicating the type of the
404 last event that occurred on the connection. This is used only in
405 complex asynchronous applications - see the section below on
406 C<ZOOM::Event> for more information.
409 This method has not been tested.
415 Destroys a Connection object, tearing down any low-level connection
416 associated with it and freeing its resources. It is an error to reuse
417 a Connection that has been C<destroy()>ed.
419 =head2 ZOOM::ResultSet
421 $rs = $conn->search_pqf('@attr 1=4 mineral');
424 $rec = $rs->record($i-1);
425 print $rec->render();
428 A ResultSet object represents the set of zero or more records
429 resulting from a search, and is the means whereby these records can be
430 retrieved. A ResultSet object may maintain client side cache or some,
431 less, none, all or more of the server's records: in general, this is
432 supposed to an implementaton detail of no interest to a typical
433 application, although more sophisticated applications do have
434 facilities for messing with the cache. Most applications will only
435 need the C<size()>, C<record()> and C<sort()> methods.
437 There is no C<new()> method nor any other explicit constructor. The
438 only way to create a new ResultSet is by using C<search()> (or
439 C<search_pqf()>) on a Connection.
441 See the description of the C<Result Set> class in the ZOOM Abstract
443 http://zoom.z3950.org/api/zoom-current.html#3.4
449 $rs->option(elementSetName => "f");
451 Allows options to be set into, and read from, a ResultSet, just like
452 the Connection class's C<option()> method. There is no
453 C<option_binary()> method for ResultSet objects.
455 ResultSet options are listed at
456 http://indexdata.com/yaz/doc/zoom.resultsets.tkl
460 print "Found ", $rs->size(), " records\n";
462 Returns the number of records in the result set.
464 =head4 record() / record_immediate()
466 $rec = $rs->record(0);
467 $rec2 = $rs->record_immediate(0);
468 $rec3 = $rs->record_immediate(1)
469 or print "second record wasn't in cache\n";
471 The C<record()> method returns a C<ZOOM::Record> object representing
472 a record from result-set, whose position is indicated by the argument
473 passed in. This is a zero-based index, so that legitimate values
474 range from zero to C<$rs->size()-1>.
476 The C<record_immediate()> API is identical, but it never invokes a
477 network operation, merely returning the record from the ResultSet's
478 cache if it's already there, or an undefined value otherwise. So if
479 you use this method, B<you must always check the return value>.
483 $rs->records(0, 10, 0);
485 print $rs->record_immediate($i)->render();
488 @nextseven = $rs->records(10, 7, 1);
490 The C<record_immediate()> method only fetches records from the cache,
491 whereas C<record()> fetches them from the server if they have not
492 already been cached; but the ZOOM module has to guess what the most
493 efficient strategy for this is. It might fetch each record, alone
494 when asked for: that's optimal in an application that's only
495 interested in the top hit from each search, but pessimal for one that
496 wants to display a whole list of results. Conversely, the software's
497 strategy might be always to ask for blocks of a twenty records:
498 that's great for assembling long lists of things, but wasteful when
499 only one record is wanted. The problem is that the ZOOM module can't
500 tell, when you call C<$rs->record()>, what your intention is.
502 But you can tell it. The C<records()> method fetches a sequence of
503 records, all in one go. It takes three arguments: the first is the
504 zero-based index of the first record in the sequence, the second is
505 the number of records to fetch, and the third is a boolean indication
506 of whether or not to return the retrieved records as well as adding
507 them to the cache. (You can always pass 1 for this if you like, and
508 Perl will discard the unused return value, but there is a small
509 efficiency gain to be had by passing 0.)
511 Once the records have been retrieved from the server
512 (i.e. C<records()> has completed without throwing an exception), they
513 can be fetched much more efficiently using C<record()> - or
514 C<record_immediate()>, which is then guaranteed to succeed.
520 Resets the ResultSet's record cache, so that subsequent invocations of
521 C<record_immediate()> will fail. I struggle to imagine a real
522 scenario where you'd want to do this.
526 if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) {
530 Sorts the ResultSet in place (discarding any cached records, as they
531 will in general be sorted into a different position). There are two
532 arguments: the first is a string indicating the type of the
533 sort-specification, and the second is the specification itself.
535 The C<sort()> method returns 0 on success, or -1 if the
536 sort-specification is invalid.
538 At present, the only supported sort-specification type is C<yaz>.
539 Such a specification consists of a space-separated sequence of keys,
540 each of which itself consists of two space-separated words (so that
541 the total number of words in the sort-specification is even). The two
542 words making up each key are a field and a set of flags. The field
543 can take one of two forms: if it contains an C<=> sign, then it is a
544 BIB-1 I<type>=I<value> pair specifying which field to sort
545 (e.g. C<1=4> for a title sort); otherwise it is sent for the server to
546 interpret as best it can. The word of flags is made up from one or
547 more of the following: C<s> for case sensitive, C<i> for case
548 insensitive; C<<> for ascending order and C<E<gt>> for descending
551 For example, the sort-specification in the code-fragment above will
552 sort the records in C<$rs> case-insensitively in descending order of
553 title, with records having equivalent titles sorted case-sensitively
554 in ascending order of subject. (The BIB-1 access points 4 and 21
555 represent title and subject respectively.)
561 Destroys a ResultSet object, freeing its resources. It is an error to
562 reuse a ResultSet that has been C<destroy()>ed.
566 $rec = $rs->record($i);
567 print $rec->render();
569 $marc = new_from_usmarc MARC::Record($raw);
570 print "Record title is: ", $marc->title(), "\n";
572 A Record object represents a record that has been retrived from the
575 There is no C<new()> method nor any other explicit constructor. The
576 only way to create a new Record is by using C<record()> (or
577 C<record_immediate()>, or C<records()>) on a ResultSet.
579 In general, records are ``owned'' by their result-sets that they were
580 retrieved from, so they do not have to be explicitly memory-managed:
581 they are deallocated (and therefore can no longer be used) when the
582 result-set is destroyed.
584 See the description of the C<Record> class in the ZOOM Abstract
586 http://zoom.z3950.org/api/zoom-current.html#3.5
594 Returns a human-readable representation of the record. Beyond that,
595 no promises are made: careful programs should not make assumptions
596 about the format of the returned string.
598 This method is useful mostly for debugging.
604 $marc = new_from_usmarc MARC::Record($raw);
606 Returns an opaque blob of data that is the raw form of the record.
607 Exactly what this is, and what you can do with it, varies depending on
608 the record-syntax. For example, XML records will be returned as,
609 well, XML; MARC records will be returned as ISO 2709-encoded blocks
610 that can be decoded by software such as the fine C<Marc::Record>
611 module; GRS-1 record will be ... gosh, what an interesting question.
612 But no-one uses GRS-1 any more, do they?
614 =head4 clone() / destroy()
616 $rec = $rs->record($i);
617 $newrec = $rec->clone();
619 print $newrec->render();
622 Usually, it's convenient that Record objects are owned by their
623 ResultSets and go away when the ResultSet is destroyed; but
624 occasionally you need a Record to outlive its parent and destroy it
625 later, explicitly. To do this, C<clone()> the record, keep the new
626 Record object that is returned, and C<destroy()> it when it's no
627 longer needed. This is B<only> situation in which a Record needs to
630 =head2 ZOOM::Exception
632 In general, method calls throw an exception (of class
633 C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
634 for success after each call. Exceptions are caught by enclosing the
635 main code in an C<eval{}> block and checking C<$@> on exit from that
636 block, as in the code-sample above.
638 There are a small number of exceptions to this rule: the three
639 record-fetching methods in the C<ZOOM::ResultSet> class,
641 C<record_immediate()>,
644 can all return undefined values for legitimate reasons, under
645 circumstances that do not merit throwing an exception. For this
646 reason, the return values of these methods should be checked. See the
647 individual methods' documentation for details.
649 An exception carries the following pieces of information:
655 A numeric code that specifies the type of error. This can be checked
656 for equality with known values, so that intelligent applications can
657 take appropriate action.
661 A human-readable message corresponding with the code. This can be
662 shown to users, but its value should not be tested, as it could vary
663 in different versions or under different locales.
665 =item additional information [optional]
667 A string containing information specific to the error-code. For
668 example, when the error-code is the BIB-1 diagnostic 109 ("Database
669 unavailable"), the additional information is the name of the database
670 that the application tried to use. For some error-codes, there is no
671 additional information at all; for some others, the additional
672 information is undefined and may just be an human-readable string.
674 =item diagnostic set [optional]
676 A short string specifying the diagnostic set from which the error-code
677 was drawn: for example, C<ZOOM> for a ZOOM-specific error such as
678 C<ZOOM::Error::MEMORY> ("out of memory"), and C<BIB-1> for a Z39.50
679 error-code drawn from the BIB-1 diagnostic set.
683 In theory, the error-code should be interpreted in the context of the
684 diagnostic set from which it is drawn; in practice, nearly all errors
685 are from either the ZOOM or BIB-1 diagnostic sets, and the codes in
686 those sets have been chosen so as not to overlap, so the diagnostic
687 set can usually be ignored.
689 See the description of the C<Exception> class in the ZOOM Abstract
691 http://zoom.z3950.org/api/zoom-current.html#3.7
697 die new ZOOM::Exception($errcode, $errmsg, $addinfo, $diagset);
699 Creates and returns a new Exception object with the specified
700 error-code, error-message, additional information and diagnostic set.
701 Applications will not in general need to use this, but may find it
702 useful to simulate ZOOM exceptions. As is usual with Perl, exceptions
703 are thrown using C<die()>.
705 =head4 code() / message() / addinfo() / diagset()
707 print "Error ", $@->code(), ": ", $@->message(), "\n";
708 print "(addinfo '", $@->addinfo(), "', set '", $@->diagset(), "')\n";
710 These methods, of no arguments, return the exception's error-code,
711 error-message, additional information and diagnostic set respectively.
717 Returns a human-readable rendition of an exception. The C<"">
718 operator is overloaded on the Exception class, so that an Exception
719 used in a string context is automatically rendered. Among other
720 consequences, this has the useful result that a ZOOM application that
721 died due to an uncaught exception will emit an informative message
726 $ss = $conn->scan('@attr 1=1003 a');
728 ($term, $occ) = $ss->term($n-1);
729 $rs = $conn->search_pqf('@attr 1=1003 "' . $term . "'");
730 assert($rs->size() == $occ);
732 A ScanSet represents a set of candidate search-terms returned from an
733 index scan. Its sole purpose is to provide access to those term, to
734 the corresponding display terms, and to the occurrence-counts of the
737 There is no C<new()> method nor any other explicit constructor. The
738 only way to create a new ScanSet is by using C<scan()> on a
741 See the description of the C<Scan Set> class in the ZOOM Abstract
743 http://zoom.z3950.org/api/zoom-current.html#3.6
749 print "Found ", $ss->size(), " terms\n";
751 Returns the number of terms in the scan set. In general, this will be
752 the scan-set size requested by the C<number> option in the Connection
753 on which the scan was performed [default 10], but it may be fewer if
754 the scan is close to the end of the index.
756 =head4 term() / display_term()
758 $ss = $conn->scan('@attr 1=1004 whatever');
759 ($term, $occurrences) = $ss->term(0);
760 ($displayTerm, $occurrences2) = $ss->display_term(0);
761 assert($occurrences == $occurrences2);
762 if (user_likes_the_look_of($displayTerm)) {
763 $rs = $conn->search_pqf('@attr 1=4 "' . $term . '"');
764 assert($rs->size() == $occurrences);
767 These methods return the scanned terms themselves. C<term()> returns
768 the term is a form suitable for submitting as part of a query, whereas
769 C<display_term()> returns it in a form suitable for displaying to a
770 user. Both versions also return the number of occurrences of the term
771 in the index, i.e. the number of hits that will be found if the term
772 is subsequently used in a query.
774 In most cases, the term and display term will be identical; however,
775 they may be different in cases where punctuation or case is
776 normalised, or where identifiers rather than the original document
781 print "scan status is ", $ss->option("scanStatus");
783 Allows options to be set into, and read from, a ScanSet, just like
784 the Connection class's C<option()> method. There is no
785 C<option_binary()> method for ScanSet objects.
787 ScanSet options are also described, though not particularly
789 http://indexdata.com/yaz/doc/zoom.scan.tkl
795 Destroys a ScanSet object, freeing its resources. It is an error to
796 reuse a ScanSet that has been C<destroy()>ed.
800 $p = $conn->package();
801 $p->option(action => "specialUpdate");
802 $p->option(recordIdOpaque => 145);
803 $p->option(record => content_of("/tmp/record.xml"));
807 This class represents an Extended Services Package: an instruction to
808 the server to do something not covered by the core parts of the Z39.50
809 standard (or the equivalent in SRW or SRU). Since the core protocols
810 are read-only, such requests are often used to make changes to the
811 database, such as in the record update example above.
813 Requesting an extended service is a four-step process: first, create a
814 package associated with the connection to the relevant database;
815 second, set options on the package to instruct the server on what to
816 do; third, send the package (which may result in an exception being
817 thrown if the server cannot execute the requested operations; and
818 finally, destroy the package.
820 Package options are listed at
821 http://indexdata.com/yaz/doc/zoom.ext.html
823 The particular options that have meaning are determined by the
824 top-level operation string specified as the argument to C<send()>.
825 For example, when the operation is C<update> (the most commonly used
826 extended service), the C<action> option may be set to any of
828 (add a new record, failing if that record already exists),
830 (delete a record, failing if it is not in the database).
832 (replace a record, failing if an old version is not already present)
835 (add a record, replacing any existing version that may be present).
837 For update, the C<record> option should be set to the full text of the
838 XML record to added, deleted or replaced. Depending on how the server
839 is configured, it may extract the record's unique ID from the text
840 (i.e. from a known element such as the C<001> field of a MARCXML
841 record), or it may require the unique ID to passed in explicitly using
842 the C<recordIdOpaque> option.
844 Extended services packages are B<not currently described> in the ZOOM
846 http://zoom.z3950.org/api/zoom-current.html
847 They will be added in a forthcoming version, and will function much
848 as those implemented in this module.
854 $p->option(recordIdOpaque => "46696f6e61");
856 Allows options to be set into, and read from, a Package, just like
857 the Connection class's C<option()> method. There is no
858 C<option_binary()> method for Package objects.
860 Package options are listed at
861 http://indexdata.com/yaz/doc/zoom.ext.tkl
865 $p->send("createdb");
867 Sends a package to the server associated with the Connection that
868 created it. Problems are reported by throwing an exception. The
869 single parameter indicates the operation that the server is being
870 requested to perform, and controls the interpretation of the package's
871 options. Valid operations include:
877 Request a copy of a nominated object, e.g. place an ILL request.
881 Create a new database, the name of which is specified by the
882 C<databaseName> option.
886 Drop an existing database, the name of which is specified by the
887 C<databaseName> option.
891 Commit changes made to the database within a transaction.
895 Modify the contents of the database by adding, deleting or replacing
896 records (as described above in the overview of the C<ZOOM::Package>
901 I have no idea what this does.
905 Although the module is capable of I<making> all these requests, not
906 all servers are capable of I<executing> them. Refusal is indicated by
907 throwing an exception. Problems may also be caused by lack of
908 privileges; so C<send()> must be used with caution, and is perhaps
909 best wrapped in a clause that checks for execptions, like so:
911 eval { $p->send("create") };
912 if ($@ && $@->isa("ZOOM::Exception")) {
913 print "Oops! ", $@->message(), "\n";
921 Destroys a Package object, freeing its resources. It is an error to
922 reuse a Package that has been C<destroy()>ed.
926 $q = new ZOOM::Query::CQL("creator=pike and subject=unix");
927 $q->sortby("1=4 >i 1=21 >s");
928 $rs = $conn->search($q);
931 C<ZOOM::Query> is a virtual base class from which various concrete
932 subclasses can be derived. Different subclasses implement different
933 types of query. The sole purpose of a Query object is to be used in a
934 C<search()> on a Connection; because PQF is such a common special
935 case, the shortcut Connection method C<search_pqf()> is provided.
937 The following Query subclasses are provided, both of the providing the
938 same set of methods described below:
942 =item ZOOM::Query::PQF
944 Implements Prefix Query Format (PQF), also sometimes known as Prefix
945 Query Notation (PQN). This esoteric but rigorous and expressive
946 format is described in the YAZ Manual at
947 http://indexdata.com/yaz/doc/tools.tkl#PQF
949 =item ZOOM::Query::CQL
951 Implements the Common Query Language (CQL) of SRU, the Search/Retrieve
952 URL. CQL is a much friendlier notation than PQF, using a simple infix
953 notation. The queries are passed ``as is'' to the server rather than
954 being compiled into a Z39.50 Type-1 query, so only CQL-compliant
955 servers can support such querier. CQL is described at
956 http://www.loc.gov/standards/sru/cql/
957 and in a slight out-of-date but nevertheless useful tutorial at
958 http://zing.z3950.org/cql/intro.html
962 See the description of the C<Query> class in the ZOOM Abstract
964 http://zoom.z3950.org/api/zoom-current.html#3.3
970 $q = new ZOOM::Query::CQL('title=dinosaur'));
971 $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
973 Creates a new query object, compiling the query passed as its argument
974 according to the rules of the particular query-type being
975 instantiated. If compilation fails, an exception is thrown.
976 Otherwise, the query may be passed to the C<Connection> method
981 $q->sortby("1=4 >i 1=21 >s");
983 Sets a sort specification into the query, so that when a C<search()>
984 is run on the query, the result is automatically sorted. The sort
985 specification language is the same as the C<yaz> sort-specification
986 type of the C<ResultSet> method C<sort()>, described above.
992 Destroys a Query object, freeing its resources. It is an error to
993 reuse a Query that has been C<destroy()>ed.
997 $o1 = new ZOOM::Options();
998 $o1->option(user => "alf");
999 $o2 = new ZOOM::Options();
1000 $o2->option(password => "fruit");
1001 $opts = new ZOOM::Options($o1, $o2);
1002 $conn = create ZOOM::Connection($opts);
1003 $conn->connect($host); # Uses the specified username and password
1005 Several classes of ZOOM objects carry their own sets of options, which
1006 can be manipulated using their C<option()> method. Sometimes,
1007 however, it's useful to deal with the option sets directly, and the
1008 C<ZOOM::Options> class exists to enable this approach.
1010 Option sets are B<not currently described> in the ZOOM
1012 http://zoom.z3950.org/api/zoom-current.html
1013 They are an extension to that specification.
1019 $o1 = new ZOOM::Options();
1020 $o1and2 = new ZOOM::Options($o1);
1021 $o3 = new ZOOM::Options();
1022 $o1and3and4 = new ZOOM::Options($o1, $o3);
1024 Creates and returns a new option set. One or two (but no more)
1025 existing option sets may be passed as arguments, in which case they
1026 become ``parents'' of the new set, which thereby ``inherits'' their
1027 options, the values of the first parent overriding those of the second
1028 when both have a value for the same key. An option set that inherits
1029 from a parent that has its own parents also inherits the grandparent's
1032 =head4 option() / option_binary()
1034 $o->option(preferredRecordSyntax => "usmarc");
1035 $o->option_binary(iconBlob => "foo\0bar");
1036 die if length($o->option_binary("iconBlob") != 7);
1038 These methods are used to get and set options within a set, and behave
1039 the same way as the same-named C<Connection> methods - see above. As
1040 with the C<Connection> methods, values passed to and retrieved using
1041 C<option()> are interpreted as NUL-terminated, while those passed to
1042 and retrieved from C<option_binary()> are binary-clean.
1046 $o->option(x => "T");
1047 $o->option(y => "F");
1048 assert($o->bool("x", 1));
1049 assert(!$o->bool("y", 1));
1050 assert($o->bool("z", 1));
1052 The first argument is a key, and the second is a default value.
1053 Returns the value associated with the specified key as a boolean, or
1054 the default value if the key has not been set. The values C<T> (upper
1055 case) and C<1> are considered true; all other values (including C<t>
1056 (lower case) and non-zero integers other than one) are considered
1059 This method is provided in ZOOM-C because in a statically typed
1060 language it's convenient to have the result returned as an
1061 easy-to-test type. In a dynamically typed language such as Perl, this
1062 problem doesn't arise, so C<bool()> is nearly useless; but it is made
1063 available in case applications need to duplicate the idiosyncratic
1064 interpretation of truth and falsehood and ZOOM-C uses.
1068 $o->option(x => "012");
1069 assert($o->int("x", 20) == 12);
1070 assert($o->int("y", 20) == 20);
1072 Returns the value associated with the specified key as an integer, or
1073 the default value if the key has not been set. See the description of
1074 C<bool()> for why you almost certainly don't want to use this.
1078 $o->set_int(x => "29");
1080 Sets the value of the specified option as an integer. Of course, Perl
1081 happily converts strings to integers on its own, so you can just use
1082 C<option()> for this, but C<set_int()> is guaranteed to use the same
1083 string-to-integer conversion as ZOOM-C does, which might occasionally
1084 be useful. Though I can't imagine how.
1086 =head4 set_callback()
1090 return "$udata-$key-$udata";
1092 $o->set_callback(\&cb, "xyz");
1093 assert($o->option("foo") eq "xyz-foo-xyz");
1095 This method allows a callback function to be installed in an option
1096 set, so that the values of options can be calculated algorithmically
1097 rather than, as usual, looked up in a table. Along with the callback
1098 function itself, an additional datum is provided: when an option is
1099 subsequently looked up, this datum is passed to the callback function
1100 along with the key; and its return value is returned to the caller as
1101 the value of the option.
1104 Although it ought to be possible to specify callback function using
1105 the C<\&name> syntax above, or a literal C<sub { code }> code
1106 reference, the complexities of the Perl-internal memory management
1107 system mean that the function must currently be specified as a string
1108 containing the fully-qualified name, e.g. C<"main::cb">.>
1111 The current implementation of the this method leaks memory, not only
1112 when the callback is installed, but on every occasion that it is
1113 consulted to look up an option value.
1119 Destroys an Options object, freeing its resources. It is an error to
1120 reuse an Options object that has been C<destroy()>ed.
1124 The ZOOM module provides two enumerations that list possible return
1125 values from particular functions. They are described in the following
1130 if ($@->code() == ZOOM::Error::QUERY_PQF) {
1131 return "your query was not accepted";
1134 This class provides a set of manifest constants representing some of
1135 the possible error codes that can be raised by the ZOOM module. The
1136 methods that return error-codes are
1137 C<ZOOM::Exception::code()>,
1138 C<ZOOM::Connection::error_x()>
1140 C<ZOOM::Connection::errcode()>.
1142 The C<ZOOM::Error> class provides the constants
1152 C<UNSUPPORTED_PROTOCOL>,
1153 C<UNSUPPORTED_QUERY>,
1163 each of which specifies a client-side error. These codes constitute
1164 the C<ZOOM> diagnostic set.
1166 Since errors may also be diagnosed by the server, and returned to the
1167 client, error codes may also take values from the BIB-1 diagnostic set
1168 of Z39.50, listed at the Z39.50 Maintenance Agency's web-site at
1169 http://www.loc.gov/z3950/agency/defns/bib1diag.html
1171 All error-codes, whether client-side from the C<ZOOM::Error>
1172 enumeration or server-side from the BIB-1 diagnostic set, can be
1173 translated into human-readable messages by passing them to the
1174 C<ZOOM::diag_str()> utility function.
1178 if ($conn->last_event() == ZOOM::Event::CONNECT) {
1179 print "Connected!\n";
1182 In applications that need it - mostly complex multiplexing
1183 applications - The C<ZOOM::Connection::last_event()> method is used to
1184 return an indication of the last event that occurred on a particular
1185 connection. It always returns a value drawn from this enumeration,
1186 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
1187 C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
1190 You almost certainly don't need to know about this. Frankly, I'm not
1191 sure how to use it myself.
1195 The ZOOM abstract API,
1196 http://zoom.z3950.org/api/zoom-current.html
1198 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
1200 The C<Net::Z3950> module, which this one supersedes.
1201 http://perl.z3950.org/
1203 The documentation for the ZOOM-C module of the YAZ Toolkit, which this
1204 module is built on. Specifically, its lists of options are useful.
1205 http://indexdata.com/yaz/doc/zoom.tkl
1207 The BIB-1 diagnostic set of Z39.50,
1208 http://www.loc.gov/z3950/agency/defns/bib1diag.html
1212 Mike Taylor, E<lt>mike@indexdata.comE<gt>
1214 =head1 COPYRIGHT AND LICENCE
1216 Copyright (C) 2005 by Index Data.
1218 This library is free software; you can redistribute it and/or modify
1219 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1220 at your option, any later version of Perl 5 you may have available.