X-Git-Url: http://lists.indexdata.dk/cgi-bin?a=blobdiff_plain;f=lib%2FZOOM.pod;h=21a4a33763305b7a57205259de45d1f1a4c98c46;hb=604153dfdcbf8fb8434d8da4fdd613ad50967040;hp=cfb636e36fd6a1631730161c979212986240f65b;hpb=14730a133330573976fc1b14459984b7311ad0e5;p=ZOOM-Perl-moved-to-github.git diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index cfb636e..21a4a33 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.5 2005-11-16 15:36:16 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,258 @@ 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');/usr/local/src/mike/records/acc-ounts/cheques- + $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:210/gils"); + $conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils"); + $conn = new ZOOM::Connection("http:indexdata.dk:210/gils"); + +Creates a new Connection object, and immediately connects it to the +specified server. If you want to make a new Connection object but +delay forging the connection, use the C and C +methods instead. + +This constructor can be called with two arguments or a single +argument. In the former case, the arguments are the name and port +number of the Z39.50 server to connect to; in the latter case, the +single argument is a YAZ service-specifier string of the form + +=over 4 + +=item + +[I:]I[:I][/I] + +=back + +In which the I and I parts are as in the two-argument +form, the I if provided specifies the name of the +database to be used in subsequent searches on this connection, and the +optional I (default C) indicates what protocol should be +used. At present, the following schemes are supported: + +=over 4 + +=item tcp + +Z39.50 connection. + +=item ssl + +Z39.50 connection encrypted using SSL (Secure Sockets Layer). Not +many servers support this, but Index Data's Zebra is one that does. + +=item unix + +Z39.50 connection on a Unix-domain (local) socket, in which case the +I portion of the string is instead used as a filename in the +local filesystem. + +=item http + +SRW connection using SOAP over HTTP. + +=back + +Support for SRU will follow in the fullness of time. + +=head4 create() + +=head4 connect() + +=head4 error_x() / errcode() / errmsg() / addinfo() + +=head4 option() / option_binary() + +=head4 search() / search_pqf() + +=head4 scan() + +=head4 package() + +=head4 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 documentation for the ZOOM-C module of the YAZ Toolkit, which this +module is built on. Specifically, its lists of options are useful. +http://indexdata.com/yaz/doc/zoom.tkl + +The BIB-1 diagnostic set of Z39.50, +http://www.loc.gov/z3950/agency/defns/bib1diag.html + =head1 AUTHOR Mike Taylor, Emike@indexdata.comE