X-Git-Url: http://git.indexdata.com/?p=yazpp-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;h=238c7d9fe171d83e79b49b9df07d33fdc9dcf8c2;hp=cc4485ecb94fa237ab765dfc46f0b9c242a52b43;hb=2604df665a484a7f11f89ce0ceb74b4280720beb;hpb=2ae9ebab1db8d27904766380a92ee49633f8a58f diff --git a/doc/zoom.xml b/doc/zoom.xml index cc4485e..238c7d9 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,35 +1,34 @@ - ZOOM-C++ - + + Introduction - ZOOM + ZOOM is the emerging standard API for information retrieval programming using the Z39.50 protocol. ZOOM's - Abstract API + Abstract API specifies semantics for classes representing key IR concepts such as connections, queries, result sets and records; and there are various - bindings + bindings specifying how those concepts should be represented in various programming languages. - The Yaz++ library includes an implementation of the C++ binding + 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 + 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> + #include <yazpp/zoom.h> using namespace ZOOM; @@ -37,20 +36,25 @@ { connection conn("z3950.loc.gov", 7090); conn.option("databaseName", "Voyager"); - resultSet rs(conn, prefixQuery("@attr attr 1=7 0253333490")); + conn.option("preferredRecordSyntax", "USMARC"); + resultSet rs(conn, prefixQuery("@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.) - + + + + For the sake of simplicity, this program does not check + for errors: we show a more robust version of the same program + later.) + + - Yaz++'s implementation of the C++ binding is a thin layer over Yaz's + 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 @@ -96,21 +100,18 @@ - + + <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); @@ -118,55 +119,103 @@ 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. - ### discusson + 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 f the ZOOM-C documentation + + + + + + + + <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: + 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 (); }; - - - - - + + + This class enables a query to be created by compiling 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 (); }; - + + + This class 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. + + + If query construction fails for either type of + query object - typically because the query + string itself is not valid PQN or CCL - then an + exception + is thrown. - + Discussion It will be readily recognised that these objects have no methods @@ -175,26 +224,59 @@ resultSet class's constructor. - ### discusson + 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> - 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. + 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); @@ -204,27 +286,74 @@ 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 uses attributes + that the server doesn't implement - then an + exception + is thrown. - ### discusson + 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. If the + method fails, for example because the requested record is out of + range, it throws an + exception. + + + + References + + + + Section 3.4 (Result Set) of the ZOOM Abstract API + + + + + The Result Sets section of the ZOOM-C documentation + + + + - + + <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 (); @@ -236,55 +365,171 @@ const char *render () const; const char *rawdata () const; }; - + + + Records returned from Z39.50 servers are encoded using a record + syntax: the various national MARC formats are commonly used for + bibliographic data, GRS-1 or XML for complex structured data, SUTRS + for simple human-readable text, etc. The + record::syntax enumeration specifies constants + representing common record syntaxes, and the + recsyn() method returns the value corresponding + to the record-syntax of the record on which it is invoked. + + + Because this interface uses an enumeration, it is difficult to + extend to other record syntaxes - for example, DANMARC, the MARC + variant widely used in Denmark. We might either grow the + enumeration substantially, or change the interface to return + either an integer or a string. + + + + + The simplest thing to do with a retrieved record is simply to + render() it. This returns a human-readable, but + not necessarily very pretty, representation of the contents of the + record. This is useful primarily for testing and debugging, since + the application has no control over how the record appears. + (The application must not + delete the returned string - it is ``owned'' by + the record object.) - ### discusson + More sophisticated applications will want to deal with the raw data + themselves: the rawdata() method returns it. + Its format will vary depending on the record syntax: SUTRS, MARC + and XML records are returned ``as is'', and GRS-1 records as a + pointer to their top-level node, which is a + Z_GenericRecord structure as defined in the + <yaz/z-grs.h> header file. + (The application must not + delete the returned data - it is ``owned'' by + the record object.) + + Perceptive readers will notice that there are no methods for access + to individual fields within a record. That's because the different + record syntaxes are so different that there is no even a uniform + notion of what a field is across them all, let alone a sensible way + to implement such a function. Fetch the raw data instead, and pick + it apart ``by hand''. + + + + Memory Management + + The record objects returned from + resultSet::getRecord() are ``owned'' by the + result set object: that means that the application is not + responsible for deleteing them - each + record is automatically deallocated when the + resultSet that owns it is + deleted. + + + Usually that's what you want: it means that you can easily fetch a + record, use it and forget all about it, like this: + + + resultSet rs(conn, query); + cout << rs.getRecord(0)->render(); + + + But sometimes you want a record to live on past + the lifetime of the resultSet from which it was + fetched. In this case, the clone(f) method can + be used to make an autonomous copy. The application must + delete it when it doesn't need it any longer: + + + record *rec; + { + resultSet rs(conn, query); + rec = rs.getRecord(0)->clone(); + // `rs' goes out of scope here, and is deleted + } + cout << rec->render(); + delete rec; + + + + + References + + + + Section 3.5 (Record) of the ZOOM Abstract API + + + + + The Records section of the ZOOM-C documentation + + + + - + + <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. ### - + or returned from a server. Its subclasses represent particular + kinds of error. + + + When any of the ZOOM methods fail, they respond by + throwing an object of type + exception or one of its subclasses. This most + usually happens with the connection constructor, + the various query constructors, the resultSet + constructor (which is actually the searching method) and + resultSet::getRecord(). + + + The base class has this declaration: + + class exception { public: exception (int code); int errcode () const; const char *errmsg () const; }; - - This class has three (so far) concrete subclasses: + + + It has three concrete subclasses: - + <literal>ZOOM::systemException</literal> - - The class has this declaration: - + class systemException: public exception { public: systemException (); int errcode () const; const char *errmsg () const; }; - + + + Represents a ``system error'', typically indicating that a system + call failed - often in the low-level networking code that + underlies Z39.50. errcode() returns the value + that the system variable errno had at the time + the exception was constructed; and errmsg() + returns a human-readable error-message corresponidng to that error + code. - + <literal>ZOOM::bib1Exception</literal> - - The class has this declaration: - + class bib1Exception: public exception { public: bib1Exception (int errcode, const char *addinfo); @@ -292,15 +537,28 @@ const char *errmsg () const; const char *addinfo () const; }; - + + + Represents an error condition communicated by a Z39.50 server. + errcode() returns the BIB-1 diagnostic code of + the error, and errmsg() a human-readable error + message corresponding to that code. addinfo() + returns any additional information associated with the error. + + + For example, if a ZOOM application tries to search in the + ``Voyager'' database of a server that does not have a database of + that name, a bib1Exception will be thrown in + which errcode() returns 109, + errmsg() returns the corresponding error + message ``Database unavailable'' and addinfo() + returns the name of the requested, but unavailable, database. - + <literal>ZOOM::queryException</literal> - - The class has this declaration: - + class queryException: public exception { public: static const int PREFIX = 1; @@ -310,14 +568,101 @@ const char *errmsg () const; const char *addinfo () const; }; - + + + This class represents an error in parsing a query into a form that + a Z39.50 can understand. It must be created with the + qtype parameter equal to one of the query-type + constants, which can be retrieved via the + errcode() method; errmsg() + returns an error-message specifying which kind of query was + malformed; and addinfo() returns a copy of the + query itself (that is, the value of source with + which the exception object was created.) - - Discussion + + Revised Sample Program + + Now we can revise the sample program from the + introduction + to catch exceptions and report any errors: + + + /* g++ -o zoom-c++-hw zoom-c++-hw.cpp -lzoompp -lyaz */ + + #include <iostream> + #include <yazpp/zoom.h> + + using namespace ZOOM; + + int main(int argc, char **argv) + { + try { + connection conn("z3950.loc.gov", 7090); + conn.option("databaseName", "Voyager"); + conn.option("preferredRecordSyntax", "USMARC"); + resultSet rs(conn, prefixQuery("@attr 1=7 0253333490")); + const record *rec = rs.getRecord(0); + cout << rec->render() << endl; + } catch (systemException &e) { + cerr << "System error " << + e.errcode() << " (" << e.errmsg() << ")" << endl; + } catch (bib1Exception &e) { + cerr << "BIB-1 error " << + e.errcode() << " (" << e.errmsg() << "): " << e.addinfo() << endl; + } catch (queryException &e) { + cerr << "Query error " << + e.errcode() << " (" << e.errmsg() << "): " << e.addinfo() << endl; + } catch (exception &e) { + cerr << "Error " << + e.errcode() << " (" << e.errmsg() << ")" << endl; + } + } + + + The heart of this program is the same as in the original version, + but it's now wrapped in a try block followed by + several catch blocks which try to give helpful + diagnostics if something goes wrong. + + + The first such block diagnoses system-level errors such as memory + exhaustion or a network connection being broken by a server's + untimely death; the second catches errors at the Z39.50 level, + such as a server's report that it can't provide records in USMARC + syntax; the third is there in case there's something wrong with + the syntax of the query (although in this case it's correct); and + finally, the last catch block is a + belt-and-braces measure to be sure that nothing escapes us. + + + + + References + + + + Section 3.7 (Exception) of the ZOOM Abstract API + + + + + Bib-1 Diagnostics on the + Z39.50 Maintenance Agency site. + + + - ### discusson + 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. @@ -333,7 +678,7 @@ sgml-always-quote-attributes:t sgml-indent-step:1 sgml-indent-data:t - sgml-parent-document: "zebra.xml" + sgml-parent-document: "yazpp.xml" sgml-local-catalogs: nil sgml-namecase-general:t End: