X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=238c7d9fe171d83e79b49b9df07d33fdc9dcf8c2;hb=55119d24b44e72b7bfef2e5a67da4964c0cd16e4;hp=0d3fcab5f94e22ef552d439935b01d12c8d92eb3;hpb=096af05205c65b89240855fc35ad3e898050d5e4;p=yazpp-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index 0d3fcab..238c7d9 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,37 +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; @@ -39,21 +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; } - + + + + For the sake of simplicity, this program does not check + for errors: we show a more robust version of the same program + later.) + + - (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 + 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 @@ -143,24 +144,24 @@ (links below). - + References - Section 3.2 (Connection) of the ZOOM Abstract API - - - - - The Connections section of the ZOOM-C documentation - - - - - + + + + + The Connections section f the ZOOM-C documentation + + + + + @@ -172,11 +173,8 @@ a specific query notation. - + <literal>ZOOM::prefixQuery</literal> - - The class has this declaration: - class prefixQuery : public query { public: @@ -184,19 +182,15 @@ ~prefixQuery (); }; - - It enables a query to be created from Yaz's cryptic but - powerful - Prefix Query Notation (PQN). - - - - + + 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: @@ -205,17 +199,23 @@ }; - It enables a query to be created using the simpler but less - expressive - Common Command Language (CCL). + 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 + 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 @@ -242,18 +242,18 @@ - + References - Section 3.3 (Query) of the ZOOM Abstract API - The Queries section of the ZOOM-C documentation @@ -292,8 +292,8 @@ 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 + the search fails - for example, because the query uses attributes + that the server doesn't implement - then an exception is thrown. @@ -318,21 +318,24 @@ 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. + 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 @@ -364,21 +367,105 @@ }; - ### discusson + 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.) + + + 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 @@ -392,7 +479,20 @@ 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 { @@ -403,14 +503,11 @@ }; - 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: @@ -419,13 +516,19 @@ 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: @@ -435,13 +538,26 @@ 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: @@ -453,24 +569,91 @@ 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. + - ### discusson + 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. + + Because C does not support exceptions, ZOOM-C has no API element @@ -478,7 +661,7 @@ exception class and its subclasses. The closest thing is the ZOOM_connection_error function described in - The Connections section of the documentation. @@ -495,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: