1 # $Id: ZOOM.pod,v 1.39 2006-11-03 09:36:28 mike Exp $
8 ZOOM - Perl extension implementing the ZOOM API for Information Retrieval
14 $conn = new ZOOM::Connection($host, $port,
15 databaseName => "mydb");
16 $conn->option(preferredRecordSyntax => "usmarc");
17 $rs = $conn->search_pqf('@attr 1=4 dinosaur');
19 print $rs->record(0)->render();
22 print "Error ", $@->code(), ": ", $@->message(), "\n";
27 This module provides a nice, Perlish implementation of the ZOOM
28 Abstract API described and documented at http://zoom.z3950.org/api/
30 the ZOOM module is implemented as a set of thin classes on top of the
31 non-OO functions provided by this distribution's C<Net::Z3950::ZOOM>
33 turn is a thin layer on top of the ZOOM-C code supplied as part of
34 Index Data's YAZ Toolkit. Because ZOOM-C is also the underlying code
35 that implements ZOOM bindings in C++, Visual Basic, Scheme, Ruby, .NET
36 (including C#) and other languages, this Perl module works compatibly
37 with those other implementations. (Of course, the point of a public
38 API such as ZOOM is that all implementations should be compatible
39 anyway; but knowing that the same code is running is reassuring.)
41 The ZOOM module provides two enumerations (C<ZOOM::Error> and
42 C<ZOOM::Event>), three utility functions C<diag_str()>, C<event_str()>
43 and C<event()> in the C<ZOOM> package itself, and eight classes:
53 Of these, the Query class is abstract, and has four concrete
57 C<ZOOM::Query::CQL2RPN>
59 C<ZOOM::Query::CCL2RPN>.
60 Finally, it also provides a
62 module which supplies a useful general-purpose logging facility.
63 Many useful ZOOM applications can be built using only the Connection,
64 ResultSet, Record and Exception classes, as in the example
67 A typical application will begin by creating an Connection object,
68 then using that to execute searches that yield ResultSet objects, then
69 fetching records from the result-sets to yield Record objects. If an
70 error occurs, an Exception object is thrown and can be dealt with.
72 More sophisticated applications might also browse the server's indexes
73 to create a ScanSet, from which indexed terms may be retrieved; others
74 might send ``Extended Services'' Packages to the server, to achieve
75 non-standard tasks such as database creation and record update.
76 Searching using a query syntax other than PQF can be done using an
77 query object of one of the Query subclasses. Finally, sets of options
78 may be manipulated independently of the objects they are associated
79 with using an Options object.
81 In general, method calls throw an exception if anything goes wrong, so
82 you don't need to test for success after each call. See the section
83 below on the Exception class for details.
85 =head1 UTILITY FUNCTIONS
87 =head2 ZOOM::diag_str()
89 $msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);
91 Returns a human-readable English-language string corresponding to the
92 error code that is its own parameter. This works for any error-code
94 C<ZOOM::Exception::code()>,
95 C<ZOOM::Connection::error_x()>
97 C<ZOOM::Connection::errcode()>,
98 irrespective of whether it is a member of the C<ZOOM::Error>
99 enumeration or drawn from the BIB-1 diagnostic set.
101 =head2 ZOOM::event_str()
103 $msg = ZOOM::event_str(ZOOM::Event::RECV_APDU);
105 Returns a human-readable English-language string corresponding to the
106 event code that is its own parameter. This works for any value of the
107 C<ZOOM::Event> enumeration.
111 $connsRef = [ $conn1, $conn2, $conn3 ];
112 $which = ZOOM::event($connsRef);
113 $ev = $connsRef->[$which-1]->last_event()
116 Used only in complex asynchronous applications, this function takes a
117 reference to a list of Connection objects, waits until an event
118 occurs on any one of them, and returns an integer indicating which of
119 the connections it occurred on. The return value is a 1-based index
120 into the list; 0 is returned if no event occurs within the longest
121 timeout specified by the C<timeout> options of all the connections.
123 See the section below on asynchronous applications.
127 The eight ZOOM classes are described here in ``sensible order'':
128 first, the four commonly used classes, in the he order that they will
129 tend to be used in most programs (Connection, ResultSet, Record,
130 Exception); then the four more esoteric classes in descending order of
131 how often they are needed.
133 With the exception of the Options class, which is an extension to the
134 ZOOM model, the introduction to each class includes a link to the
135 relevant section of the ZOOM Abstract API.
137 =head2 ZOOM::Connection
139 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
140 print("server is '", $conn->option("serverImplementationName"), "'\n");
141 $conn->option(preferredRecordSyntax => "usmarc");
142 $rs = $conn->search_pqf('@attr 1=4 mineral');
143 $ss = $conn->scan('@attr 1=1003 a');
144 if ($conn->errcode() != 0) {
145 die("somthing went wrong: " . $conn->errmsg())
149 This class represents a connection to an information retrieval server,
150 using an IR protocol such as ANSI/NISO Z39.50, SRW (the
151 Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
152 OpenSearch. Not all of these protocols require a low-level connection
153 to be maintained, but the Connection object nevertheless provides a
154 location for the necessary cache of configuration and state
155 information, as well as a uniform API to the connection-oriented
156 facilities (searching, index browsing, etc.), provided by these
159 See the description of the C<Connection> class in the ZOOM Abstract
161 http://zoom.z3950.org/api/zoom-current.html#3.2
167 $conn = new ZOOM::Connection("indexdata.dk", 210);
168 $conn = new ZOOM::Connection("indexdata.dk:210/gils");
169 $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
170 $conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
171 $conn = new ZOOM::Connection("indexdata.dk", 210,
172 databaseName => "mydb",
173 preferredRecordSyntax => "marc");
175 Creates a new Connection object, and immediately connects it to the
176 specified server. If you want to make a new Connection object but
177 delay forging the connection, use the C<create()> and C<connect()>
180 This constructor can be called with two arguments or a single
181 argument. In the former case, the arguments are the name and port
182 number of the Z39.50 server to connect to; in the latter case, the
183 single argument is a YAZ service-specifier string of the form
185 When the two-option form is used (which may be done using a vacuous
186 second argument of zero), any number of additional argument pairs may
187 be provided, which are interpreted as key-value pairs to be set as
188 options after the Connection object is created but before it is
189 connected to the server. This is a convenient way to set options,
190 including those that must be set before connecting such as
191 authentication tokens.
193 The server-name string is of the form:
199 [I<scheme>:]I<host>[:I<port>][/I<databaseName>]
203 In which the I<host> and I<port> parts are as in the two-argument
204 form, the I<databaseName> if provided specifies the name of the
205 database to be used in subsequent searches on this connection, and the
206 optional I<scheme> (default C<tcp>) indicates what protocol should be
207 used. At present, the following schemes are supported:
217 Z39.50 connection encrypted using SSL (Secure Sockets Layer). Not
218 many servers support this, but Index Data's Zebra is one that does.
222 Z39.50 connection on a Unix-domain (local) socket, in which case the
223 I<hostname> portion of the string is instead used as a filename in the
228 SRU connection over HTTP.
232 If the C<http> scheme is used, the particular SRU flavour to be used
233 may be specified by the C<sru> option, which takes the following
240 SRU over SOAP (i.e. what used to be called SRW).
245 "SRU Classic" (i.e. SRU over HTTP GET).
253 If an error occurs, an exception is thrown. This may indicate a
254 networking problem (e.g. the host is not found or unreachable), or a
255 protocol-level problem (e.g. a Z39.50 server rejected the Init
258 =head4 create() / connect()
260 $options = new ZOOM::Options();
261 $options->option(implementationName => "my client");
262 $options->option(implementationId => 12345);
263 $conn = create ZOOM::Connection($options)
265 $conn = create ZOOM::Connection(implementationName => "my client",
266 implementationId => 12345);
268 $conn->connect($host, 0);
270 The usual Connection constructor, C<new()> brings a new object into
271 existence and forges the connection to the server all in one
272 operation, which is often what you want. For applications that need
273 more control, however, these two methods separate the two steps,
274 allowing additional steps in between such as the setting of options.
276 C<create()> creates and returns a new Connection object, which is
277 I<not> connected to any server. It may be passed an options block, of
278 type C<ZOOM::Options> (see below), into which options may be set
279 before or after the creation of the Connection. Alternatively and
280 equivalently, C<create()> may be passed a list of key-value option
281 pairs directly. The connection to the server may then be forged by
282 the C<connect()> method, the arguments of which are the same as those
283 of the C<new()> constructor.
285 =head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
287 ($errcode, $errmsg, $addinfo, $diagset) = $conn->error_x();
288 $errcode = $conn->errcode();
289 $errmsg = $conn->errmsg();
290 $addinfo = $conn->addinfo();
291 $diagset = $conn->diagset();
293 These methods may be used to obtain information about the last error
294 to have occurred on a connection - although typically they will not
295 been used, as the same information is available through the
296 C<ZOOM::Exception> that is thrown when the error occurs. The
302 methods each return one element of the diagnostic, and
304 returns all four at once.
306 See the C<ZOOM::Exception> for the interpretation of these elements.
308 =head4 option() / option_binary()
310 print("server is '", $conn->option("serverImplementationName"), "'\n");
311 $conn->option(preferredRecordSyntax => "usmarc");
312 $conn->option_binary(iconBlob => "foo\0bar");
313 die if length($conn->option_binary("iconBlob") != 7);
315 Objects of the Connection, ResultSet, ScanSet and Package classes
316 carry with them a set of named options which affect their behaviour in
317 certain ways. See the ZOOM-C options documentation for details:
319 Connection options are listed at
320 http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
322 These options are set and fetched using the C<option()> method, which
323 may be called with either one or two arguments. In the two-argument
324 form, the option named by the first argument is set to the value of
325 the second argument, and its old value is returned. In the
326 one-argument form, the value of the specified option is returned.
328 For historical reasons, option values are not binary-clean, so that a
329 value containing a NUL byte will be returned in truncated form. The
330 C<option_binary()> method behaves identically to C<option()> except
331 that it is binary-clean, so that values containing NUL bytes are set
332 and returned correctly.
334 =head4 search() / search_pqf()
336 $rs = $conn->search(new ZOOM::Query::CQL('title=dinosaur'));
337 # The next two lines are equivalent
338 $rs = $conn->search(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
339 $rs = $conn->search_pqf('@attr 1=4 dinosaur');
341 The principal purpose of a search-and-retrieve protocol is searching
342 (and, er, retrieval), so the principal method used on a Connection
343 object is C<search()>. It accepts a single argument, a C<ZOOM::Query>
344 object (or, more precisely, an object of a subclass of this class);
345 and it creates and returns a new ResultSet object representing the set
346 of records resulting from the search.
348 Since queries using PQF (Prefix Query Format) are so common, we make
349 them a special case by providing a C<search_pqf()> method. This is
350 identical to C<search()> except that it accepts a string containing
351 the query rather than an object, thereby obviating the need to create
352 a C<ZOOM::Query::PQF> object. See the documentation of that class for
353 information about PQF.
355 =head4 scan() / scan_pqf()
357 $rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur'));
358 # The next two lines are equivalent
359 $rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
360 $rs = $conn->scan_pqf('@attr 1=4 dinosaur');
362 Many Z39.50 servers allow you to browse their indexes to find terms to
363 search for. This is done using the C<scan> method, which creates and
364 returns a new ScanSet object representing the set of terms resulting
367 C<scan()> takes a single argument, but it has to work hard: it
368 specifies both what index to scan for terms, and where in the index to
369 start scanning. What's more, the specification of what index to scan
370 includes multiple facets, such as what database fields it's an index
371 of (author, subject, title, etc.) and whether to scan for whole fields
372 or single words (e.g. the title ``I<The Empire Strikes Back>'', or the
373 four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved
374 with words from other titles in the same index.
376 All of this is done by using a Query object representing a query of a
377 single term as the C<scan()> argument. The attributes associated with
378 the term indicate which index is to be used, and the term itself
379 indicates the point in the index at which to start the scan. For
380 example, if the argument is the query C<@attr 1=4 fish>, then
386 This is the BIB-1 attribute with type 1 (meaning access-point, which
387 specifies an index), and type 4 (which means ``title''). So the scan
388 is in the title index.
392 Start the scan from the lexicographically earliest term that is equal
393 to or falls after ``fish''.
397 The argument C<@attr 1=4 @attr 6=3 fish> would behave similarly; but
398 the BIB-1 attribute 6=3 mean completeness=``complete field'', so the
399 scan would be for complete titles rather than for words occurring in
402 This takes a bit of getting used to.
404 The behaviour is C<scan()> is affected by the following options, which
405 may be set on the Connection through which the scan is done:
409 =item number [default: 10]
411 Indicates how many terms should be returned in the ScanSet. The
412 number actually returned may be less, if the start-point is near the
413 end of the index, but will not be greater.
415 =item position [default: 1]
417 A 1-based index specifying where in the returned list of terms the
418 seed-term should appear. By default it should be the first term
419 returned, but C<position> may be set, for example, to zero (requesting
420 the next terms I<after> the seed-term), or to the same value as
421 C<number> (requesting the index terms I<before> the seed term).
423 =item stepSize [default: 0]
425 An integer indicating how many indexed terms are to be skipped between
426 each one returned in the ScanSet. By default, no terms are skipped,
427 but overriding this can be useful to get a high-level overview of the
430 Since scans using PQF (Prefix Query Format) are so common, we make
431 them a special case by providing a C<scan_pqf()> method. This is
432 identical to C<scan()> except that it accepts a string containing the
433 query rather than an object, thereby obviating the need to create a
434 C<ZOOM::Query::PQF> object.
440 $p = $conn->package();
441 $o = new ZOOM::Options();
442 $o->option(databaseName => "newdb");
443 $p = $conn->package($o);
445 Creates and returns a new C<ZOOM::Package>, to be used in invoking an
446 Extended Service. An options block may optionally be passed in. See
447 the C<ZOOM::Package> documentation.
451 if ($conn->last_event() == ZOOM::Event::CONNECT) {
452 print "Connected!\n";
455 Returns a C<ZOOM::Event> enumerated value indicating the type of the
456 last event that occurred on the connection. This is used only in
457 complex asynchronous applications - see the sections below on the
458 C<ZOOM::Event> enumeration and asynchronous applications.
464 Destroys a Connection object, tearing down any low-level connection
465 associated with it and freeing its resources. It is an error to reuse
466 a Connection that has been C<destroy()>ed.
468 =head2 ZOOM::ResultSet
470 $rs = $conn->search_pqf('@attr 1=4 mineral');
473 $rec = $rs->record($i-1);
474 print $rec->render();
477 A ResultSet object represents the set of zero or more records
478 resulting from a search, and is the means whereby these records can be
479 retrieved. A ResultSet object may maintain client side cache or some,
480 less, none, all or more of the server's records: in general, this is
481 supposed to an implementaton detail of no interest to a typical
482 application, although more sophisticated applications do have
483 facilities for messing with the cache. Most applications will only
484 need the C<size()>, C<record()> and C<sort()> methods.
486 There is no C<new()> method nor any other explicit constructor. The
487 only way to create a new ResultSet is by using C<search()> (or
488 C<search_pqf()>) on a Connection.
490 See the description of the C<Result Set> class in the ZOOM Abstract
492 http://zoom.z3950.org/api/zoom-current.html#3.4
498 $rs->option(elementSetName => "f");
500 Allows options to be set into, and read from, a ResultSet, just like
501 the Connection class's C<option()> method. There is no
502 C<option_binary()> method for ResultSet objects.
504 ResultSet options are listed at
505 http://indexdata.com/yaz/doc/zoom.resultsets.tkl
509 print "Found ", $rs->size(), " records\n";
511 Returns the number of records in the result set.
513 =head4 record() / record_immediate()
515 $rec = $rs->record(0);
516 $rec2 = $rs->record_immediate(0);
517 $rec3 = $rs->record_immediate(1)
518 or print "second record wasn't in cache\n";
520 The C<record()> method returns a C<ZOOM::Record> object representing
521 a record from result-set, whose position is indicated by the argument
522 passed in. This is a zero-based index, so that legitimate values
523 range from zero to C<$rs->size()-1>.
525 The C<record_immediate()> API is identical, but it never invokes a
526 network operation, merely returning the record from the ResultSet's
527 cache if it's already there, or an undefined value otherwise. So if
528 you use this method, B<you must always check the return value>.
532 $rs->records(0, 10, 0);
534 print $rs->record_immediate($i)->render();
537 @nextseven = $rs->records(10, 7, 1);
539 The C<record_immediate()> method only fetches records from the cache,
540 whereas C<record()> fetches them from the server if they have not
541 already been cached; but the ZOOM module has to guess what the most
542 efficient strategy for this is. It might fetch each record, alone
543 when asked for: that's optimal in an application that's only
544 interested in the top hit from each search, but pessimal for one that
545 wants to display a whole list of results. Conversely, the software's
546 strategy might be always to ask for blocks of a twenty records:
547 that's great for assembling long lists of things, but wasteful when
548 only one record is wanted. The problem is that the ZOOM module can't
549 tell, when you call C<$rs->record()>, what your intention is.
551 But you can tell it. The C<records()> method fetches a sequence of
552 records, all in one go. It takes three arguments: the first is the
553 zero-based index of the first record in the sequence, the second is
554 the number of records to fetch, and the third is a boolean indication
555 of whether or not to return the retrieved records as well as adding
556 them to the cache. (You can always pass 1 for this if you like, and
557 Perl will discard the unused return value, but there is a small
558 efficiency gain to be had by passing 0.)
560 Once the records have been retrieved from the server
561 (i.e. C<records()> has completed without throwing an exception), they
562 can be fetched much more efficiently using C<record()> - or
563 C<record_immediate()>, which is then guaranteed to succeed.
569 Resets the ResultSet's record cache, so that subsequent invocations of
570 C<record_immediate()> will fail. I struggle to imagine a real
571 scenario where you'd want to do this.
575 if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) {
579 Sorts the ResultSet in place (discarding any cached records, as they
580 will in general be sorted into a different position). There are two
581 arguments: the first is a string indicating the type of the
582 sort-specification, and the second is the specification itself.
584 The C<sort()> method returns 0 on success, or -1 if the
585 sort-specification is invalid.
587 At present, the only supported sort-specification type is C<yaz>.
588 Such a specification consists of a space-separated sequence of keys,
589 each of which itself consists of two space-separated words (so that
590 the total number of words in the sort-specification is even). The two
591 words making up each key are a field and a set of flags. The field
592 can take one of two forms: if it contains an C<=> sign, then it is a
593 BIB-1 I<type>=I<value> pair specifying which field to sort
594 (e.g. C<1=4> for a title sort); otherwise it is sent for the server to
595 interpret as best it can. The word of flags is made up from one or
596 more of the following: C<s> for case sensitive, C<i> for case
597 insensitive; C<<> for ascending order and C<E<gt>> for descending
600 For example, the sort-specification in the code-fragment above will
601 sort the records in C<$rs> case-insensitively in descending order of
602 title, with records having equivalent titles sorted case-sensitively
603 in ascending order of subject. (The BIB-1 access points 4 and 21
604 represent title and subject respectively.)
610 Destroys a ResultSet object, freeing its resources. It is an error to
611 reuse a ResultSet that has been C<destroy()>ed.
615 $rec = $rs->record($i);
616 print $rec->render();
618 $marc = new_from_usmarc MARC::Record($raw);
619 print "Record title is: ", $marc->title(), "\n";
621 A Record object represents a record that has been retrived from the
624 There is no C<new()> method nor any other explicit constructor. The
625 only way to create a new Record is by using C<record()> (or
626 C<record_immediate()>, or C<records()>) on a ResultSet.
628 In general, records are ``owned'' by their result-sets that they were
629 retrieved from, so they do not have to be explicitly memory-managed:
630 they are deallocated (and therefore can no longer be used) when the
631 result-set is destroyed.
633 See the description of the C<Record> class in the ZOOM Abstract
635 http://zoom.z3950.org/api/zoom-current.html#3.5
641 print $rec->render();
642 print $rec->render("charset=latin1,utf8");
644 Returns a human-readable representation of the record. Beyond that,
645 no promises are made: careful programs should not make assumptions
646 about the format of the returned string.
648 If the optional argument is provided, then it is interpreted as in the
649 C<get()> method (q.v.)
651 This method is useful mostly for debugging.
657 $marc = new_from_usmarc MARC::Record($raw);
658 $trans = $rec->render("charset=latin1,utf8");
660 Returns an opaque blob of data that is the raw form of the record.
661 Exactly what this is, and what you can do with it, varies depending on
662 the record-syntax. For example, XML records will be returned as,
663 well, XML; MARC records will be returned as ISO 2709-encoded blocks
664 that can be decoded by software such as the fine C<Marc::Record>
665 module; GRS-1 record will be ... gosh, what an interesting question.
666 But no-one uses GRS-1 any more, do they?
668 If the optional argument is provided, then it is interpreted as in the
669 C<get()> method (q.v.)
673 $raw = $rec->get("raw");
674 $rendered = $rec->get("render");
675 $trans = $rec->get("render;charset=latin1,utf8");
676 $trans = $rec->get("render", "charset=latin1,utf8");
678 This is the underlying method used by C<render()> and C<raw()>, and
679 which in turn delegates to the C<ZOOM_record_get()> function of the
680 underlying ZOOM-C library. Most applications will find it more
681 natural to work with C<render()> and C<raw()>.
683 C<get()> may be called with either one or two arguments. The
684 two-argument form is syntactic sugar: the two arguments are simply
685 joined with a semi-colon to make a single argument, so the third and
686 fourth example invocations above are equivalent. The second argument
687 (or portion of the first argument following the semicolon) is used in
688 the C<type> argument of C<ZOOM_record_get()>, as described in
689 http://www.indexdata.com/yaz/doc/zoom.records.tkl
690 This is useful primarily for invoking the character-set transformation
691 - in the examples above, from ISO Latin-1 to UTF-8 Unicode.
693 =head4 clone() / destroy()
695 $rec = $rs->record($i);
696 $newrec = $rec->clone();
698 print $newrec->render();
701 Usually, it's convenient that Record objects are owned by their
702 ResultSets and go away when the ResultSet is destroyed; but
703 occasionally you need a Record to outlive its parent and destroy it
704 later, explicitly. To do this, C<clone()> the record, keep the new
705 Record object that is returned, and C<destroy()> it when it's no
706 longer needed. This is B<only> situation in which a Record needs to
709 =head2 ZOOM::Exception
711 In general, method calls throw an exception (of class
712 C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
713 for success after each call. Exceptions are caught by enclosing the
714 main code in an C<eval{}> block and checking C<$@> on exit from that
715 block, as in the code-sample above.
717 There are a small number of exceptions to this rule: the three
718 record-fetching methods in the C<ZOOM::ResultSet> class,
720 C<record_immediate()>,
723 can all return undefined values for legitimate reasons, under
724 circumstances that do not merit throwing an exception. For this
725 reason, the return values of these methods should be checked. See the
726 individual methods' documentation for details.
728 An exception carries the following pieces of information:
734 A numeric code that specifies the type of error. This can be checked
735 for equality with known values, so that intelligent applications can
736 take appropriate action.
740 A human-readable message corresponding with the code. This can be
741 shown to users, but its value should not be tested, as it could vary
742 in different versions or under different locales.
744 =item additional information [optional]
746 A string containing information specific to the error-code. For
747 example, when the error-code is the BIB-1 diagnostic 109 ("Database
748 unavailable"), the additional information is the name of the database
749 that the application tried to use. For some error-codes, there is no
750 additional information at all; for some others, the additional
751 information is undefined and may just be an human-readable string.
753 =item diagnostic set [optional]
755 A short string specifying the diagnostic set from which the error-code
756 was drawn: for example, C<ZOOM> for a ZOOM-specific error such as
757 C<ZOOM::Error::MEMORY> ("out of memory"), and C<BIB-1> for a Z39.50
758 error-code drawn from the BIB-1 diagnostic set.
762 In theory, the error-code should be interpreted in the context of the
763 diagnostic set from which it is drawn; in practice, nearly all errors
764 are from either the ZOOM or BIB-1 diagnostic sets, and the codes in
765 those sets have been chosen so as not to overlap, so the diagnostic
766 set can usually be ignored.
768 See the description of the C<Exception> class in the ZOOM Abstract
770 http://zoom.z3950.org/api/zoom-current.html#3.7
776 die new ZOOM::Exception($errcode, $errmsg, $addinfo, $diagset);
778 Creates and returns a new Exception object with the specified
779 error-code, error-message, additional information and diagnostic set.
780 Applications will not in general need to use this, but may find it
781 useful to simulate ZOOM exceptions. As is usual with Perl, exceptions
782 are thrown using C<die()>.
784 =head4 code() / message() / addinfo() / diagset()
786 print "Error ", $@->code(), ": ", $@->message(), "\n";
787 print "(addinfo '", $@->addinfo(), "', set '", $@->diagset(), "')\n";
789 These methods, of no arguments, return the exception's error-code,
790 error-message, additional information and diagnostic set respectively.
796 Returns a human-readable rendition of an exception. The C<"">
797 operator is overloaded on the Exception class, so that an Exception
798 used in a string context is automatically rendered. Among other
799 consequences, this has the useful result that a ZOOM application that
800 died due to an uncaught exception will emit an informative message
805 $ss = $conn->scan('@attr 1=1003 a');
807 ($term, $occ) = $ss->term($n-1);
808 $rs = $conn->search_pqf('@attr 1=1003 "' . $term . "'");
809 assert($rs->size() == $occ);
811 A ScanSet represents a set of candidate search-terms returned from an
812 index scan. Its sole purpose is to provide access to those term, to
813 the corresponding display terms, and to the occurrence-counts of the
816 There is no C<new()> method nor any other explicit constructor. The
817 only way to create a new ScanSet is by using C<scan()> on a
820 See the description of the C<Scan Set> class in the ZOOM Abstract
822 http://zoom.z3950.org/api/zoom-current.html#3.6
828 print "Found ", $ss->size(), " terms\n";
830 Returns the number of terms in the scan set. In general, this will be
831 the scan-set size requested by the C<number> option in the Connection
832 on which the scan was performed [default 10], but it may be fewer if
833 the scan is close to the end of the index.
835 =head4 term() / display_term()
837 $ss = $conn->scan('@attr 1=1004 whatever');
838 ($term, $occurrences) = $ss->term(0);
839 ($displayTerm, $occurrences2) = $ss->display_term(0);
840 assert($occurrences == $occurrences2);
841 if (user_likes_the_look_of($displayTerm)) {
842 $rs = $conn->search_pqf('@attr 1=4 "' . $term . '"');
843 assert($rs->size() == $occurrences);
846 These methods return the scanned terms themselves. C<term()> returns
847 the term is a form suitable for submitting as part of a query, whereas
848 C<display_term()> returns it in a form suitable for displaying to a
849 user. Both versions also return the number of occurrences of the term
850 in the index, i.e. the number of hits that will be found if the term
851 is subsequently used in a query.
853 In most cases, the term and display term will be identical; however,
854 they may be different in cases where punctuation or case is
855 normalised, or where identifiers rather than the original document
860 print "scan status is ", $ss->option("scanStatus");
862 Allows options to be set into, and read from, a ScanSet, just like
863 the Connection class's C<option()> method. There is no
864 C<option_binary()> method for ScanSet objects.
866 ScanSet options are also described, though not particularly
868 http://indexdata.com/yaz/doc/zoom.scan.tkl
874 Destroys a ScanSet object, freeing its resources. It is an error to
875 reuse a ScanSet that has been C<destroy()>ed.
879 $p = $conn->package();
880 $p->option(action => "specialUpdate");
881 $p->option(recordIdOpaque => 145);
882 $p->option(record => content_of("/tmp/record.xml"));
886 This class represents an Extended Services Package: an instruction to
887 the server to do something not covered by the core parts of the Z39.50
888 standard (or the equivalent in SRW or SRU). Since the core protocols
889 are read-only, such requests are often used to make changes to the
890 database, such as in the record update example above.
892 Requesting an extended service is a four-step process: first, create a
893 package associated with the connection to the relevant database;
894 second, set options on the package to instruct the server on what to
895 do; third, send the package (which may result in an exception being
896 thrown if the server cannot execute the requested operations; and
897 finally, destroy the package.
899 Package options are listed at
900 http://indexdata.com/yaz/doc/zoom.ext.tkl
902 The particular options that have meaning are determined by the
903 top-level operation string specified as the argument to C<send()>.
904 For example, when the operation is C<update> (the most commonly used
905 extended service), the C<action> option may be set to any of
907 (add a new record, failing if that record already exists),
909 (delete a record, failing if it is not in the database).
911 (replace a record, failing if an old version is not already present)
914 (add a record, replacing any existing version that may be present).
916 For update, the C<record> option should be set to the full text of the
917 XML record to added, deleted or replaced. Depending on how the server
918 is configured, it may extract the record's unique ID from the text
919 (i.e. from a known element such as the C<001> field of a MARCXML
920 record), or it may require the unique ID to passed in explicitly using
921 the C<recordIdOpaque> option.
923 Extended services packages are B<not currently described> in the ZOOM
925 http://zoom.z3950.org/api/zoom-current.html
926 They will be added in a forthcoming version, and will function much
927 as those implemented in this module.
933 $p->option(recordIdOpaque => "46696f6e61");
935 Allows options to be set into, and read from, a Package, just like
936 the Connection class's C<option()> method. There is no
937 C<option_binary()> method for Package objects.
939 Package options are listed at
940 http://indexdata.com/yaz/doc/zoom.ext.tkl
946 Sends a package to the server associated with the Connection that
947 created it. Problems are reported by throwing an exception. The
948 single parameter indicates the operation that the server is being
949 requested to perform, and controls the interpretation of the package's
950 options. Valid operations include:
956 Request a copy of a nominated object, e.g. place an ILL request.
960 Create a new database, the name of which is specified by the
961 C<databaseName> option.
965 Drop an existing database, the name of which is specified by the
966 C<databaseName> option.
970 Commit changes made to the database within a transaction.
974 Modify the contents of the database by adding, deleting or replacing
975 records (as described above in the overview of the C<ZOOM::Package>
980 I have no idea what this does.
984 Although the module is capable of I<making> all these requests, not
985 all servers are capable of I<executing> them. Refusal is indicated by
986 throwing an exception. Problems may also be caused by lack of
987 privileges; so C<send()> must be used with caution, and is perhaps
988 best wrapped in a clause that checks for execptions, like so:
990 eval { $p->send("create") };
991 if ($@ && $@->isa("ZOOM::Exception")) {
992 print "Oops! ", $@->message(), "\n";
1000 Destroys a Package object, freeing its resources. It is an error to
1001 reuse a Package that has been C<destroy()>ed.
1005 $q = new ZOOM::Query::CQL("creator=pike and subject=unix");
1006 $q->sortby("1=4 >i 1=21 >s");
1007 $rs = $conn->search($q);
1010 C<ZOOM::Query> is a virtual base class from which various concrete
1011 subclasses can be derived. Different subclasses implement different
1012 types of query. The sole purpose of a Query object is to be used in a
1013 C<search()> on a Connection; because PQF is such a common special
1014 case, the shortcut Connection method C<search_pqf()> is provided.
1016 The following Query subclasses are provided, each providing the
1017 same set of methods described below:
1021 =item ZOOM::Query::PQF
1023 Implements Prefix Query Format (PQF), also sometimes known as Prefix
1024 Query Notation (PQN). This esoteric but rigorous and expressive
1025 format is described in the YAZ Manual at
1026 http://indexdata.com/yaz/doc/tools.tkl#PQF
1028 =item ZOOM::Query::CQL
1030 Implements the Common Query Language (CQL) of SRU, the Search/Retrieve
1031 URL. CQL is a much friendlier notation than PQF, using a simple infix
1032 notation. The queries are passed ``as is'' to the server rather than
1033 being compiled into a Z39.50 Type-1 query, so only CQL-compliant
1034 servers can support such querier. CQL is described at
1035 http://www.loc.gov/standards/sru/cql/
1036 and in a slight out-of-date but nevertheless useful tutorial at
1037 http://zing.z3950.org/cql/intro.html
1039 =item ZOOM::Query::CQL2RPN
1041 Implements CQL by compiling it on the client-side into a Z39.50
1042 Type-1 (RPN) query, and sending that. This provides essentially the
1043 same functionality as C<ZOOM::Query::CQL>, but it will work against
1044 any standard Z39.50 server rather than only against the small subset
1045 that support CQL natively. The drawback is that, because the
1046 compilation is done on the client side, a configuration file is
1047 required to direct the mapping of CQL constructs such as index names,
1048 relations and modifiers into Type-1 query attributes. An example CQL
1049 configuration file is included in the ZOOM-Perl distribution, in the
1050 file C<samples/cql/pqf.properties>
1052 =item ZOOM::Query::CCL2RPN
1054 Implements CCL by compiling it on the client-side into a Z39.50 Type-1
1055 (RPN) query, and sending that. Because the compilation is done on the
1056 client side, a configuration file is required to direct the mapping of
1057 CCL constructs such as index names and boolean operators into Type-1
1058 query attributes. An example CCL configuration file is included in
1059 the ZOOM-Perl distribution, in the file C<samples/ccl/default.bib>
1061 CCL is syntactically very similar to CQL, but much looser. While CQL
1062 is an entirely precise language in which each possible query has
1063 rigorously defined semantics, and is thus suitable for transfer as
1064 part of a protocol, CCL is best deployed as a human-facing UI
1069 See the description of the C<Query> class in the ZOOM Abstract
1071 http://zoom.z3950.org/api/zoom-current.html#3.3
1077 $q = new ZOOM::Query::CQL('title=dinosaur');
1078 $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur');
1080 Creates a new query object, compiling the query passed as its argument
1081 according to the rules of the particular query-type being
1082 instantiated. If compilation fails, an exception is thrown.
1083 Otherwise, the query may be passed to the C<Connection> method
1086 $conn->option(cqlfile => "samples/cql/pqf.properties");
1087 $q = new ZOOM::Query::CQL2RPN('title=dinosaur', $conn);
1089 Note that for the C<ZOOM::Query::CQL2RPN> subclass, the Connection
1090 must also be passed into the constructor. This is used for two
1091 purposes: first, its C<cqlfile> option is used to find the CQL
1092 configuration file that directs the translations into RPN; and second,
1093 if compilation fails, then diagnostic information is cached in the
1094 Connection and be retrieved using C<$conn-E<gt>errcode()> and related
1097 $conn->option(cclfile => "samples/ccl/default.bib");
1099 $conn->option(cclqual => "ti u=4 s=pw\nab u=62 s=pw");
1100 $q = new ZOOM::Query::CCL2RPN('ti=dinosaur', $conn);
1102 For the C<ZOOM::Query::CQL2RPN> subclass, too, the Connection must be
1103 passed into the constructor, for the same reasons as when client-side
1104 CQL compilation is used. The C<cclqual> option, if defined, gives a
1105 CCL qualification specification inline; otherwise, the contents of the
1106 file named by the C<cclfile> option are used.
1110 $q->sortby("1=4 >i 1=21 >s");
1112 Sets a sort specification into the query, so that when a C<search()>
1113 is run on the query, the result is automatically sorted. The sort
1114 specification language is the same as the C<yaz> sort-specification
1115 type of the C<ResultSet> method C<sort()>, described above.
1121 Destroys a Query object, freeing its resources. It is an error to
1122 reuse a Query that has been C<destroy()>ed.
1124 =head2 ZOOM::Options
1126 $o1 = new ZOOM::Options();
1127 $o1->option(user => "alf");
1128 $o2 = new ZOOM::Options();
1129 $o2->option(password => "fruit");
1130 $opts = new ZOOM::Options($o1, $o2);
1131 $conn = create ZOOM::Connection($opts);
1132 $conn->connect($host); # Uses the specified username and password
1134 Several classes of ZOOM objects carry their own sets of options, which
1135 can be manipulated using their C<option()> method. Sometimes,
1136 however, it's useful to deal with the option sets directly, and the
1137 C<ZOOM::Options> class exists to enable this approach.
1139 Option sets are B<not currently described> in the ZOOM
1141 http://zoom.z3950.org/api/zoom-current.html
1142 They are an extension to that specification.
1148 $o1 = new ZOOM::Options();
1149 $o1and2 = new ZOOM::Options($o1);
1150 $o3 = new ZOOM::Options();
1151 $o1and3and4 = new ZOOM::Options($o1, $o3);
1153 Creates and returns a new option set. One or two (but no more)
1154 existing option sets may be passed as arguments, in which case they
1155 become ``parents'' of the new set, which thereby ``inherits'' their
1156 options, the values of the first parent overriding those of the second
1157 when both have a value for the same key. An option set that inherits
1158 from a parent that has its own parents also inherits the grandparent's
1161 =head4 option() / option_binary()
1163 $o->option(preferredRecordSyntax => "usmarc");
1164 $o->option_binary(iconBlob => "foo\0bar");
1165 die if length($o->option_binary("iconBlob") != 7);
1167 These methods are used to get and set options within a set, and behave
1168 the same way as the same-named C<Connection> methods - see above. As
1169 with the C<Connection> methods, values passed to and retrieved using
1170 C<option()> are interpreted as NUL-terminated, while those passed to
1171 and retrieved from C<option_binary()> are binary-clean.
1175 $o->option(x => "T");
1176 $o->option(y => "F");
1177 assert($o->bool("x", 1));
1178 assert(!$o->bool("y", 1));
1179 assert($o->bool("z", 1));
1181 The first argument is a key, and the second is a default value.
1182 Returns the value associated with the specified key as a boolean, or
1183 the default value if the key has not been set. The values C<T> (upper
1184 case) and C<1> are considered true; all other values (including C<t>
1185 (lower case) and non-zero integers other than one) are considered
1188 This method is provided in ZOOM-C because in a statically typed
1189 language it's convenient to have the result returned as an
1190 easy-to-test type. In a dynamically typed language such as Perl, this
1191 problem doesn't arise, so C<bool()> is nearly useless; but it is made
1192 available in case applications need to duplicate the idiosyncratic
1193 interpretation of truth and falsehood and ZOOM-C uses.
1197 $o->option(x => "012");
1198 assert($o->int("x", 20) == 12);
1199 assert($o->int("y", 20) == 20);
1201 Returns the value associated with the specified key as an integer, or
1202 the default value if the key has not been set. See the description of
1203 C<bool()> for why you almost certainly don't want to use this.
1207 $o->set_int(x => "29");
1209 Sets the value of the specified option as an integer. Of course, Perl
1210 happily converts strings to integers on its own, so you can just use
1211 C<option()> for this, but C<set_int()> is guaranteed to use the same
1212 string-to-integer conversion as ZOOM-C does, which might occasionally
1213 be useful. Though I can't imagine how.
1215 =head4 set_callback()
1219 return "$udata-$key-$udata";
1221 $o->set_callback(\&cb, "xyz");
1222 assert($o->option("foo") eq "xyz-foo-xyz");
1224 This method allows a callback function to be installed in an option
1225 set, so that the values of options can be calculated algorithmically
1226 rather than, as usual, looked up in a table. Along with the callback
1227 function itself, an additional datum is provided: when an option is
1228 subsequently looked up, this datum is passed to the callback function
1229 along with the key; and its return value is returned to the caller as
1230 the value of the option.
1233 Although it ought to be possible to specify callback function using
1234 the C<\&name> syntax above, or a literal C<sub { code }> code
1235 reference, the complexities of the Perl-internal memory management
1236 system mean that the function must currently be specified as a string
1237 containing the fully-qualified name, e.g. C<"main::cb">.>
1240 The current implementation of the this method leaks memory, not only
1241 when the callback is installed, but on every occasion that it is
1242 consulted to look up an option value.
1248 Destroys an Options object, freeing its resources. It is an error to
1249 reuse an Options object that has been C<destroy()>ed.
1253 The ZOOM module provides two enumerations that list possible return
1254 values from particular functions. They are described in the following
1259 if ($@->code() == ZOOM::Error::QUERY_PQF) {
1260 return "your query was not accepted";
1263 This class provides a set of manifest constants representing some of
1264 the possible error codes that can be raised by the ZOOM module. The
1265 methods that return error-codes are
1266 C<ZOOM::Exception::code()>,
1267 C<ZOOM::Connection::error_x()>
1269 C<ZOOM::Connection::errcode()>.
1271 The C<ZOOM::Error> class provides the constants
1281 C<UNSUPPORTED_PROTOCOL>,
1282 C<UNSUPPORTED_QUERY>,
1297 each of which specifies a client-side error. These codes constitute
1298 the C<ZOOM> diagnostic set.
1300 Since errors may also be diagnosed by the server, and returned to the
1301 client, error codes may also take values from the BIB-1 diagnostic set
1302 of Z39.50, listed at the Z39.50 Maintenance Agency's web-site at
1303 http://www.loc.gov/z3950/agency/defns/bib1diag.html
1305 All error-codes, whether client-side from the C<ZOOM::Error>
1306 enumeration or server-side from the BIB-1 diagnostic set, can be
1307 translated into human-readable messages by passing them to the
1308 C<ZOOM::diag_str()> utility function.
1312 if ($conn->last_event() == ZOOM::Event::CONNECT) {
1313 print "Connected!\n";
1316 In applications that need it - mostly complex multiplexing
1317 applications - The C<ZOOM::Connection::last_event()> method is used to
1318 return an indication of the last event that occurred on a particular
1319 connection. It always returns a value drawn from this enumeration,
1320 that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
1321 C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD>,
1322 C<RECV_SEARCH> or C<ZEND>.
1324 See the section below on asynchronous applications.
1328 ZOOM::Log::init_level(ZOOM::Log::mask_str("zoom,myapp,-warn"));
1329 ZOOM::Log::log("myapp", "starting up with pid ", $$);
1331 Logging facilities are provided by a set of functions in the
1332 C<ZOOM::Log> module. Note that C<ZOOM::Log> is not a class, and it
1333 is not possible to create C<ZOOM::Log> objects: the API is imperative,
1334 reflecting that of the underlying YAZ logging facilities. Although
1335 there are nine logging functions altogether, you can ignore nearly
1336 all of them: most applications that use logging will begin by calling
1337 C<mask_str()> and C<init_level()> once each, as above, and will then
1338 repeatedly call C<log()>.
1342 $level = ZOOM::Log::mask_str("zoom,myapp,-warn");
1344 Returns an integer corresponding to the log-level specified by the
1345 parameter. This is a string of zero or more comma-separated
1346 module-names, each indicating an individual module to be either added
1347 to the default log-level or removed from it (for those components
1348 prefixed by a minus-sign). The names may be those of either standard
1349 YAZ-logging modules such as C<fatal>, C<debug> and C<warn>, or custom
1350 modules such as C<myapp> in the example above. The module C<zoom>
1351 requests logging from the ZOOM module itself, which may be helpful for
1354 Note that calling this function does not in any way change the logging
1355 state: it merely returns a value. To change the state, this value
1356 must be passed to C<init_level()>.
1358 =head2 module_level()
1360 $level = ZOOM::Log::module_level("zoom");
1361 ZOOM::Log::log($level, "all systems clear: thrusters invogriated");
1363 Returns the integer corresponding to the single log-level specified as
1364 the parameter, or zero if that level has not been registered by a
1365 prior call to C<mask_str()>. Since C<log()> accepts either a numeric
1366 log-level or a string, there is no reason to call this function; but,
1367 what the heck, maybe you enjoy that kind of thing. Who are we to
1372 ZOOM::Log::init_level($level);
1374 Initialises the log-level to the specified integer, which is a bitmask
1375 of values, typically as returned from C<mask_str()>. All subsequent
1376 calls to C<log()> made with a log-level that matches one of the bits
1377 in this mask will result in a log-message being emitted. All logging
1378 can be turned off by calling C<init_level(0)>.
1380 =head2 init_prefix()
1382 ZOOM::Log::init_prefix($0);
1384 Initialises a prefix string to be included in all log-messages.
1388 ZOOM::Log::init_file("/tmp/myapp.log");
1390 Initialises the output file to be used for logging: subsequent
1391 log-messages are written to the nominated file. If this function is
1392 not called, log-messages are written to the standard error stream.
1396 ZOOM::Log::init($level, $0, "/tmp/myapp.log");
1398 Initialises the log-level, the logging prefix and the logging output
1399 file in a single operation.
1401 =head2 time_format()
1403 ZOOM::Log::time_format("%Y-%m-%d %H:%M:%S");
1405 Sets the format in which log-messages' timestamps are emitted, by
1406 means of a format-string like that used in the C function
1407 C<strftime()>. The example above emits year, month, day, hours,
1408 minutes and seconds in big-endian order, such that timestamps can be
1409 sorted lexicographically.
1411 =head2 init_max_size()
1413 (This doesn't seem to work, so I won't bother describing it.)
1417 ZOOM::Log::log(8192, "reducing to warp-factor $wf");
1418 ZOOM::Log::log("myapp", "starting up with pid ", $$);
1420 Provided that the first argument, log-level, is among the modules
1421 previously established by C<init_level()>, this function emits a
1422 log-message made up of a timestamp, the prefix supplied to
1423 C<init_prefix()>, if any, and the concatenation of all arguments after
1424 the first. The message is written to the standard output stream, or
1425 to the file previous specified by C<init_file()> if this has been
1428 The log-level argument may be either a numeric value, as returned from
1429 C<module_level()>, or a string containing the module name.
1431 =head1 ASYNCHRONOUS APPLICATIONS
1433 Although asynchronous applications are conceptually complex, the ZOOM
1434 support for them is provided through a very simple interface,
1435 consisting of one option (C<async>), one function (C<ZOOM::event()>),
1436 one Connection method (C<last_event()> and an enumeration
1439 The approach is as follows:
1443 =item Initialisation
1445 Create several connections to the various servers, each of them having
1446 the option C<async> set, and with whatever additional options are
1447 required - e.g. the piggyback retrieval record-count can be set so
1448 that records will be returned in search responses.
1452 Send searches to the connections, request records, etc.
1454 =item Event harvesting
1456 Repeatedly call C<ZOOM::event()> to discover what responses are being
1457 received from the servers. Each time this function returns, it
1458 indicates which of the connections has fired; this connection can then
1459 be interrogated with the C<last_event()> method to discover what event
1460 has occurred, and the return value - an element of the C<ZOOM::Event>
1461 enumeration - can be tested to determine what to do next. For
1462 example, the C<ZEND> event indicates that no further operations are
1463 outstanding on the connection, so any fetched records can now be
1464 immediately obtained.
1468 Here is a very short program (omitting all error-checking!) which
1469 demonstrates this process. It parallel-searches three servers (or more
1470 of you add them the list), displaying the first record in the
1471 result-set of each server as soon as it becomes available.
1474 @servers = ('z3950.loc.gov:7090/Voyager',
1475 'z3950.indexdata.com:210/gils',
1476 'agricola.nal.usda.gov:7190/Voyager');
1477 for ($i = 0; $i < @servers; $i++) {
1478 $z[$i] = new ZOOM::Connection($servers[$i], 0,
1479 async => 1, # asynchronous mode
1480 count => 1, # piggyback retrieval count
1481 preferredRecordSyntax => "usmarc");
1482 $r[$i] = $z[$i]->search_pqf("mineral");
1484 while (($i = ZOOM::event(\@z)) != 0) {
1485 $ev = $z[$i-1]->last_event();
1486 print("connection ", $i-1, ": ", ZOOM::event_str($ev), "\n");
1487 if ($ev == ZOOM::Event::ZEND) {
1488 $size = $r[$i-1]->size();
1489 print "connection ", $i-1, ": $size hits\n";
1490 print $r[$i-1]->record(0)->render()
1497 The ZOOM abstract API,
1498 http://zoom.z3950.org/api/zoom-current.html
1500 The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
1502 The C<Net::Z3950> module, which this one supersedes.
1503 http://perl.z3950.org/
1505 The documentation for the ZOOM-C module of the YAZ Toolkit, which this
1506 module is built on. Specifically, its lists of options are useful.
1507 http://indexdata.com/yaz/doc/zoom.tkl
1509 The BIB-1 diagnostic set of Z39.50,
1510 http://www.loc.gov/z3950/agency/defns/bib1diag.html
1514 Mike Taylor, E<lt>mike@indexdata.comE<gt>
1516 =head1 COPYRIGHT AND LICENCE
1518 Copyright (C) 2005 by Index Data.
1520 This library is free software; you can redistribute it and/or modify
1521 it under the same terms as Perl itself, either Perl version 5.8.4 or,
1522 at your option, any later version of Perl 5 you may have available.