-# $Id: ZOOM.pod,v 1.12 2005-11-26 16:59:53 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'':
carry with them a set of named options which affect their behaviour in
certain ways. See the ZOOM-C options documentation for details:
-=over 4
-
-=item *
-
Connection options are listed at
http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
-=item *
-
-ScanSet options are listed at
-http://indexdata.com/yaz/doc/zoom.scan.tkl
-I<### move this obvservation down to the appropriate place>
-
-=item *
-
-Package options are listed at
-http://indexdata.com/yaz/doc/zoom.ext.html
-I<### move this obvservation down to the appropriate place>
-
-=back
-
These options are set and fetched using the C<option()> method, which
may be called with either one or two arguments. In the two-argument
form, the option named by the first argument is set to the value of
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
=head4 option()
- $conn->option(elementSetName => "f");
+ $rs->option(elementSetName => "f");
-Allows options to be set into, and read from a ResultSet, just like
+Allows options to be set into, and read from, a ResultSet, just like
the Connection class's C<option()> method. There is no
C<option_binary()> method for ResultSet objects.
Returns the number of records in the result set.
-=head4 record(), record_immediate()
+=head4 record() / record_immediate()
$rec = $rs->record(0);
$rec2 = $rs->record_immediate(0);
Once the records have been retrieved from the server
(i.e. C<records()> has completed without throwing an exception), they
can be fetched much more efficiently using C<record()> - or
-C<record_immediate(), which is then guaranteed to succeed.
+C<record_immediate()>, which is then guaranteed to succeed.
=head4 cache_reset()
print "Found ", $ss->size(), " terms\n";
-Returns the number of terms in the scan set.
-### describe option that affects this.
+Returns the number of terms in the scan set. In general, this will be
+the scan-set size requested by the C<number> option in the Connection
+on which the scan was performed [default 10], but it may be fewer if
+the scan is close to the end of the index.
=head4 term() / display_term()
-I<###>
+ $ss = $conn->scan('@attr 1=1004 whatever');
+ ($term, $occurrences) = $ss->term(0);
+ ($displayTerm, $occurrences2) = $ss->display_term(0);
+ assert($occurrences == $occurrences2);
+ if (user_likes_the_look_of($displayTerm)) {
+ $rs = $conn->search_pqf('@attr 1=4 "' . $term . '"');
+ assert($rs->size() == $occurrences);
+ }
+
+These methods return the scanned terms themselves. C<term()> returns
+the term is a form suitable for submitting as part of a query, whereas
+C<display_term()> returns it in a form suitable for displaying to a
+user. Both versions also return the number of occurrences of the term
+in the index, i.e. the number of hits that will be found if the term
+is subsequently used in a query.
+
+In most cases, the term and display term will be identical; however,
+they may be different in cases where punctuation or case is
+normalised, or where identifiers rather than the original document
+terms are indexed.
=head4 option()
-I<###>
+ print "scan status is ", $ss->option("scanStatus");
+
+Allows options to be set into, and read from, a ScanSet, just like
+the Connection class's C<option()> method. There is no
+C<option_binary()> method for ScanSet objects.
+
+ScanSet options are also described, though not particularly
+informatively, at
+http://indexdata.com/yaz/doc/zoom.scan.tkl
=head4 destroy()
-I<###>
+ $ss->destroy()
+
+Destroys a ScanSet object, freeing its resources. It is an error to
+reuse a ScanSet that has been C<destroy()>ed.
=head2 ZOOM::Package
-I<###>
+ $p = $conn->package();
+ $p->option(action => "specialUpdate");
+ $p->option(recordIdOpaque => 145);
+ $p->option(record => content_of("/tmp/record.xml"));
+ $p->send("update");
+ $p->destroy();
+
+This class represents an Extended Services Package: an instruction to
+the server to do something not covered by the core parts of the Z39.50
+standard (or the equivalent in SRW or SRU). Since the core protocols
+are read-only, such requests are often used to make changes to the
+database, such as in the record update example above.
+
+Requesting an extended service is a four-step process: first, create a
+package associated with the connection to the relevant database;
+second, set options on the package to instruct the server on what to
+do; third, send the package (which may result in an exception being
+thrown if the server cannot execute the requested operations; and
+finally, destroy the package.
+
+Package options are listed at
+http://indexdata.com/yaz/doc/zoom.ext.html
+
+The particular options that have meaning are determined by the
+top-level operation string specified as the argument to C<send()>.
+For example, when the operation is C<update> (the most commonly used
+extended service), the C<action> option may be set to any of
+C<recordInsert>
+(add a new record, failing if that record already exists),
+C<recordDelete>
+(delete a record, failing if it is not in the database).
+C<recordReplace>
+(replace a record, failing if an old version is not already present)
+or
+C<specialUpdate>
+(add a record, replacing any existing version that may be present).
+
+For update, the C<record> option should be set to the full text of the
+XML record to added, deleted or replaced. Depending on how the server
+is configured, it may extract the record's unique ID from the text
+(i.e. from a known element such as the C<001> field of a MARCXML
+record), or it may require the unique ID to passed in explicitly using
+the C<recordIdOpaque> option.
+
+Extended services packages are B<not currently described> in the ZOOM
+Abstract API at
+http://zoom.z3950.org/api/zoom-current.html
+They will be added in a forthcoming version, and will function much
+as those implemented in this module.
+
+=head3 Methods
+
+=head4 option()
+
+ $p->option(recordIdOpaque => "46696f6e61");
+
+Allows options to be set into, and read from, a Package, just like
+the Connection class's C<option()> method. There is no
+C<option_binary()> method for Package objects.
+
+Package options are listed at
+http://indexdata.com/yaz/doc/zoom.ext.tkl
+
+=head4 send()
+
+ $p->send("createdb");
+
+Sends a package to the server associated with the Connection that
+created it. Problems are reported by throwing an exception. The
+single parameter indicates the operation that the server is being
+requested to perform, and controls the interpretation of the package's
+options. Valid operations include:
+
+=over 4
+
+=item itemorder
+
+Request a copy of a nominated object, e.g. place an ILL request.
+
+=item create
+
+Create a new database, the name of which is specified by the
+C<databaseName> option.
+
+=item drop
+
+Drop an existing database, the name of which is specified by the
+C<databaseName> option.
+
+=item commit
+
+Commit changes made to the database within a transaction.
+
+=item update
+
+Modify the contents of the database by adding, deleting or replacing
+records (as described above in the overview of the C<ZOOM::Package>
+class).
+
+=item xmlupdate
+
+I have no idea what this does.
+
+=back
+
+Although the module is capable of I<making> all these requests, not
+all servers are capable of I<executing> them. Refusal is indicated by
+throwing an exception. Problems may also be caused by lack of
+privileges; so C<send()> must be used with caution, and is perhaps
+best wrapped in a clause that checks for execptions, like so:
+
+ eval { $p->send("create") };
+ if ($@ && $@->isa("ZOOM::Exception")) {
+ print "Oops! ", $@->message(), "\n";
+ return $@->code();
+ }
+
+=head4 destroy()
+
+ $p->destroy()
+
+Destroys a Package object, freeing its resources. It is an error to
+reuse a Package that has been C<destroy()>ed.
=head2 ZOOM::Query
-I<###>
+ $q = new ZOOM::Query::CQL("creator=pike and subject=unix");
+ $q->sortby("1=4 >i 1=21 >s");
+ $rs = $conn->search($q);
+ $q->destroy();
+
+C<ZOOM::Query> is a virtual base class from which various concrete
+subclasses can be derived. Different subclasses implement different
+types of query. The sole purpose of a Query object is to be used in a
+C<search()> on a Connection; because PQF is such a common special
+case, the shortcut Connection method C<search_pqf()> is provided.
+
+The following Query subclasses are provided, both of the providing the
+same set of methods described below:
+
+=over 4
+
+=item ZOOM::Query::PQF
+
+Implements Prefix Query Format (PQF), also sometimes known as Prefix
+Query Notation (PQN). This esoteric but rigorous and expressive
+format is described in the YAZ Manual at
+http://indexdata.com/yaz/doc/tools.tkl#PQF
+
+=item ZOOM::Query::CQL
+
+Implements the Common Query Language (CQL) of SRU, the Search/Retrieve
+URL. CQL is a much friendlier notation than PQF, using a simple infix
+notation. The queries are passed ``as is'' to the server rather than
+being compiled into a Z39.50 Type-1 query, so only CQL-compliant
+servers can support such querier. CQL is described at
+http://www.loc.gov/standards/sru/cql/
+and in a slight out-of-date but nevertheless useful tutorial at
+http://zing.z3950.org/cql/intro.html
+
+=back
+
+See the description of the C<Query> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.3
+
+=head3 Methods
+
+=head4 new()
+
+ $q = new ZOOM::Query::CQL('title=dinosaur'));
+ $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+
+Creates a new query object, compiling the query passed as its argument
+according to the rules of the particular query-type being
+instantiated. If compilation fails, an exception is thrown.
+Otherwise, the query may be passed to the C<Connection> method
+<search()>.
+
+=head4 sortby()
+
+ $q->sortby("1=4 >i 1=21 >s");
+
+Sets a sort specification into the query, so that when a C<search()>
+is run on the query, the result is automatically sorted. The sort
+specification language is the same as the C<yaz> sort-specification
+type of the C<ResultSet> method C<sort()>, described above.
+
+=head4 destroy()
+
+ $p->destroy()
+
+Destroys a Query object, freeing its resources. It is an error to
+reuse a Query that has been C<destroy()>ed.
=head2 ZOOM::Options
-I<###>
+ $o1 = new ZOOM::Options();
+ $o1->option(user => "alf");
+ $o2 = new ZOOM::Options();
+ $o2->option(password => "fruit");
+ $opts = new ZOOM::Options($o1, $o2);
+ $conn = create ZOOM::Connection($opts);
+ $conn->connect($host); # Uses the specified username and password
+
+Several classes of ZOOM objects carry their own sets of options, which
+can be manipulated using their C<option()> method. Sometimes,
+however, it's useful to deal with the option sets directly, and the
+C<ZOOM::Options> class exists to enable this approach.
+
+Option sets are B<not currently described> in the ZOOM
+Abstract API at
+http://zoom.z3950.org/api/zoom-current.html
+They are an extension to that specification.
+
+=head3 Methods
+
+=head4 new()
+
+ $o1 = new ZOOM::Options();
+ $o1and2 = new ZOOM::Options($o1);
+ $o3 = new ZOOM::Options();
+ $o1and3and4 = new ZOOM::Options($o1, $o3);
+
+Creates and returns a new option set. One or two (but no more)
+existing option sets may be passed as arguments, in which case they
+become ``parents'' of the new set, which thereby ``inherits'' their
+options, the values of the first parent overriding those of the second
+when both have a value for the same key. An option set that inherits
+from a parent that has its own parents also inherits the grandparent's
+options, and so on.
+
+=head4 option() / option_binary()
+
+ $o->option(preferredRecordSyntax => "usmarc");
+ $o->option_binary(iconBlob => "foo\0bar");
+ die if length($o->option_binary("iconBlob") != 7);
+
+These methods are used to get and set options within a set, and behave
+the same way as the same-named C<Connection> methods - see above. As
+with the C<Connection> methods, values passed to and retrieved using
+C<option()> are interpreted as NUL-terminated, while those passed to
+and retrieved from C<option_binary()> are binary-clean.
+
+=head4 bool()
+
+ $o->option(x => "T");
+ $o->option(y => "F");
+ assert($o->bool("x", 1));
+ assert(!$o->bool("y", 1));
+ assert($o->bool("z", 1));
+
+The first argument is a key, and the second is a default value.
+Returns the value associated with the specified key as a boolean, or
+the default value if the key has not been set. The values C<T> (upper
+case) and C<1> are considered true; all other values (including C<t>
+(lower case) and non-zero integers other than one) are considered
+false.
+
+This method is provided in ZOOM-C because in a statically typed
+language it's convenient to have the result returned as an
+easy-to-test type. In a dynamically typed language such as Perl, this
+problem doesn't arise, so C<bool()> is nearly useless; but it is made
+available in case applications need to duplicate the idiosyncratic
+interpretation of truth and falsehood and ZOOM-C uses.
+
+=head4 int()
+
+ $o->option(x => "012");
+ assert($o->int("x", 20) == 12);
+ assert($o->int("y", 20) == 20);
+
+Returns the value associated with the specified key as an integer, or
+the default value if the key has not been set. See the description of
+C<bool()> for why you almost certainly don't want to use this.
+
+=head4 set_int()
+
+ $o->set_int(x => "29");
+
+Sets the value of the specified option as an integer. Of course, Perl
+happily converts strings to integers on its own, so you can just use
+C<option()> for this, but C<set_int()> is guaranteed to use the same
+string-to-integer conversion as ZOOM-C does, which might occasionally
+be useful. Though I can't imagine how.
+
+=head4 set_callback()
+
+ 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()
+
+ $o->destroy()
+
+Destroys an Options object, freeing its resources. It is an error to
+reuse an Options object that has been C<destroy()>ed.
=head1 ENUMERATIONS