Update copyright year
[ZOOM-Perl-moved-to-github.git] / lib / ZOOM.pod
index 73e122a..20fb9a1 100644 (file)
@@ -1,5 +1,3 @@
-# $Id: ZOOM.pod,v 1.37 2006-06-15 15:42:30 mike Exp $
-
 use strict;
 use warnings;
 
 use strict;
 use warnings;
 
@@ -98,6 +96,13 @@ 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);
 =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.
 
 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
@@ -223,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
@@ -238,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()
 
@@ -277,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");
@@ -492,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
@@ -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
 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
@@ -608,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();
@@ -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);
 
  $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::CQL2RPN> subclass, too, the Connection must be
+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
 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
@@ -1247,7 +1326,7 @@ 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<INTERNAL>,
 C<TIMEOUT>,
 C<UNSUPPORTED_PROTOCOL>,
@@ -1444,7 +1523,7 @@ result-set of each server as soon as it becomes available.
 
  use ZOOM;
  @servers = ('z3950.loc.gov:7090/Voyager',
 
  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,
              '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, 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,