-# $Id: ZOOM.pod,v 1.10 2005-11-18 17:55:08 mike Exp $
+# $Id: ZOOM.pod,v 1.18 2005-12-13 14:53:08 mike Exp $
use strict;
use warnings;
carry with them a set of named options which affect their behaviour in
certain ways. See the ZOOM-C options documentation for details:
-=over 4
-
-=item *
-
Connection options are listed at
http://indexdata.com/yaz/doc/zoom.tkl#zoom.connections
-=item *
-
-ScanSet options are listed at
-http://indexdata.com/yaz/doc/zoom.scan.tkl
-I<### move this obvservation down to the appropriate place>
-
-=item *
-
-Package options are listed at
-http://indexdata.com/yaz/doc/zoom.ext.html
-I<### move this obvservation down to the appropriate place>
-
-=back
-
These options are set and fetched using the C<option()> method, which
may be called with either one or two arguments. In the two-argument
form, the option named by the first argument is set to the value of
=head4 option()
- $conn->option(elementSetName => "f");
+ $rs->option(elementSetName => "f");
-Allows options to be set into, and read from a ResultSet, just like
+Allows options to be set into, and read from, a ResultSet, just like
the Connection class's C<option()> method. There is no
C<option_binary()> method for ResultSet objects.
Returns the number of records in the result set.
-=head4 record(), record_immediate()
+=head4 record() / record_immediate()
$rec = $rs->record(0);
$rec2 = $rs->record_immediate(0);
Once the records have been retrieved from the server
(i.e. C<records()> has completed without throwing an exception), they
can be fetched much more efficiently using C<record()> - or
-C<record_immediate(), which is then guaranteed to succeed.
+C<record_immediate()>, which is then guaranteed to succeed.
=head4 cache_reset()
=head4 sort()
- if ($rs->sort("yaz", "1=4 >i") < 0) {
+ if ($rs->sort("yaz", "1=4 >i 1=21 >s") < 0) {
die "sort failed";
}
-Sorts the ResultSet in place ###
-
+Sorts the ResultSet in place (discarding any cached records, as they
+will in general be sorted into a different position). There are two
+arguments: the first is a string indicating the type of the
+sort-specification, and the second is the specification itself.
+
+The C<sort()> method returns 0 on success, or -1 if the
+sort-specification is invalid.
+
+At present, the only supported sort-specification type is C<yaz>.
+Such a specification consists of a space-separated sequence of keys,
+each of which itself consists of two space-separated words (so that
+the total number of words in the sort-specification is even). The two
+words making up each key are a field and a set of flags. The field
+can take one of two forms: if it contains an C<=> sign, then it is a
+BIB-1 I<type>=I<value> pair specifying which field to sort
+(e.g. C<1=4> for a title sort); otherwise it is sent for the server to
+interpret as best it can. The word of flags is made up from one or
+more of the following: C<s> for case sensitive, C<i> for case
+insensitive; C<<> for ascending order and C<E<gt>> for descending
+order.
+
+For example, the sort-specification in the code-fragment above will
+sort the records in C<$rs> case-insensitively in descending order of
+title, with records having equivalent titles sorted case-sensitively
+in ascending order of subject. (The BIB-1 access points 4 and 21
+represent title and subject respectively.)
+
=head4 destroy()
$rs->destroy()
=head2 ZOOM::Record
-I<###>
+ $rec = $rs->record($i);
+ print $rec->render();
+ $raw = $rec->raw();
+ $marc = new_from_usmarc MARC::Record($raw);
+ print "Record title is: ", $marc->title(), "\n";
+
+A Record object represents a record that has been retrived from the
+server.
+
+There is no C<new()> method nor any other explicit constructor. The
+only way to create a new Record is by using C<record()> (or
+C<record_immediate()>, or C<records()>) on a ResultSet.
+
+In general, records are ``owned'' by their result-sets that they were
+retrieved from, so they do not have to be explicitly memory-managed:
+they are deallocated (and therefore can no longer be used) when the
+result-set is destroyed.
+
+See the description of the C<Record> class in the ZOOM Abstract
+API at
+http://zoom.z3950.org/api/zoom-current.html#3.5
+
+=head3 Methods
+
+=head4 render()
+
+ print $rec->render()
+
+Returns a human-readable representation of the record. Beyond that,
+no promises are made: careful programs should not make assumptions
+about the format of the returned string.
+
+This method is useful mostly for debugging.
+
+=head4 raw()
+
+ use MARC::Record
+ $raw = $rec->raw();
+ $marc = new_from_usmarc MARC::Record($raw);
+
+Returns an opaque blob of data that is the raw form of the record.
+Exactly what this is, and what you can do with it, varies depending on
+the record-syntax. For example, XML records will be returned as,
+well, XML; MARC records will be returned as ISO 2709-encoded blocks
+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?
+
+=head4 clone() / destroy()
+
+ $rec = $rs->record($i);
+ $newrec = $rec->clone();
+ $rs->destroy();
+ print $newrec->render();
+ $newrec->destroy();
+
+Usually, it's convenient that Record objects are owned by their
+ResultSets and go away when the ResultSet is destroyed; but
+occasionally you need a Record to outlive its parent and destroy it
+later, explicitly. To do this, C<clone()> the record, keep the new
+Record object that is returned, and C<destroy()> it when it's no
+longer needed. This is B<only> situation in which a Record needs to
+be destroyed.
=head2 ZOOM::Exception
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
-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
-I<###>
+ $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. In general, this will be
+the scan-set size requested by the C<number> option in the Connection
+on which the scan was performed [default 10], but it may be fewer if
+the scan is close to the end of the index.
+
+=head4 term() / display_term()
+
+ $ss = $conn->scan('@attr 1=1004 whatever');
+ ($term, $occurrences) = $ss->term(0);
+ ($displayTerm, $occurrences2) = $ss->display_term(0);
+ assert($occurrences == $occurrences2);
+ if (user_likes_the_look_of($displayTerm)) {
+ $rs = $conn->search_pqf('@attr 1=4 "' . $term . '"');
+ assert($rs->size() == $occurrences);
+ }
+
+These methods return the scanned terms themselves. C<term()> returns
+the term is a form suitable for submitting as part of a query, whereas
+C<display_term()> returns it in a form suitable for displaying to a
+user. Both versions also return the number of occurrences of the term
+in the index, i.e. the number of hits that will be found if the term
+is subsequently used in a query.
+
+In most cases, the term and display term will be identical; however,
+they may be different in cases where punctuation or case is
+normalised, or where identifiers rather than the original document
+terms are indexed.
+
+=head4 option()
+
+ print "scan status is ", $ss->option("scanStatus");
+
+Allows options to be set into, and read from, a ScanSet, just like
+the Connection class's C<option()> method. There is no
+C<option_binary()> method for ScanSet objects.
+
+ScanSet options are also described, though not particularly
+informatively, at
+http://indexdata.com/yaz/doc/zoom.scan.tkl
+
+=head4 destroy()
+
+ $ss->destroy()
+
+Destroys a ScanSet object, freeing its resources. It is an error to
+reuse a ScanSet that has been C<destroy()>ed.
=head2 ZOOM::Package
-I<###>
+ $p = $conn->package();
+ $p->option(action => "specialUpdate");
+ $p->option(recordIdOpaque => 145);
+ $p->option(record => content_of("/tmp/record.xml"));
+ $p->send("update");
+ $p->destroy();
+
+This class represents an Extended Services Package: an instruction to
+the server to do something not covered by the core parts of the Z39.50
+standard (or the equivalent in SRW or SRU). Since the core protocols
+are read-only, such requests are often used to make changes to the
+database, such as in the record update example above.
+
+Requesting an extended service is a four-step process: first, create a
+package associated with the connection to the relevant database;
+second, set options on the package to instruct the server on what to
+do; third, send the package (which may result in an exception being
+thrown if the server cannot execute the requested operations; and
+finally, destroy the package.
+
+Package options are listed at
+http://indexdata.com/yaz/doc/zoom.ext.html
+
+The particular options that have meaning are determined by the
+top-level operation string specified as the argument to C<send()>.
+For example, when the operation is C<update> (the most commonly used
+extended service), the C<action> option may be set to any of
+C<recordInsert>
+(add a new record, failing if that record already exists),
+C<recordDelete>
+(delete a record, failing if it is not in the database).
+C<recordReplace>
+(replace a record, failing if an old version is not already present)
+or
+C<specialUpdate>
+(add a record, replacing any existing version that may be present).
+
+For update, the C<record> option should be set to the full text of the
+XML record to added, deleted or replaced. Depending on how the server
+is configured, it may extract the record's unique ID from the text
+(i.e. from a known element such as the C<001> field of a MARCXML
+record), or it may require the unique ID to passed in explicitly using
+the C<recordIdOpaque> option.
+
+Extended services packages are B<not currently described> in the ZOOM
+Abstract API at
+http://zoom.z3950.org/api/zoom-current.html
+They will be added in a forthcoming version, and will function much
+as those implemented in this module.
+
+=head3 Methods
+
+=head4 option()
+
+ $p->option(recordIdOpaque => "46696f6e61");
+
+Allows options to be set into, and read from, a Package, just like
+the Connection class's C<option()> method. There is no
+C<option_binary()> method for Package objects.
+
+Package options are listed at
+http://indexdata.com/yaz/doc/zoom.ext.tkl
+
+=head4 send()
+
+ $p->send("createdb");
+
+Sends a package to the server associated with the Connection that
+created it. Problems are reported by throwing an exception. The
+single parameter indicates the operation that the server is being
+requested to perform, and controls the interpretation of the package's
+options. Valid operations include:
+
+=over 4
+
+=item itemorder
+
+Request a copy of a nominated object, e.g. place an ILL request.
+
+=item create
+
+Create a new database, the name of which is specified by the
+C<databaseName> option.
+
+=item drop
+
+Drop an existing database, the name of which is specified by the
+C<databaseName> option.
+
+=item commit
+
+Commit changes made to the database within a transaction.
+
+=item update
+
+Modify the contents of the database by adding, deleting or replacing
+records (as described above in the overview of the C<ZOOM::Package>
+class).
+
+=item xmlupdate
+
+I have no idea what this does.
+
+=back
+
+Although the module is capable of I<making> all these requests, not
+all servers are capable of I<executing> them. Refusal is indicated by
+throwing an exception. Problems may also be caused by lack of
+privileges; so C<send()> must be used with caution, and is perhaps
+best wrapped in a clause that checks for execptions, like so:
+
+ eval { $p->send("create") };
+ if ($@ && $@->isa("ZOOM::Exception")) {
+ print "Oops! ", $@->message(), "\n";
+ return $@->code();
+ }
+
+=head4 destroy()
+
+ $p->destroy()
+
+Destroys a Package object, freeing its resources. It is an error to
+reuse a Package that has been C<destroy()>ed.
=head2 ZOOM::Query
-I<###>
+ $q = new ZOOM::Query::CQL("creator=pike and subject=unix");
+ $q->sortby("1=4 >i 1=21 >s");
+ $rs = $conn->search($q);
+ $q->destroy();
+
+C<ZOOM::Query> is a virtual base class from which various concrete
+subclasses can be derived. Different subclasses implement different
+types of query. The sole purpose of a Query object is to be used in a
+C<search()> on a Connection; because PQF is such a common special
+case, the shortcut Connection method C<search_pqf()> is provided.
+
+The following Query subclasses are provided, both of the providing the
+same set of methods described below:
+
+=over 4
+
+=item ZOOM::Query::PQF
+
+Implements Prefix Query Format (PQF), also sometimes known as Prefix
+Query Notation (PQN). This esoteric but rigorous and expressive
+format is described in the YAZ Manual at
+http://indexdata.com/yaz/doc/tools.tkl#PQF
+
+=item ZOOM::Query::CQL
+
+Implements the Common Query Language (CQL) of SRU, the Search/Retrieve
+URL. CQL is a much friendlier notation than PQF, using a simple infix
+notation. The queries are passed ``as is'' to the server rather than
+being compiled into a Z39.50 Type-1 query, so only CQL-compliant
+servers can support such querier. CQL is described at
+http://www.loc.gov/standards/sru/cql/
+and in a slight out-of-date but nevertheless useful tutorial at
+http://zing.z3950.org/cql/intro.html
+
+=back
+
+=head3 Methods
+
+=head4 new()
+
+ $q = new ZOOM::Query::CQL('title=dinosaur'));
+ $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+
+Creates a new query object, compiling the query passed as its argument
+according to the rules of the particular query-type being
+instantiated. If compilation fails, an exception is thrown.
+Otherwise, the query may be passed to the C<Connection> method
+<search()>.
+
+=head4 sortby()
+
+ $q->sortby("1=4 >i 1=21 >s");
+
+Sets a sort specification into the query, so that when a C<search()>
+is run on the query, the result is automatically sorted. The sort
+specification language is the same as the C<yaz> sort-specification
+type of the C<ResultSet> method C<sort()>, described above.
+
+I<### It should be possible to sort by CQL query, too.>
+
+=head4 destroy()
+
+ $p->destroy()
+
+Destroys a Query object, freeing its resources. It is an error to
+reuse a Query that has been C<destroy()>ed.
=head2 ZOOM::Options
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>
projects / ZOOM-Perl-moved-to-github.git / blobdiff