X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Fzoom.xml;h=238c7d9fe171d83e79b49b9df07d33fdc9dcf8c2;hb=55119d24b44e72b7bfef2e5a67da4964c0cd16e4;hp=cba9e9ea01e8f7b80b32e621f2e1902fcfa1b284;hpb=994ac888aec8e10aaaf578687b4d554b300cb4fd;p=yazpp-moved-to-github.git diff --git a/doc/zoom.xml b/doc/zoom.xml index cba9e9e..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; } - - - (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 @@ -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,7 +173,7 @@ a specific query notation. - + <literal>ZOOM::prefixQuery</literal> class prefixQuery : public query { @@ -181,15 +182,14 @@ ~prefixQuery (); }; - - This class enables a query to be created by compiling 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> class CCLQuery : public query { @@ -201,10 +201,9 @@ This class enables a query to be created using the simpler but less expressive - Common Command Language (CCL). + 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. @@ -216,7 +215,7 @@ - + Discussion It will be readily recognised that these objects have no methods @@ -243,7 +242,7 @@ - + References @@ -254,7 +253,7 @@ - The Queries section of the ZOOM-C documentation @@ -325,7 +324,7 @@ exception. - + References @@ -336,7 +335,7 @@ - The Result Sets section of the ZOOM-C documentation @@ -417,10 +416,10 @@ it apart ``by hand''. - + Memory Management - The record obejcts returned from + 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 @@ -432,10 +431,10 @@ 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 @@ -443,7 +442,7 @@ 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); @@ -452,10 +451,10 @@ } cout << rec->render(); delete rec; - + - + References @@ -466,7 +465,7 @@ - The Records section of the ZOOM-C documentation @@ -507,7 +506,7 @@ It has three concrete subclasses: - + <literal>ZOOM::systemException</literal> class systemException: public exception { @@ -528,7 +527,7 @@ - + <literal>ZOOM::bib1Exception</literal> class bib1Exception: public exception { @@ -557,7 +556,7 @@ - + <literal>ZOOM::queryException</literal> class queryException: public exception { @@ -583,7 +582,64 @@ - + + 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 @@ -594,10 +650,8 @@ - Bib-1 Diagnostics on the - Z39.50 Maintenance Agency site. + Bib-1 Diagnostics on the + Z39.50 Maintenance Agency site. @@ -607,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. @@ -624,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: