-# $Id: ZOOM.pod,v 1.34 2006-04-12 08:49:20 mike Exp $
-
use strict;
use warnings;
anyway; but knowing that the same code is running is reassuring.)
The ZOOM module provides two enumerations (C<ZOOM::Error> and
-C<ZOOM::Event>), two utility functions C<diag_str()> and C<event()> in
-the C<ZOOM> package itself, and eight classes:
+C<ZOOM::Event>), three utility functions C<diag_str()>, C<event_str()>
+and C<event()> in the C<ZOOM> package itself, and eight classes:
C<ZOOM::Exception>,
C<ZOOM::Options>,
C<ZOOM::Connection>,
C<ZOOM::ScanSet>
and
C<ZOOM::Package>.
-Of these, the Query class is abstract, and has three concrete
+Of these, the Query class is abstract, and has four concrete
subclasses:
C<ZOOM::Query::CQL>,
-C<ZOOM::Query::PQF>
+C<ZOOM::Query::PQF>,
+C<ZOOM::Query::CQL2RPN>
and
-C<ZOOM::Query::CQL2RPN>.
+C<ZOOM::Query::CCL2RPN>.
Finally, it also provides a
C<ZOOM::Query::Log>
module which supplies a useful general-purpose logging facility.
irrespective of whether it is a member of the C<ZOOM::Error>
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);
+
+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<ZOOM::Event> enumeration.
+
=head2 ZOOM::event()
$connsRef = [ $conn1, $conn2, $conn3 ];
including those that must be set before connecting such as
authentication tokens.
+The server-name string is of the form:
+
=over 4
=item
=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<http> scheme is used, the particular SRU flavour to be used
+may be specified by the C<sru> 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
$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<new()> 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<create()> creates and returns a new Connection object, which is
I<not> connected to any server. It may be passed an options block, of
type C<ZOOM::Options> (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<connect()> method, the arguments of
-which are the same as those of the C<new()> constructor.
+before or after the creation of the Connection. Alternatively and
+equivalently, C<create()> may be passed a list of key-value option
+pairs directly. The connection to the server may then be forged by
+the C<connect()> method, which accepts hostname and port arguments
+like those of the C<new()> constructor.
=head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
See the C<ZOOM::Exception> for the interpretation of these elements.
+=head4 exception()
+
+ die $conn->exception();
+
+C<exception()> returns the same information as C<error_x()> in the
+form of a C<ZOOM::Exception> object which may be thrown or rendered.
+If no error occurred on the connection, then C<exception()> returns an
+undefined value.
+
+=head4 check()
+
+ $conn->check();
+
+Checks whether an error is pending on the connection, and throw a
+C<ZOOM::Exception> 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");
The C<record()> method returns a C<ZOOM::Record> 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-E<gt>size()-1>.
The C<record_immediate()> API is identical, but it never invokes a
network operation, merely returning the record from the ResultSet'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-E<gt>record()>, what your intention is.
But you can tell it. The C<records()> method fetches a sequence of
records, all in one go. It takes three arguments: the first is the
=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<error()> 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<exception()> returns the same information in the form of a
+C<ZOOM::Exception> object which may be thrown or rendered. If no
+error occurred on the record, then C<exception()> returns an undefined
+value.
+
=head4 render()
print $rec->render();
configuration file is included in the ZOOM-Perl distribution, in the
file C<samples/cql/pqf.properties>
+=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<samples/ccl/default.bib>
+
+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<Query> class in the ZOOM Abstract
Connection and be retrieved using C<$conn-E<gt>errcode()> 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<ZOOM::Query::CCL2RPN> subclass, too, the Connection must be
+passed into the constructor, for the same reasons as when client-side
+CQL compilation is used. The C<cclqual> option, if defined, gives a
+CCL qualification specification inline; otherwise, the contents of the
+file named by the C<cclfile> option are used.
+
=head4 sortby()
$q->sortby("1=4 >i 1=21 >s");
C<ENCODE>,
C<DECODE>,
C<CONNECTION_LOST>,
-C<INIT>,
+C<ZINIT>,
C<INTERNAL>,
C<TIMEOUT>,
C<UNSUPPORTED_PROTOCOL>,
C<UNSUPPORTED_QUERY>,
C<INVALID_QUERY>,
+C<CQL_PARSE>,
+C<CQL_TRANSFORM>,
+C<CCL_CONFIG>,
+C<CCL_PARSE>,
C<CREATE_QUERY>,
C<QUERY_CQL>,
C<QUERY_PQF>,
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,
=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,
projects / ZOOM-Perl-moved-to-github.git / blobdiff