-# $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;
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.
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
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
=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()