-# $Id: ZOOM.pod,v 1.20 2005-12-13 16:03:14 mike Exp $
+# $Id: ZOOM.pod,v 1.25 2005-12-21 00:25:51 mike Exp $
use strict;
use warnings;
anyway; but knowing that the same code is running is reassuring.)
The ZOOM module provides two enumerations (C<ZOOM::Error> and
-C<ZOOM::Event>), a single utility function C<diag_str()> in the C<ZOOM>
-package itself, and eight classes:
+C<ZOOM::Event>), two utility functions C<diag_str()> and C<event()> in
+the C<ZOOM> package itself, and eight classes:
C<ZOOM::Exception>,
C<ZOOM::Options>,
C<ZOOM::Connection>,
you don't need to test for success after each call. See the section
below on the Exception class for details.
-=head1 UTILITY FUNCTION
+=head1 UTILITY FUNCTIONS
=head2 ZOOM::diag_str()
irrespective of whether it is a member of the C<ZOOM::Error>
enumeration or drawn from the BIB-1 diagnostic set.
+=head2 ZOOM::event()
+
+B<Warning.>
+Lark's vomit. Do not read this section.
+
+ $which = ZOOM::event([ $conn1, $conn2, $conn3 ]);
+
+Used only in complex asynchronous applications, this function takes a
+reference to a list of Connection objects, waits until an event
+occurs on any one of them, and returns an integer indicating which of
+the connections it occurred on. The return value is a 1-based index
+into the list; 0 is returned if no event occurs within the longest
+timeout specified by the C<timeout> options of all the connections.
+
+B<Warning.>
+This function is not yet implemented.
+
=head1 CLASSES
The eight ZOOM classes are described here in ``sensible order'':
of records resulting from the search.
Since queries using PQF (Prefix Query Format) are so common, we make
-them a special case by providing a C<search_prefix()> method. This is
+them a special case by providing a C<search_pqf()> method. This is
identical to C<search()> except that it accepts a string containing
the query rather than an object, thereby obviating the need to create
a C<ZOOM::Query::PQF> object. See the documentation of that class for
information about PQF.
-=head4 scan()
+=head4 scan() / scan_pqf()
+
+ $rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur'));
+ # The next two lines are equivalent
+ $rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+ $rs = $conn->scan_pqf('@attr 1=4 dinosaur');
Many Z39.50 servers allow you to browse their indexes to find terms to
search for. This is done using the C<scan> method, which creates and
four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved
with words from other titles in the same index.
-All of this is done by using a single term from the PQF query as the
-C<scan()> argument. (At present, only PQF is supported, although
-there is no reason in principle why CQL and other query syntaxes
-should not be supported in future). The attributes associated with
+All of this is done by using a Query object representing a query of a
+single term as the C<scan()> argument. The attributes associated with
the term indicate which index is to be used, and the term itself
indicates the point in the index at which to start the scan. For
-example, if the argument is C<@attr 1=4 fish>, then
+example, if the argument is the query C<@attr 1=4 fish>, then
=over 4
but overriding this can be useful to get a high-level overview of the
index.
+Since scans using PQF (Prefix Query Format) are so common, we make
+them a special case by providing a C<scan_pqf()> method. This is
+identical to C<scan()> except that it accepts a string containing the
+query rather than an object, thereby obviating the need to create a
+C<ZOOM::Query::PQF> object.
+
=back
=head4 package()
Extended Service. An options block may optionally be passed in. See
the C<ZOOM::Package> documentation.
+=head4 last_event()
+
+ if ($conn->last_event() == ZOOM::Event::CONNECT) {
+ print "Connected!\n";
+ }
+
+Returns a C<ZOOM::Event> enumerated value indicating the type of the
+last event that occurred on the connection. This is used only in
+complex asynchronous applications - see the section below on
+C<ZOOM::Event> for more information.
+
+B<Warning.>
+This method has not been tested.
+
=head4 destroy()
$conn->destroy()
There is no C<new()> method nor any other explicit constructor. The
only way to create a new ResultSet is by using C<search()> (or
-C<search_prefix()>) on a Connection.
+C<search_pqf()>) on a Connection.
See the description of the C<Result Set> class in the ZOOM Abstract
API at
specification language is the same as the C<yaz> sort-specification
type of the C<ResultSet> method C<sort()>, described above.
-B<It ought to be possible to sort by CQL query, too, but at present
-limitations in the underlying ZOOM-C library make this impossible.>
-
=head4 destroy()
$p->destroy()
=head4 set_callback()
-I<###>
+ sub cb {
+ ($udata, $key) = @;
+ return "$udata-$key-$udata";
+ }
+ $o->set_callback(\&cb, "xyz");
+ assert($o->option("foo") eq "xyz-foo-xyz");
+
+This method allows a callback function to be installed in an option
+set, so that the values of options can be calculated algorithmically
+rather than, as usual, looked up in a table. Along with the callback
+function itself, an additional datum is provided: when an option is
+subsequently looked up, this datum is passed to the callback function
+along with the key; and its return value is returned to the caller as
+the value of the option.
+
+B<Warning.>
+Although it ought to be possible to specify callback function using
+the C<\&name> syntax above, or a literal C<sub { code }> code
+reference, the complexities of the Perl-internal memory management
+system mean that the function must currently be specified as a string
+containing the fully-qualified name, e.g. C<"main::cb">.>
+
+B<Warning.>
+The current implementation of the this method leaks memory, not only
+when the callback is installed, but on every occasion that it is
+consulted to look up an option value.
=head4 destroy()
projects / ZOOM-Perl-moved-to-github.git / blobdiff