From 2ae9ebab1db8d27904766380a92ee49633f8a58f Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Tue, 8 Oct 2002 23:52:40 +0000 Subject: [PATCH] skeleton --- doc/zoom.xml | 329 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 324 insertions(+), 5 deletions(-) diff --git a/doc/zoom.xml b/doc/zoom.xml index 29f248f..cc4485e 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,10 +1,329 @@ - - 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> + + SEE ALSO + Section 3.2 (Connection) of the ZOOM Abstract API + + + 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); + }; + + + + ### discusson + + + + + <literal>ZOOM::query</literal> and subclasses + + SEE ALSO + Section 3.3 (Query) of the ZOOM Abstract API + + + 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: + + + + <literal>ZOOM::prefixQuery</literal> + + The class has this declaration: + + class prefixQuery : public query { + public: + prefixQuery (const char *pqn); + ~prefixQuery (); + }; + + + + + + <literal>ZOOM::CCLQuery</literal> + + The class has this declaration: + + class CCLQuery : public query { + public: + CCLQuery (const char *ccl, void *qualset); + ~CCLQuery (); + }; + + + + + + 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. + + + ### discusson + + + + + + <literal>ZOOM::resultSet</literal> + + SEE ALSO + Section 3.4 (Result Set) of the ZOOM Abstract API + + + A ZOOM::resultSet object represents a set of + record identified by a query that has been executed against a + particular 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; + }; + + + + ### discusson + + + + + <literal>ZOOM::record</literal> + + SEE ALSO + Section 3.5 (Record) of the ZOOM Abstract API + + + 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 + + + + + <literal>ZOOM::exception</literal> and subclasses + + SEE ALSO + Section 3.7 (Exception) of the ZOOM Abstract API + + + 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 + + + + +