X-Git-Url: http://lists.indexdata.dk/cgi-bin?a=blobdiff_plain;f=lib%2FZOOM.pod;h=e3c64169aee6f980b62e8ebcd8f6612cf3bc0a0d;hb=f39659ec808b403737e2bd5e9a2bcc8d1fb67674;hp=73e122a870b5b9ee45675b758fc473e2f8b81a1e;hpb=01aefec56fba249c41a1cfb042aac54955cae634;p=ZOOM-Perl-moved-to-github.git

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 73e122a..e3c6416 100644
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.37 2006-06-15 15:42:30 mike Exp $
+# $Id: ZOOM.pod,v 1.41 2006-12-01 14:11:21 mike Exp $
 
 use strict;
 use warnings;
@@ -190,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
@@ -223,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<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
@@ -238,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<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, the arguments of which are the same as those
+of the C<new()> constructor.
 
 =head4 error_x() / errcode() / errmsg() / addinfo() / diagset()
 
@@ -608,6 +636,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<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();
@@ -1071,7 +1127,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<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
@@ -1247,7 +1303,7 @@ C<MEMORY>,
 C<ENCODE>,
 C<DECODE>,
 C<CONNECTION_LOST>,
-C<INIT>,
+C<ZINIT>,
 C<INTERNAL>,
 C<TIMEOUT>,
 C<UNSUPPORTED_PROTOCOL>,
@@ -1444,7 +1500,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,