X-Git-Url: http://sru.miketaylor.org.uk/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=0d3fcab5f94e22ef552d439935b01d12c8d92eb3;hb=096af05205c65b89240855fc35ad3e898050d5e4;hp=29f248f3a9333c74900f964944e42cfb0da137c0;hpb=2ad40f2e15a4d6927833231b8dc6874b747fed2e;p=yazpp-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index 29f248f..0d3fcab 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,10 +1,491 @@ - - ZOOM - - About ZOOM (++). - + + ZOOM-C++ + + + + Introduction + + ZOOM + is the emerging standard API for information retrieval programming + using the Z39.50 protocol. ZOOM's + Abstract API + specifies semantics for classes representing key IR concepts such as + connections, queries, result sets and records; and there are various + bindings + specifying how those concepts should be represented in various + programming languages. + + + The Yaz++ library includes an implementation of the C++ binding + for ZOOM, enabling quick, easy development of client applications. + + + For example, here is a tiny Z39.50 client that fetches and displays + the MARC record for Farlow & Brett Surman's + + The Complete Dinosaur + from the Library of Congress's Z39.50 server: + + + #include <iostream> + #include <yaz++/zoom.h> + + using namespace ZOOM; + + int main(int argc, char **argv) + { + connection conn("z3950.loc.gov", 7090); + conn.option("databaseName", "Voyager"); + resultSet rs(conn, prefixQuery("@attr attr 1=7 0253333490")); + const record *rec = rs.getRecord(0); + cout << rec->render() << endl; + } + + + (Note that, for the sake of simplicity, this does not check for + errors: we show a more realistic version of this program later.) + + + Yaz++'s implementation of the C++ binding is a thin layer over Yaz's + implementation of the C binding. For information on the supported + options and other such details, see the ZOOM-C documentation, which + can be found on-line at + + + + All of the classes defined by ZOOM-C++ are in the + ZOOM namespace. We will now consider + the five main classes in turn: + + + + + connection + + + + + + query and its subclasses + prefixQuery and + CCLQuery + + + + + + resultSet + + + + + + record + + + + + + exception and its subclasses + systemException, + bib1Exception and + queryException + + + + + + + + + <literal>ZOOM::connection</literal> + + A ZOOM::connection object represents an open + connection to a Z39.50 server. Such a connection is forged by + constructing a connection object. + + + The class has this declaration: + + + class connection { + public: + connection (const char *hostname, int portnum); + ~connection (); + const char *option (const char *key) const; + const char *option (const char *key, const char *val); + }; + + + When a new connection is created, the hostname + and port number of a Z39.50 server must be supplied, and the + network connection is forged and wrapped in the new object. If the + connection can't be established - perhaps because the hostname + couldn't be resolved, or there is no server listening on the + specified port - then an + exception + is thrown. + + + The only other methods on a connection object + are for getting and setting options. Any name-value pair of + strings may be set as options, and subsequently retrieved, but + certain options have special meanings which are understood by the + ZOOM code and affect the behaviour of the object that carries + them. For example, the value of the + databaseName option is used as the name of the + database to query when a search is executed against the + connection. For a full list of such special + options, see the ZOOM abstract API and the ZOOM-C documentation + (links below). + + + + References + + + + Section 3.2 (Connection) of the ZOOM Abstract API + + + + + The Connections section of the ZOOM-C documentation + + + + + + + + + <literal>ZOOM::query</literal> and subclasses + + The ZOOM::query class is a virtual base class, + representing a query to be submitted to a server. This class has + no methods, but two (so far) concrete subclasses, each implementing + a specific query notation. + + + + <literal>ZOOM::prefixQuery</literal> + + The class has this declaration: + + + class prefixQuery : public query { + public: + prefixQuery (const char *pqn); + ~prefixQuery (); + }; + + + It enables a query to be created from Yaz's cryptic but + powerful + Prefix Query Notation (PQN). + + + + + <literal>ZOOM::CCLQuery</literal> + + The class has this declaration: + + + class CCLQuery : public query { + public: + CCLQuery (const char *ccl, void *qualset); + ~CCLQuery (); + }; + + + It enables a query to be created using the simpler but less + expressive + Common Command Language (CCL). + The qualifiers recognised by the CCL parser are specified in an + external configuration file in the format described by the Yaz + documentation. + + + + + Discussion + + It will be readily recognised that these objects have no methods + other than their constructors: their only role in life is to be + used in searching, by being passed to the + resultSet class's constructor. + + + Given a suitable set of CCL qualifiers, the following pairs of + queries are equivalent: + + + prefixQuery("dinosaur"); + CCLQuery("dinosaur"); + + prefixQuery("@and complete dinosaur"); + CCLQuery("complete and dinosaur"); + + prefixQuery("@and complete @or dinosaur pterosaur"); + CCLQuery("complete and (dinosaur or pterosaur)"); + + prefixQuery("@attr 1=7 0253333490"); + CCLQuery("isbn=0253333490"); + + + + + References + + + + Section 3.3 (Query) of the ZOOM Abstract API + + + + + The Queries section of the ZOOM-C documentation + + + + + + + + + <literal>ZOOM::resultSet</literal> + + A ZOOM::resultSet object represents a set of + records identified by a query that has been executed against a + particular connection. The sole purpose of both + connection and query objects + is that they can be used to create new + resultSets - that is, to perform a search on the + server on the remote end of the connection. + + + The class has this declaration: + + + class resultSet { + public: + resultSet (connection &c, const query &q); + ~resultSet (); + const char *option (const char *key) const; + const char *option (const char *key, const char *val); + size_t size () const; + const record *getRecord (size_t i) const; + }; + + + New resultSets are created by the constructor, + which is passed a connection, indicating the + server on which the search is to be performed, and a + query, indicating what search to perform. If + the search fails - for example, because the query is malformed - + then an + exception + is thrown. + + + Like connections, resultSet + objects can carry name-value options. The special options which + affect ZOOM-C++'s behaviour are the same as those for ZOOM-C and + are described in its documentation (link below). In particular, + the preferredRecordSyntax option may be set to + a string such as ``USMARC'', ``SUTRS'' etc. to indicate what the + format in which records should be retrieved; and the + elementSetName option indicates whether brief + records (``B''), full records (``F'') or some other composition + should be used. + + + The size() method returns the number of records + in the result set. Zero is a legitimate value: a search that finds + no records is not the same as a search that fails. + + + Finally, the getRecord method returns the + ith record from the result set, where + i is zero-based: that is, legitmate values + range from zero up to one less than the result-set size. + + + + References + + + + Section 3.4 (Result Set) of the ZOOM Abstract API + + + + + The Result Sets section of the ZOOM-C documentation + + + + + + + + + <literal>ZOOM::record</literal> + + A ZOOM::record object represents a chunk of data + from a resultSet returned from a server. + + + The class has this declaration: + + + class record { + public: + ~record (); + enum syntax { + UNKNOWN, GRS1, SUTRS, USMARC, UKMARC, XML + }; + record *clone () const; + syntax recsyn () const; + const char *render () const; + const char *rawdata () const; + }; + + + ### discusson + + + + References + + + + Section 3.5 (Record) of the ZOOM Abstract API + + + + + The Records section of the ZOOM-C documentation + + + + + + + + + <literal>ZOOM::exception</literal> and subclasses + + The ZOOM::exception class is a virtual base + class, representing a diagnostic generated by the ZOOM-C++ library + or returned from a server. ### + + + class exception { + public: + exception (int code); + int errcode () const; + const char *errmsg () const; + }; + + + This class has three (so far) concrete subclasses: + + + + <literal>ZOOM::systemException</literal> + + The class has this declaration: + + + class systemException: public exception { + public: + systemException (); + int errcode () const; + const char *errmsg () const; + }; + + + + + <literal>ZOOM::bib1Exception</literal> + + The class has this declaration: + + + class bib1Exception: public exception { + public: + bib1Exception (int errcode, const char *addinfo); + int errcode () const; + const char *errmsg () const; + const char *addinfo () const; + }; + + + + + <literal>ZOOM::queryException</literal> + + The class has this declaration: + + + class queryException: public exception { + public: + static const int PREFIX = 1; + static const int CCL = 2; + queryException (int qtype, const char *source); + int errcode () const; + const char *errmsg () const; + const char *addinfo () const; + }; + + + + + Discussion + + ### discusson + + + + + References + + + + Section 3.7 (Exception) of the ZOOM Abstract API + + + + + Because C does not support exceptions, ZOOM-C has no API element + that corresponds directly with ZOOM-C++'s + exception class and its subclasses. The + closest thing is the ZOOM_connection_error + function described in + The Connections section of the documentation. + + + + +