X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=lib%2FZOOM.pod;h=867c528dc1c33aeadd2e53ff0036d16fe655e64e;hb=6795d689424605833b03f6269e95b8b0cd3a1757;hp=dbc7ae4e4c07d396d94c819ca3656aca73da27fc;hpb=5f457cb130c69411228cf63ed18bc1eaa579261a;p=ZOOM-Perl-moved-to-github.git diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index dbc7ae4..867c528 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,4 +1,4 @@ -# $Id: ZOOM.pod,v 1.34 2006-04-12 08:49:20 mike Exp $ +# $Id: ZOOM.pod,v 1.39 2006-11-03 09:36:28 mike Exp $ use strict; use warnings; @@ -39,8 +39,8 @@ API such as ZOOM is that all implementations should be compatible anyway; but knowing that the same code is running is reassuring.) The ZOOM module provides two enumerations (C and -C), two utility functions C and C in -the C package itself, and eight classes: +C), three utility functions C, C +and C in the C package itself, and eight classes: C, C, C, @@ -50,12 +50,13 @@ C, C and C. -Of these, the Query class is abstract, and has three concrete +Of these, the Query class is abstract, and has four concrete subclasses: C, -C +C, +C and -C. +C. Finally, it also provides a C module which supplies a useful general-purpose logging facility. @@ -97,6 +98,14 @@ C, irrespective of whether it is a member of the C enumeration or drawn from the BIB-1 diagnostic set. +=head2 ZOOM::event_str() + + $msg = ZOOM::event_str(ZOOM::Event::RECV_APDU); + +Returns a human-readable English-language string corresponding to the +event code that is its own parameter. This works for any value of the +C enumeration. + =head2 ZOOM::event() $connsRef = [ $conn1, $conn2, $conn3 ]; @@ -181,6 +190,8 @@ connected to the server. This is a convenient way to set options, including those that must be set before connecting such as authentication tokens. +The server-name string is of the form: + =over 4 =item @@ -214,11 +225,30 @@ local filesystem. =item http -SRW connection using SOAP over HTTP. +SRU connection over HTTP. =back -Support for SRU will follow in the fullness of time. +If the C scheme is used, the particular SRU flavour to be used +may be specified by the C option, which takes the following +values: + +=over 4 + +=item soap + +SRU over SOAP (i.e. what used to be called SRW). +This is the default. + +=item get + +"SRU Classic" (i.e. SRU over HTTP GET). + +=item post + +SRU over HTTP POST. + +=back If an error occurs, an exception is thrown. This may indicate a networking problem (e.g. the host is not found or unreachable), or a @@ -229,21 +259,28 @@ request). $options = new ZOOM::Options(); $options->option(implementationName => "my client"); + $options->option(implementationId => 12345); $conn = create ZOOM::Connection($options) + # or + $conn = create ZOOM::Connection(implementationName => "my client", + implementationId => 12345); + $conn->connect($host, 0); The usual Connection constructor, C brings a new object into existence and forges the connection to the server all in one operation, which is often what you want. For applications that need -more control, however, these two method separate the two steps, +more control, however, these two methods separate the two steps, allowing additional steps in between such as the setting of options. C creates and returns a new Connection object, which is I connected to any server. It may be passed an options block, of type C (see below), into which options may be set -before or after the creation of the Connection. The connection to the -server may then be forged by the C method, the arguments of -which are the same as those of the C constructor. +before or after the creation of the Connection. Alternatively and +equivalently, C may be passed a list of key-value option +pairs directly. The connection to the server may then be forged by +the C method, the arguments of which are the same as those +of the C constructor. =head4 error_x() / errcode() / errmsg() / addinfo() / diagset() @@ -1012,6 +1049,21 @@ relations and modifiers into Type-1 query attributes. An example CQL configuration file is included in the ZOOM-Perl distribution, in the file C +=item ZOOM::Query::CCL2RPN + +Implements CCL by compiling it on the client-side into a Z39.50 Type-1 +(RPN) query, and sending that. Because the compilation is done on the +client side, a configuration file is required to direct the mapping of +CCL constructs such as index names and boolean operators into Type-1 +query attributes. An example CCL configuration file is included in +the ZOOM-Perl distribution, in the file C + +CCL is syntactically very similar to CQL, but much looser. While CQL +is an entirely precise language in which each possible query has +rigorously defined semantics, and is thus suitable for transfer as +part of a protocol, CCL is best deployed as a human-facing UI +language. + =back See the description of the C class in the ZOOM Abstract @@ -1042,6 +1094,17 @@ if compilation fails, then diagnostic information is cached in the Connection and be retrieved using C<$conn-Eerrcode()> and related methods. + $conn->option(cclfile => "samples/ccl/default.bib"); + # or + $conn->option(cclqual => "ti u=4 s=pw\nab u=62 s=pw"); + $q = new ZOOM::Query::CCL2RPN('ti=dinosaur', $conn); + +For the C subclass, too, the Connection must be +passed into the constructor, for the same reasons as when client-side +CQL compilation is used. The C option, if defined, gives a +CCL qualification specification inline; otherwise, the contents of the +file named by the C option are used. + =head4 sortby() $q->sortby("1=4 >i 1=21 >s"); @@ -1218,6 +1281,10 @@ C, C, C, C, +C, +C, +C, +C, C, C, C, @@ -1405,7 +1472,7 @@ result-set of each server as soon as it becomes available. use ZOOM; @servers = ('z3950.loc.gov:7090/Voyager', - 'bagel.indexdata.com:210/gils', + 'z3950.indexdata.com:210/gils', 'agricola.nal.usda.gov:7190/Voyager'); for ($i = 0; $i < @servers; $i++) { $z[$i] = new ZOOM::Connection($servers[$i], 0,