Much new material (from yesterday).

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 176f05c..b626bf6 100644 (file)
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,4 @@
-# $Id: ZOOM.pod,v 1.11 2005-11-24 17:35:29 mike Exp $
+# $Id: ZOOM.pod,v 1.12 2005-11-26 16:59:53 mike Exp $

 
 use strict;
 use warnings;
 
 use strict;
 use warnings;

@@ -561,7 +561,7 @@ result-set is destroyed.
 
 See the description of the C<Record> class in the ZOOM Abstract
 API at
 
 See the description of the C<Record> class in the ZOOM Abstract
 API at

-http://zoom.z3950.org/api/zoom-current.html#3.4
+http://zoom.z3950.org/api/zoom-current.html#3.5

 
 =head3 Methods
 
 
 =head3 Methods
 

@@ -589,7 +589,7 @@ that can be decoded by software such as the fine C<Marc::Record>
 module; GRS-1 record will be ... gosh, what an interesting question.
 But no-one uses GRS-1 any more, do they?
 
 module; GRS-1 record will be ... gosh, what an interesting question.
 But no-one uses GRS-1 any more, do they?
 

-=head4 clone(), destroy()
+=head4 clone() / destroy()

 
  $rec = $rs->record($i);
  $newrec = $rec->clone();
 
  $rec = $rs->record($i);
  $newrec = $rec->clone();

@@ -624,12 +624,121 @@ circumstances that do not merit throwing an exception.  For this
 reason, the return values of these methods should be checked.  See the
 individual methods' documentation for details.
 
 reason, the return values of these methods should be checked.  See the
 individual methods' documentation for details.
 

+An exception carries the following pieces of information:
+
+=over 4
+
+=item error-code
+
+A numeric code that specifies the type of error.  This can be checked
+for equality with known values, so that intelligent applications can
+take appropriate action.
+
+=item error-message
+
+A human-readable message corresponding with the code.  This can be
+shown to users, but its value should not be tested, as it could vary
+in different versions or under different locales.
+
+=item additional information [optional]
+
+A string containing information specific to the error-code.  For
+example, when the error-code is the BIB-1 diagnostic 109 ("Database
+unavailable"), the additional information is the name of the database
+that the application tried to use.  For some error-codes, there is no
+additional information at all; for some others, the additional
+information is undefined and may just be an human-readable string.
+
+=item diagnostic set [optional]
+
+A short string specifying the diagnostic set from which the error-code
+was drawn: for example, C<ZOOM> for a ZOOM-specific error such as
+C<ZOOM::Error::MEMORY> ("out of memory"), and C<BIB-1> for a Z39.50
+error-code drawn from the BIB-1 diagnostic set.
+
+=back
+
+In theory, the error-code should be interpreted in the context of the
+diagnostic set from which it is drawn; in practice, nearly all errors
+are from either the ZOOM or BIB-1 diagnostic sets, and the codes in
+those sets have been chosen so as not to overlap, so the diagnostic
+set can usually be ignored.
+
+See the description of the C<Exception> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.7
+

 =head3 Methods
 
 =head3 Methods
 

-I<###>
+=head4 new()
+
+ die new ZOOM::Exception($errcode, $errmsg, $addinfo, $diagset);
+
+Creates and returns a new Exception object with the specified
+error-code, error-message, additional information and diagnostic set.
+Applications will not in general need to use this, but may find it
+useful to simulate ZOOM exceptions.  As is usual with Perl, exceptions
+are thrown using C<die()>.
+
+=head4 code() / message() / addinfo() / diagset()
+
+ print "Error ", $@->code(), ": ", $@->message(), "\n";
+ print "(addinfo '", $@->addinfo(), "', set '", $@->diagset(), "')\n";
+
+These methods, of no arguments, return the exception's error-code,
+error-message, additional information and diagnostic set respectively.
+
+=head4 render()
+
+ print $@->render();
+
+Returns a human-readable rendition of an exception.  The C<"">
+operator is overloaded on the Exception class, so that an Exception
+used in a string context is automatically rendered.  Among other
+consequences, this has the useful result that a ZOOM application that
+died due to an uncaught exception will emit an informative message
+before exiting.

 
 =head2 ZOOM::ScanSet
 
 
 =head2 ZOOM::ScanSet
 

+ $ss = $conn->scan('@attr 1=1003 a');
+ $n = $ss->size();
+ ($term, $occ) = $ss->term($n-1);
+ $rs = $conn->search_pqf('@attr 1=1003 "' . $term . "'");
+ assert($rs->size() == $occ);
+
+A ScanSet represents a set of candidate search-terms returned from an
+index scan.  Its sole purpose is to provide access to those term, to
+the corresponding display terms, and to the occurrence-counts of the
+terms.
+
+There is no C<new()> method nor any other explicit constructor.  The
+only way to create a new ScanSet is by using C<scan()> on a
+Connection.
+
+See the description of the C<Scan Set> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.6
+
+=head3 Methods
+
+=head4 size()
+
+ print "Found ", $ss->size(), " terms\n";
+
+Returns the number of terms in the scan set.
+### describe option that affects this.
+
+=head4 term() / display_term()
+
+I<###>
+
+=head4 option()
+
+I<###>
+
+=head4 destroy()
+

 I<###>
 
 =head2 ZOOM::Package
 I<###>
 
 =head2 ZOOM::Package

@@ -685,10 +794,12 @@ C<CLONE>,
 C<PACKAGE>
 and
 C<SCANTERM>,
 C<PACKAGE>
 and
 C<SCANTERM>,

-each of which specifies a client-side error.  Since errors may also be
-diagnosed by the server, and returned to the client, error codes may
-also take values from the BIB-1 diagnostic set of Z39.50, listed at
-the Z39.50 Maintenance Agency's web-site at
+each of which specifies a client-side error.  These codes constitute
+the C<ZOOM> diagnostic set.
+
+Since errors may also be diagnosed by the server, and returned to the
+client, error codes may also take values from the BIB-1 diagnostic set
+of Z39.50, listed at the Z39.50 Maintenance Agency's web-site at

 http://www.loc.gov/z3950/agency/defns/bib1diag.html
 
 All error-codes, whether client-side from the C<ZOOM::Error>
 http://www.loc.gov/z3950/agency/defns/bib1diag.html
 
 All error-codes, whether client-side from the C<ZOOM::Error>