From 994ac888aec8e10aaaf578687b4d554b300cb4fd Mon Sep 17 00:00:00 2001 From: Mike Taylor Date: Thu, 10 Oct 2002 22:48:10 +0000 Subject: [PATCH] First finished version! --- doc/zoom.xml | 223 +++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 176 insertions(+), 47 deletions(-) diff --git a/doc/zoom.xml b/doc/zoom.xml index 0d3fcab..cba9e9e 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,24 +1,24 @@ - + 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 for ZOOM, enabling quick, easy development of client applications. @@ -148,13 +148,13 @@ - Section 3.2 (Connection) of the ZOOM Abstract API - The Connections section of the ZOOM-C documentation @@ -174,9 +174,6 @@ <literal>ZOOM::prefixQuery</literal> - - The class has this declaration: - class prefixQuery : public query { public: @@ -185,18 +182,15 @@ }; - It enables a query to be created from Yaz's cryptic but - powerful - Prefix Query Notation (PQN). <literal>ZOOM::CCLQuery</literal> - - The class has this declaration: - class CCLQuery : public query { public: @@ -205,14 +199,21 @@ }; - It 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. + @@ -247,13 +248,13 @@ - Section 3.3 (Query) of the ZOOM Abstract API - The Queries section of the ZOOM-C documentation @@ -292,8 +293,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,7 +319,10 @@ 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. @@ -326,13 +330,13 @@ - Section 3.4 (Result Set) of the ZOOM Abstract API - The Result Sets section of the ZOOM-C documentation @@ -364,21 +368,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 obejcts 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 +480,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 +504,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 +517,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 +539,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,12 +570,16 @@ const char *addinfo () const; }; - - - - Discussion - ### discusson + 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.) @@ -467,10 +588,18 @@ - 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 +607,7 @@ exception class and its subclasses. The closest thing is the ZOOM_connection_error function described in - The Connections section of the documentation. -- 1.7.10.4