New ->exception() method£

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

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 1b62c13..acc0cce 100644 (file)
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.40 2006-11-03 09:49:38 mike Exp $
+# $Id: ZOOM.pod,v 1.43 2007-05-09 12:03:52 mike Exp $
 
 use strict;
 use warnings;
@@ -305,6 +305,24 @@ returns all four at once.
 
 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");
@@ -636,6 +654,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();
@@ -1275,7 +1321,7 @@ C<MEMORY>,
 C<ENCODE>,
 C<DECODE>,
 C<CONNECTION_LOST>,
-C<INIT>,
+C<ZINIT>,
 C<INTERNAL>,
 C<TIMEOUT>,
 C<UNSUPPORTED_PROTOCOL>,