X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=lib%2FZOOM.pod;h=20fb9a1d2e4b07d7dc614dc418511d62631ed3d3;hb=150f46f520c95d48bc52eacae074639b1718a8fc;hp=73e122a870b5b9ee45675b758fc473e2f8b81a1e;hpb=01aefec56fba249c41a1cfb042aac54955cae634;p=ZOOM-Perl-moved-to-github.git diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index 73e122a..20fb9a1 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,5 +1,3 @@ -# $Id: ZOOM.pod,v 1.37 2006-06-15 15:42:30 mike Exp $ - use strict; use warnings; @@ -98,6 +96,13 @@ C, irrespective of whether it is a member of the C enumeration or drawn from the BIB-1 diagnostic set. +=head2 ZOOM::diag_srw_str() + + $msg = ZOOM::diag_srw_str(18); + +Returns a human-readable English-language string corresponding to the +specified SRW error code. + =head2 ZOOM::event_str() $msg = ZOOM::event_str(ZOOM::Event::RECV_APDU); @@ -190,6 +195,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 @@ -223,11 +230,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 @@ -238,21 +264,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, which accepts hostname and port arguments +like those of the C constructor. =head4 error_x() / errcode() / errmsg() / addinfo() / diagset() @@ -277,6 +310,24 @@ returns all four at once. See the C for the interpretation of these elements. +=head4 exception() + + die $conn->exception(); + +C returns the same information as C in the +form of a C object which may be thrown or rendered. +If no error occurred on the connection, then C returns an +undefined value. + +=head4 check() + + $conn->check(); + +Checks whether an error is pending on the connection, and throw a +C object if so. Since errors are thrown as they +occur for synchronous connections, there is no need ever to call this +except in asynchronous applications. + =head4 option() / option_binary() print("server is '", $conn->option("serverImplementationName"), "'\n"); @@ -492,7 +543,7 @@ Returns the number of records in the result set. The C method returns a C object representing a record from result-set, whose position is indicated by the argument passed in. This is a zero-based index, so that legitimate values -range from zero to C<$rs->size()-1>. +range from zero to C<$rs-Esize()-1>. The C API is identical, but it never invokes a network operation, merely returning the record from the ResultSet's @@ -518,7 +569,7 @@ wants to display a whole list of results. Conversely, the software's strategy might be always to ask for blocks of a twenty records: that's great for assembling long lists of things, but wasteful when only one record is wanted. The problem is that the ZOOM module can't -tell, when you call C<$rs->record()>, what your intention is. +tell, when you call C<$rs-Erecord()>, what your intention is. But you can tell it. The C method fetches a sequence of records, all in one go. It takes three arguments: the first is the @@ -608,6 +659,34 @@ http://zoom.z3950.org/api/zoom-current.html#3.5 =head3 Methods +=head4 error() / exception() + + if ($rec->error()) { + my($code, $msg, $addinfo, $dset) = $rec->error(); + print "error $code, $msg ($addinfo) from $dset set\n"; + die $rec->exception(); + } + +These functions test for surrogate diagnostics associated with a +record: that is, errors pertaining to a particular record rather than +to the fetch-some-records operation as a whole. (The latter are known +in Z39.50 as non-surrogate diagnostics, and are reported as exceptions +thrown by searches.) If a particular record can't be obtained - for +example, because it is not available in the requested record syntax - +then the record object obtained from the result-set, when interrogated +with these functions, will report the error. + +C returns the error-code, a human-readable message, +additional information and the name of the diagnostic set that the +error is from. When called in a scalar context, it just returns the +error-code. Since error 0 means "no error", it can be used as a +boolean has-there-been-an-error indicator. + +C returns the same information in the form of a +C object which may be thrown or rendered. If no +error occurred on the record, then C returns an undefined +value. + =head4 render() print $rec->render(); @@ -1071,7 +1150,7 @@ methods. $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 +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 @@ -1247,7 +1326,7 @@ C, C, C, C, -C, +C, C, C, C, @@ -1444,7 +1523,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, @@ -1487,7 +1566,7 @@ Mike Taylor, Emike@indexdata.comE =head1 COPYRIGHT AND LICENCE -Copyright (C) 2005 by Index Data. +Copyright (C) 2005-2014 by Index Data. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or,