From 082de6827362c1ec90de4f1c003ed0629c899ba9 Mon Sep 17 00:00:00 2001 From: mike Date: Wed, 16 Nov 2005 14:54:43 +0000 Subject: [PATCH] Many huge changes. --- lib/ZOOM.pod | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 199 insertions(+), 5 deletions(-) diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index cfb636e..da85d4a 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,4 +1,4 @@ -# $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; @@ -24,7 +24,7 @@ ZOOM - Perl extension implementing the ZOOM API for Information Retrieval =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 @@ -55,14 +55,16 @@ C and C. 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 @@ -70,13 +72,205 @@ query object of one of the Query subclasses. Finally, sets of options 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, +C +or +C, +irrespective of whether it is a member of the C +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 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) 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 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, +C +and +C. + +The C class provides the constants +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C, +C +and +C, +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 +enumeration or server-side from the BIB-1 diagnostic set, can be +translated into human-readable messages by passing them to the +C 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 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, C, C, C, +C, C, C, C, C or +C. + +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 module, included in the same distribution as this one. The C 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, Emike@indexdata.comE -- 1.7.10.4