-# $Id: ZOOM.pod,v 1.15 2005-12-13 12:32:15 mike Exp $
+# $Id: ZOOM.pod,v 1.23 2005-12-19 17:42:15 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'':
a C<ZOOM::Query::PQF> object. See the documentation of that class for
information about PQF.
-=head4 scan()
+=head4 scan() / scan1()
+
+ ### Code sample needed here!
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
but overriding this can be useful to get a high-level overview of the
index.
+The C<scan1()> method is the same as C<scan()> except that it takes a
+Query object as its argument instead of a PQF string. This means
+that it can be used to scan using a CQL term, so long as the
+underlying ZOOM-C library supports this.
+
=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()
$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.
print "scan status is ", $ss->option("scanStatus");
-Allows options to be set into, and read from a ScanSet, just like
+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.
=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.
+
+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()
+
+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