Update copyright year

[ZOOM-Perl-moved-to-github.git] / lib / ZOOM.pod

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index fd8abbf..20fb9a1 100644 (file)
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,5 +1,3 @@
-# $Id: ZOOM.pod,v 1.33 2006-04-11 16:40:08 mike Exp $
-

 use strict;
 use warnings;
 
 use strict;
 use warnings;
 

@@ -39,8 +37,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<ZOOM::Error> and
 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::Exception>,
 C<ZOOM::Options>,
 C<ZOOM::Connection>,

@@ -50,12 +48,13 @@ C<ZOOM::Record>,
 C<ZOOM::ScanSet>
 and
 C<ZOOM::Package>.
 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>,
 subclasses:
 C<ZOOM::Query::CQL>,

-C<ZOOM::Query::PQF>
+C<ZOOM::Query::PQF>,
+C<ZOOM::Query::CQL2RPN>

 and
 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.
 Finally, it also provides a
 C<ZOOM::Query::Log>
 module which supplies a useful general-purpose logging facility.

@@ -97,6 +96,21 @@ C<ZOOM::Connection::errcode()>,
 irrespective of whether it is a member of the C<ZOOM::Error>
 enumeration or drawn from the BIB-1 diagnostic set.
 
 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 ];
 =head2 ZOOM::event()
 
  $connsRef = [ $conn1, $conn2, $conn3 ];

@@ -181,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.
 
 including those that must be set before connecting such as
 authentication tokens.
 

+The server-name string is of the form:
+

 =over 4
 
 =item
 =over 4
 
 =item

@@ -214,11 +230,30 @@ local filesystem.
 
 =item http
 
 
 =item http
 

-SRW connection using SOAP over HTTP.
+SRU connection over HTTP.

 
 =back
 
 
 =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
 
 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 +264,28 @@ request).
 
  $options = new ZOOM::Options();
  $options->option(implementationName => "my client");
 
  $options = new ZOOM::Options();
  $options->option(implementationName => "my client");

+ $options->option(implementationId => 12345);

  $conn = create ZOOM::Connection($options)
  $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
  $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
 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()
 
 
 =head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
 

@@ -268,6 +310,24 @@ returns all four at once.
 
 See the C<ZOOM::Exception> for the interpretation of these elements.
 
 
 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");
 =head4 option() / option_binary()
 
  print("server is '", $conn->option("serverImplementationName"), "'\n");

@@ -483,7 +543,7 @@ Returns the number of records in the result set.
 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
 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
 
 The C<record_immediate()> API is identical, but it never invokes a
 network operation, merely returning the record from the ResultSet's

@@ -509,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
 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
 
 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

@@ -599,6 +659,34 @@ http://zoom.z3950.org/api/zoom-current.html#3.5
 
 =head3 Methods
 
 
 =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();
 =head4 render()
 
  print $rec->render();

@@ -1012,6 +1100,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<samples/cql/pqf.properties>
 
 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
 =back
 
 See the description of the C<Query> class in the ZOOM Abstract

@@ -1042,6 +1145,17 @@ if compilation fails, then diagnostic information is cached in the
 Connection and be retrieved using C<$conn-E<gt>errcode()> and related
 methods.
 
 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");
 =head4 sortby()
 
  $q->sortby("1=4 >i 1=21 >s");

@@ -1212,12 +1326,16 @@ C<MEMORY>,
 C<ENCODE>,
 C<DECODE>,
 C<CONNECTION_LOST>,
 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<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>,
 C<CREATE_QUERY>,
 C<QUERY_CQL>,
 C<QUERY_PQF>,

@@ -1399,13 +1517,14 @@ immediately obtained.
 =back
 
 Here is a very short program (omitting all error-checking!) which
 =back
 
 Here is a very short program (omitting all error-checking!) which

-demonstrates this process.  It parallel-searches two servers (or more
+demonstrates this process.  It parallel-searches three servers (or more

 of you add them the list), displaying the first record in the
 result-set of each server as soon as it becomes available.
 
  use ZOOM;
  @servers = ('z3950.loc.gov:7090/Voyager',
 of you add them the list), displaying the first record in the
 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,
                                    async => 1, # asynchronous mode
  for ($i = 0; $i < @servers; $i++) {
      $z[$i] = new ZOOM::Connection($servers[$i], 0,
                                    async => 1, # asynchronous mode

@@ -1447,7 +1566,7 @@ Mike Taylor, E<lt>mike@indexdata.comE<gt>
 
 =head1 COPYRIGHT AND LICENCE
 
 
 =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,
 
 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,