X-Git-Url: http://git.indexdata.com/?p=yazpp-moved-to-github.git;a=blobdiff_plain;f=doc%2Fzoom.xml;fp=doc%2Fzoom.xml;h=0000000000000000000000000000000000000000;hp=238c7d9fe171d83e79b49b9df07d33fdc9dcf8c2;hb=8c34dbe31f7d0051b2e2372dcfabb4308da0367e;hpb=2ae1c056431fb14ee4dafaeb1ad54381848083ed diff --git a/doc/zoom.xml b/doc/zoom.xml deleted file mode 100644 index 238c7d9..0000000 --- a/doc/zoom.xml +++ /dev/null @@ -1,685 +0,0 @@ - - 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 <yazpp/zoom.h> - - using namespace ZOOM; - - int main(int argc, char **argv) - { - 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; - } - - - - 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 - 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 f 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> - - 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> - - 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 - 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 uses attributes - that the server doesn't implement - 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. 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> - - 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; - }; - - - 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 - - - - - - - - - <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. 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; - }; - - - It has three concrete subclasses: - - - - <literal>ZOOM::systemException</literal> - - 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> - - class bib1Exception: public exception { - public: - bib1Exception (int errcode, const char *addinfo); - int errcode () const; - 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> - - 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; - }; - - - 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.) - - - - - 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. - - - - - 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. - - - - - - -