X-Git-Url: http://lists.indexdata.dk/cgi-bin?a=blobdiff_plain;f=lib%2FZOOM.pod;h=21a4a33763305b7a57205259de45d1f1a4c98c46;hb=604153dfdcbf8fb8434d8da4fdd613ad50967040;hp=28c3f81573a9a0d807a490f57b9a57f6d0a0289d;hpb=09bbcbee048a4b0183f1265f1e512851aa472ca8;p=ZOOM-Perl-moved-to-github.git diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index 28c3f81..21a4a33 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,4 +1,4 @@ -# $Id: ZOOM.pod,v 1.1 2005-11-09 11:32:12 mike Exp $ +# $Id: ZOOM.pod,v 1.5 2005-11-16 15:36:16 mike Exp $ use strict; use warnings; @@ -13,7 +13,7 @@ ZOOM - Perl extension implementing the ZOOM API for Information Retrieval eval { $conn = new ZOOM::Connection($host, $port) $conn->option(preferredRecordSyntax => "usmarc"); - $rs = $conn->search_pqf($query); + $rs = $conn->search_pqf('@attr 1=4 dinosaur'); $n = $rs->size(); print $rs->record(0)->render(); }; @@ -24,10 +24,11 @@ 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 the Net::Z3950::ZOOM module, which in +non-OO functions provided by this distribution's C +module, which in turn is a thin layer on top of the ZOOM-C code supplied as part of Index Data's YAZ Toolkit. Because ZOOM-C is also the underlying code that implements ZOOM bindings in C++, Visual Basic, Scheme, Ruby, .NET @@ -36,14 +37,293 @@ with those other implementations. (Of course, the point of a public API such as ZOOM is that all implementations should be compatible anyway; but knowing that the same code is running is reassuring.) -I<###> There is rather more to say here :-) +The ZOOM module provides two enumerations (C and +C), a single utility function C in the C +package itself, and eight classes: +C, +C, +C, +C, +C, +C, +C +and +C. +Of these, the Query class is abstract, and has two concrete +subclasses: +C +and +C. +Many useful ZOOM applications can be built using only the Connection, +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 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 +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