-# $Id: ZOOM.pod,v 1.39 2006-11-03 09:36:28 mike Exp $
+# $Id: ZOOM.pod,v 1.46 2007-12-10 21:51:40 mike Exp $
use strict;
use warnings;
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);
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");
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
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
=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();
$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
C<ENCODE>,
C<DECODE>,
C<CONNECTION_LOST>,
-C<INIT>,
+C<ZINIT>,
C<INTERNAL>,
C<TIMEOUT>,
C<UNSUPPORTED_PROTOCOL>,