From f2269bac5ee3e10e9b8ba3ac5af3bc0fb7382edf Mon Sep 17 00:00:00 2001
From: mike <mike>
Date: Thu, 22 Dec 2005 11:58:03 +0000
Subject: [PATCH] Documentation for client-side CQL.

---
 lib/ZOOM.pod |   43 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 35 insertions(+), 8 deletions(-)

diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod
index 23c2bef..f0d8dec 100644
--- a/lib/ZOOM.pod
+++ b/lib/ZOOM.pod
@@ -1,4 +1,6 @@
-# $Id: ZOOM.pod,v 1.25 2005-12-21 00:25:51 mike Exp $
+### Add documentation for logging.
+
+# $Id: ZOOM.pod,v 1.26 2005-12-22 11:58:03 mike Exp $
 
 use strict;
 use warnings;
@@ -49,11 +51,12 @@ C<ZOOM::Record>,
 C<ZOOM::ScanSet>
 and
 C<ZOOM::Package>.
-Of these, the Query class is abstract, and has two concrete
+Of these, the Query class is abstract, and has three concrete
 subclasses:
-C<ZOOM::Query::CQL>
+C<ZOOM::Query::CQL>,
+C<ZOOM::Query::PQF>
 and
-C<ZOOM::Query::PQF>.
+C<ZOOM::Query::CQL2RPN>.
 Many useful ZOOM applications can be built using only the Connection,
 ResultSet, Record and Exception classes, as in the example
 code-snippet above.
@@ -934,7 +937,7 @@ types of query.  The sole purpose of a Query object is to be used in a
 C<search()> on a Connection; because PQF is such a common special
 case, the shortcut Connection method C<search_pqf()> is provided.
 
-The following Query subclasses are provided, both of the providing the
+The following Query subclasses are provided, each providing the
 same set of methods described below:
 
 =over 4
@@ -957,6 +960,19 @@ http://www.loc.gov/standards/sru/cql/
 and in a slight out-of-date but nevertheless useful tutorial at
 http://zing.z3950.org/cql/intro.html
 
+=item ZOOM::Query::CQL2RPN
+
+Implements CQL by compiling it on the client-side into a Z39.50
+Type-1 (RPN) query, and sending that.  This provides essentially the
+same functionality as C<ZOOM::Query::CQL>, but it will work against
+any standard Z39.50 server rather than only against the small subset
+that support CQL natively.  The drawback is that, because the
+compilation is done on the client side, a configuration file is
+required to direct the mapping of CQL constructs such as index names,
+relations and modifiers into Type-1 query attributes.  An example CQL
+configuration file is included in the ZOOM-Perl distribution, in the
+file C<samples/cql/pqf.properties>
+
 =back
 
 See the description of the C<Query> class in the ZOOM Abstract
@@ -967,14 +983,25 @@ http://zoom.z3950.org/api/zoom-current.html#3.3
 
 =head4 new()
 
- $q = new ZOOM::Query::CQL('title=dinosaur'));
- $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur'));
+ $q = new ZOOM::Query::CQL('title=dinosaur');
+ $q = new ZOOM::Query::PQF('@attr 1=4 dinosaur');
 
 Creates a new query object, compiling the query passed as its argument
 according to the rules of the particular query-type being
 instantiated.  If compilation fails, an exception is thrown.
 Otherwise, the query may be passed to the C<Connection> method
-<search()>.
+C<search()>.
+
+ $conn->option(cqlfile => "samples/cql/pqf.properties");
+ $q = new ZOOM::Query::CQL2RPN('title=dinosaur', $conn);
+
+Note that for the C<ZOOM::Query::CQL2RPN> subclass, the Connection
+must also be passed into the constructor.  This is used for two
+purposes: first, its C<cqlfile> option is used to find the CQL
+configuration file that directs the translations into RPN; and second,
+if compilation fails, then diagnostic information is cached in the
+Connection and be retrieved using C<$conn-E<gt>errcode()> and related
+methods.
 
 =head4 sortby()
 
-- 
1.7.10.4