Update copyright year

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

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 867c528..20fb9a1 100644 (file)
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,5 +1,3 @@
-# $Id: ZOOM.pod,v 1.39 2006-11-03 09:36:28 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);

@@ -279,8 +284,8 @@ type C<ZOOM::Options> (see below), into which options may be set
 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
 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.
+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()
 

@@ -305,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");

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

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

@@ -636,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();

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

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

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