From c0ccfab6a11c696d81eb60bdeda710c223679d0c Mon Sep 17 00:00:00 2001 From: mike Date: Sat, 26 Nov 2005 16:59:53 +0000 Subject: [PATCH] Much new material (from yesterday). --- lib/ZOOM.pod | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 119 insertions(+), 8 deletions(-) diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index 176f05c..b626bf6 100644 --- 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; @@ -561,7 +561,7 @@ result-set is destroyed. See the description of the C 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 @@ -589,7 +589,7 @@ that can be decoded by software such as the fine C 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(); @@ -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. +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 for a ZOOM-specific error such as +C ("out of memory"), and C 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 class in the ZOOM Abstract +API at +http://zoom.z3950.org/api/zoom-current.html#3.7 + =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. + +=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 + $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 method nor any other explicit constructor. The +only way to create a new ScanSet is by using C on a +Connection. + +See the description of the C 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 @@ -685,10 +794,12 @@ C, C and C, -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 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 -- 1.7.10.4