-# $Id: ZOOM.pod,v 1.3 2005-11-15 17:33:04 mike Exp $
+# $Id: ZOOM.pod,v 1.4 2005-11-16 14:54:43 mike Exp $
use strict;
use warnings;
=head1 DESCRIPTION
This module provides a nice, Perlish implementation of the ZOOM
-Abstract API described at http://zoom.z3950.org/api/
+Abstract API described and documented at http://zoom.z3950.org/api/
the ZOOM module is implemented as a set of thin classes on top of the
non-OO functions provided by this distribution's C<Net::Z3950::ZOOM>
and
C<ZOOM::Query::PQF>.
Many useful ZOOM applications can be built using only the Connection,
-ResultSet and Record classes, as in the example code-snippet above.
+ResultSet, Record and Exception classes, as in the example
+code-snippet above.
A typical application will begin by creating an Connection object,
then using that to execute searches that yield ResultSet objects, then
fetching records from the result-sets to yield Record objects. If an
error occurs, an Exception object is thrown and can be dealt with.
-More sophisticated applications might browse the server's indexes to
-create a ScanSet, from which indexed terms may be retrieved; others
+
+More sophisticated applications might also browse the server's indexes
+to create a ScanSet, from which indexed terms may be retrieved; others
might send ``Extended Services'' Packages to the server, to achieve
non-standard tasks such as database creation and record update.
Searching using a query syntax other than PQF can be done using an
may be manipulated independently of the objects they are associated
with using an Options object.
+In general, method calls throw an exception if anything goes wrong, so
+you don't need to test for success after each call. See the section
+below on the Exception class for details.
+
+=head1 UTILITY FUNCTION
+
+=head2 ZOOM::diag_str()
+
+ $msg = ZOOM::diag_str(ZOOM::Error::INVALID_QUERY);
+
+Returns a human-readable English-language string corresponding to the
+error code that is its own parameter. This works for any error-code
+returned from
+C<ZOOM::Exception::code()>,
+C<ZOOM::Connection::error_x()>
+or
+C<ZOOM::Connection::errcode()>,
+irrespective of whether it is a member of the C<ZOOM::Error>
+enumeration or drawn from the BIB-1 diagnostic set.
+
+=head1 CLASSES
+
+The eight ZOOM classes are described here in ``sensible order'':
+first, the four commonly used classes, in the he order that they will
+tend to be used in most programs (Connection, ResultSet, Record,
+Exception); then the four more esoteric classes in descending order of
+how often they are needed.
+
+With the exception of the Options class, which is an extension to the
+ZOOM model, the introduction to each class includes a link to the
+relevant section of the ZOOM Abstract API.
+
+=head2 ZOOM::Connection
+
+ $conn = new ZOOM::Connection("indexdata.dk:210/gils");
+ print("server is '", $conn->option("serverImplementationName"), "'\n");
+ $conn->option(preferredRecordSyntax => "usmarc");
+ $conn->option_binary(iconBlob => "foo\0bar");
+ $rs = $conn->search_pqf('@attr 1=4 mineral');
+ $ss = $conn->scan('@attr 1=1003 a');
+ if ($conn->errcode() != 0) {
+ die("somthing went wrong: " . $conn->errmsg())
+ }
+ $conn->destroy()
+
+This class represents a connection to an information retrieval server,
+using an IR protocol such as ANSI/NISO Z39.50, SRW (the
+Search/Retrieve Webservice), SRU (the Search/Retrieve URL) or
+OpenSearch. Not all of these protocols require a low-level connection
+to be maintained, but the Connection object nevertheless provides a
+location for the necessary cache of configuration and state
+information, as well as a uniform API to the connection-oriented
+facilities (searching, index browsing, etc.), provided by these
+protocols.
+
+See the description of the C<Connection> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.2
+
+=head3 Methods
+
+=head4 new()
+
+ $conn = new ZOOM::Connection("indexdata.dk", 210);
+ $conn = new ZOOM::Connection("indexdata.dk/gils:210");
+ $conn = new ZOOM::Connection("tcp:indexdata.dk/gils:210");
+ $conn = new ZOOM::Connection("http:indexdata.dk/gils:210");
+
+I<###>
+
+create
+connect
+error_x
+errcode
+errmsg
+addinfo
+option
+option_binary
+search
+search_pqf
+scan
+package
+destroy
+
+=head2 ZOOM::ResultSet
+
+I<###>
+
+=head2 ZOOM::Record
+
+I<###>
+
+=head2 ZOOM::Exception
+
+In general, method calls throw an exception (of class
+C<ZOOM::Exception>) if anything goes wrong, so you don't need to test
+for success after each call. Exceptions are caught by enclosing the
+main code in an C<eval{}> block and checking C<$@> on exit from that
+block, as in the code-sample above.
+
+There are a small number of exceptions to this rule.
+I<###>
+
+=head2 ZOOM::ScanSet
+
+I<###>
+
+=head2 ZOOM::Package
+
+I<###>
+
+=head2 ZOOM::Query
+
+I<###>
+
+=head2 ZOOM::Options
+
+I<###>
+
+=head1 ENUMERATIONS
+
+The ZOOM module provides two enumerations that list possible return
+values from particular functions. They are described in the following
+sections.
+
+=head2 ZOOM::Error
+
+ if ($@->code() == ZOOM::Error::QUERY_PQF) {
+ return "your query was not accepted";
+ }
+
+This class provides a set of manifest constants representing some of
+the possible error codes that can be raised by the ZOOM module. The
+methods that return error-codes are
+C<ZOOM::Exception::code()>,
+C<ZOOM::Connection::error_x()>
+and
+C<ZOOM::Connection::errcode()>.
+
+The C<ZOOM::Error> class provides the constants
+C<NONE>,
+C<CONNECT>,
+C<MEMORY>,
+C<ENCODE>,
+C<DECODE>,
+C<CONNECTION_LOST>,
+C<INIT>,
+C<INTERNAL>,
+C<TIMEOUT>,
+C<UNSUPPORTED_PROTOCOL>,
+C<UNSUPPORTED_QUERY>,
+C<INVALID_QUERY>,
+C<CREATE_QUERY>,
+C<QUERY_CQL>,
+C<QUERY_PQF>,
+C<SORTBY>,
+C<CLONE>
+and
+C<PACKAGE>,
+each of which specifies a client-side error. Since errors may also be
+diagnosed by the server, and returned to the client, error codes may
+also take values from the BIB-1 diagnostic set of Z39.50, listed at
+the Z39.50 Maintenance Agency's web-site at
+http://www.loc.gov/z3950/agency/defns/bib1diag.html
+
+All error-codes, whether client-side from the C<ZOOM::Error>
+enumeration or server-side from the BIB-1 diagnostic set, can be
+translated into human-readable messages by passing them to the
+C<ZOOM::diag_str()> utility function.
+
+=head2 ZOOM::Event
+
+ if ($conn->last_event() == ZOOM::Event::CONNECT) {
+ print "Connected!\n";
+ }
+
+In applications that need it - mostly complex multiplexing
+applications - The C<ZOOM::Connection::last_event()> method is used to
+return an indication of the last event that occurred on a particular
+connection. It always returns a value drawn from this enumeration,
+that is, one of C<NONE>, C<CONNECT>, C<SEND_DATA>, C<RECV_DATA>,
+C<TIMEOUT>, C<UNKNOWN>, C<SEND_APDU>, C<RECV_APDU>, C<RECV_RECORD> or
+C<RECV_SEARCH>.
+
+You almost certainly don't need to know about this. Frankly, I'm not
+sure how to use it myself.
=head1 SEE ALSO
+The ZOOM abstract API,
+http://zoom.z3950.org/api/zoom-current.html
+
The C<Net::Z3950::ZOOM> module, included in the same distribution as this one.
The C<Net::Z3950> module, which this one supersedes.
+The BIB-1 diagnostic set of Z39.50,
+http://www.loc.gov/z3950/agency/defns/bib1diag.html
+
=head1 AUTHOR
Mike Taylor, E<lt>mike@indexdata.comE<gt>
projects / ZOOM-Perl-moved-to-github.git / commitdiff