From: mike Date: Thu, 17 Nov 2005 15:31:06 +0000 (+0000) Subject: Finished section on the Connection class X-Git-Tag: cpan_1_22~347 X-Git-Url: http://lists.indexdata.com/cgi-bin?a=commitdiff_plain;h=400789c7f048c737c543e5c5f516bb0666cd1959;p=ZOOM-Perl-moved-to-github.git Finished section on the Connection class ... except discussion of Scan options. --- diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index 4fe8a3c..a57b3b9 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,4 +1,4 @@ -# $Id: ZOOM.pod,v 1.8 2005-11-17 13:32:30 mike Exp $ +# $Id: ZOOM.pod,v 1.9 2005-11-17 15:31:06 mike Exp $ use strict; use warnings; @@ -109,8 +109,7 @@ relevant section of the ZOOM Abstract API. $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- + $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()) @@ -239,6 +238,11 @@ See the C for the interpretation of these elements. =head4 option() / option_binary() + print("server is '", $conn->option("serverImplementationName"), "'\n"); + $conn->option(preferredRecordSyntax => "usmarc"); + $conn->option_binary(iconBlob => "foo\0bar"); + die if length($conn->option_binary("iconBlob") != 7); + Objects of the Connection, ResultSet, ScanSet and Package classes carry with them a set of named options which affect their behaviour in certain ways. See the ZOOM-C options documentation for details: @@ -254,19 +258,19 @@ http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections ResultSet options are listed at http://indexdata.com/yaz/doc/zoom.resultsets.tkl -I<### move this obvservation down the appropriate place> +I<### move this obvservation down to the appropriate place> =item * ScanSet options are listed at http://indexdata.com/yaz/doc/zoom.scan.tkl -I<### move this obvservation down the appropriate place> +I<### move this obvservation down to the appropriate place> =item * Package options are listed at http://indexdata.com/yaz/doc/zoom.ext.html -I<### move this obvservation down the appropriate place> +I<### move this obvservation down to the appropriate place> =back @@ -284,15 +288,83 @@ and returned correctly. =head4 search() / search_pqf() -I<###> + $rs = $conn->search(new ZOOM::Query::CQL('title=dinosaur')); + # The next two lines are equivalent + $rs = $conn->search(new ZOOM::Query::PQF('@attr 1=4 dinosaur')); + $rs = $conn->search_pqf('@attr 1=4 dinosaur'); + +The principal purpose of a search-and-retrieve protocol is searching +(and, er, retrieval), so the principal method used on a Connection +object is C. It accepts a single argument, a C +object (or, more precisely, an object of a subclass of this class); +and it creates and returns a new ResultSet object representing the set +of records resulting from the search. + +Since queries using PQF (Prefix Query Format) are so common, we make +them a special case by providing a C method. This is +identical to C except that it accepts a string containing +the query rather than an object, thereby obviating the need to create +a C object. See the documentation of that class for +information about PQF. =head4 scan() -I<###> +Many Z39.50 servers allow you to browse their indexes to find terms to +search for. This is done using the C method, which creates and +returns a new ScanSet object representing the set of terms resulting +from the scan. + +C takes a single argument, but it has to work hard: it +specifies both what index to scan for terms, and where in the index to +start scanning. What's more, the specification of what index to scan +includes multiple facets, such as what database fields it's an index +of (author, subject, title, etc.) and whether to scan for whole fields +or single words (e.g. the title ``I'', or the +four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved +with words from other titles in the same index. + +All of this is done by using a single term from the PQF query as the +C argument. (At present, only PQF is supported, although +there is no reason in principle why CQL and other query syntaxes +should not be supported in future). The attributes associated with +the term indicate which index is to be used, and the term itself +indicates the point in the index at which to start the scan. For +example, if the argument is C<@attr 1=4 fish>, then + +=over 4 + +=item @attr 1=4 + +This is the BIB-1 attribute with type 1 (meaning access-point, which +specifies an index), and type 4 (which means ``title''). So the scan +is in the title index. + +=item fish + +Start the scan from the lexicographically earliest term that is equal +to or falls after ``fish''. + +=back + +The argument C<@attr 1=4 @attr 6=3 fish> would behave similarly; but +the BIB-1 attribute 6=3 mean completeness=``complete field'', so the +scan would be for complete titles rather than for words occurring in +titles. + +This takes a bit of getting used to. + +I<###> discuss how the values of options affect scanning. =head4 package() -I<###> + $p = $conn->package(); + $o = new ZOOM::Options(); + $o->option(databaseName => "newdb"); + $p = $conn->package($o); + +Creates and returns a new C, to be used in invoking an +Extended Service. An options block may optionally be passed in. See +the C documentation. =head4 destroy() @@ -426,6 +498,7 @@ 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. +http://perl.z3950.org/ The documentation for the ZOOM-C module of the YAZ Toolkit, which this module is built on. Specifically, its lists of options are useful.