X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=lib%2FZOOM.pod;h=bf706ead247eca0e3de289162372be42e3f28764;hb=7520ed846be21307038247f134786749d392ed83;hp=20694d4c00906612ff34378853bbf7ac2e2c86f8;hpb=202fa72d1f5647efa7299a32df31de8f64bf7733;p=ZOOM-Perl-moved-to-github.git diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index 20694d4..bf706ea 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,4 +1,4 @@ -# $Id: ZOOM.pod,v 1.21 2005-12-13 16:22:41 mike Exp $ +# $Id: ZOOM.pod,v 1.27 2005-12-22 14:11:17 mike Exp $ use strict; use warnings; @@ -49,11 +49,15 @@ C, C and C. -Of these, the Query class is abstract, and has two concrete +Of these, the Query class is abstract, and has three concrete subclasses: -C +C, +C and -C. +C. +Finally, it also provides a +C +module which supplies a useful general-purpose logging facility. Many useful ZOOM applications can be built using only the Connection, ResultSet, Record and Exception classes, as in the example code-snippet above. @@ -94,7 +98,8 @@ enumeration or drawn from the BIB-1 diagnostic set. =head2 ZOOM::event() -B +B +Lark's vomit. Do not read this section. $which = ZOOM::event([ $conn1, $conn2, $conn3 ]); @@ -105,7 +110,8 @@ the connections it occurred on. The return value is a 1-based index into the list; 0 is returned if no event occurs within the longest timeout specified by the C options of all the connections. -B +B +This function is not yet implemented. =head1 CLASSES @@ -292,13 +298,18 @@ and it creates and returns a new ResultSet object representing the set of records resulting from the search. Since queries using PQF (Prefix Query Format) are so common, we make -them a special case by providing a C method. This is +them a special case by providing a C method. This is identical to C except that it accepts a string containing the query rather than an object, thereby obviating the need to create a C object. See the documentation of that class for information about PQF. -=head4 scan() +=head4 scan() / scan_pqf() + + $rs = $conn->scan(new ZOOM::Query::CQL('title=dinosaur')); + # The next two lines are equivalent + $rs = $conn->scan(new ZOOM::Query::PQF('@attr 1=4 dinosaur')); + $rs = $conn->scan_pqf('@attr 1=4 dinosaur'); Many Z39.50 servers allow you to browse their indexes to find terms to search for. This is done using the C method, which creates and @@ -314,13 +325,11 @@ or single words (e.g. the title ``I'', or the four words ``Back'', ``Empire'', ``Strikes'' and ``The'', interleaved with words from other titles in the same index. -All of this is done by using a single term from the PQF query as the -C argument. (At present, only PQF is supported, although -there is no reason in principle why CQL and other query syntaxes -should not be supported in future). The attributes associated with +All of this is done by using a Query object representing a query of a +single term as the C argument. The attributes associated with the term indicate which index is to be used, and the term itself indicates the point in the index at which to start the scan. For -example, if the argument is C<@attr 1=4 fish>, then +example, if the argument is the query C<@attr 1=4 fish>, then =over 4 @@ -370,6 +379,12 @@ each one returned in the ScanSet. By default, no terms are skipped, but overriding this can be useful to get a high-level overview of the index. +Since scans using PQF (Prefix Query Format) are so common, we make +them a special case by providing a C method. This is +identical to C except that it accepts a string containing the +query rather than an object, thereby obviating the need to create a +C object. + =back =head4 package() @@ -392,9 +407,10 @@ the C documentation. Returns a C enumerated value indicating the type of the last event that occurred on the connection. This is used only in complex asynchronous applications - see the section below on - for more information. +C for more information. -B +B +This method has not been tested. =head4 destroy() @@ -424,7 +440,7 @@ need the C, C and C methods. There is no C method nor any other explicit constructor. The only way to create a new ResultSet is by using C (or -C) on a Connection. +C) on a Connection. See the description of the C class in the ZOOM Abstract API at @@ -922,7 +938,7 @@ types of query. The sole purpose of a Query object is to be used in a C on a Connection; because PQF is such a common special case, the shortcut Connection method C 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 @@ -945,6 +961,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, 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 + =back See the description of the C class in the ZOOM Abstract @@ -955,14 +984,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 method -. +C. + + $conn->option(cqlfile => "samples/cql/pqf.properties"); + $q = new ZOOM::Query::CQL2RPN('title=dinosaur', $conn); + +Note that for the C subclass, the Connection +must also be passed into the constructor. This is used for two +purposes: first, its C 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-Eerrcode()> and related +methods. =head4 sortby() @@ -973,9 +1013,6 @@ is run on the query, the result is automatically sorted. The sort specification language is the same as the C sort-specification type of the C method C, described above. -B - =head4 destroy() $p->destroy() @@ -1076,7 +1113,32 @@ be useful. Though I can't imagine how. =head4 set_callback() -I<###> + sub cb { + ($udata, $key) = @; + return "$udata-$key-$udata"; + } + $o->set_callback(\&cb, "xyz"); + assert($o->option("foo") eq "xyz-foo-xyz"); + +This method allows a callback function to be installed in an option +set, so that the values of options can be calculated algorithmically +rather than, as usual, looked up in a table. Along with the callback +function itself, an additional datum is provided: when an option is +subsequently looked up, this datum is passed to the callback function +along with the key; and its return value is returned to the caller as +the value of the option. + +B +Although it ought to be possible to specify callback function using +the C<\&name> syntax above, or a literal C code +reference, the complexities of the Perl-internal memory management +system mean that the function must currently be specified as a string +containing the fully-qualified name, e.g. C<"main::cb">.> + +B +The current implementation of the this method leaks memory, not only +when the callback is installed, but on every occasion that it is +consulted to look up an option value. =head4 destroy() @@ -1123,9 +1185,10 @@ C, C, C, C, -C +C, +C and -C, +C, each of which specifies a client-side error. These codes constitute the C diagnostic set. @@ -1156,6 +1219,111 @@ C. You almost certainly don't need to know about this. Frankly, I'm not sure how to use it myself. +=head1 LOGGING + + ZOOM::Log::init_level(ZOOM::Log::mask_str("zoom,myapp,-warn")); + ZOOM::Log::log("myapp", "starting up with pid ", $$); + +Logging facilities are provided by a set of functions in the +C module. Note that C is not a class, and it +is not possible to create C objects: the API is imperative, +reflecting that of the underlying YAZ logging facilities. Although +there are nine logging functions altogether, you can ignore nearly +all of them: most applications that use logging will begin by calling +C and C once each, as above, and will then +repeatedly call C. + +=head2 mask_str() + + $level = ZOOM::Log::mask_str("zoom,myapp,-warn"); + +Returns an integer corresponding to the log-level specified by the +parameter. This is a string of zero or more comma-separated +module-names, each indicating an individual module to be either added +to the default log-level or removed from it (for those components +prefixed by a minus-sign). The names may be those of either standard +YAZ-logging modules such as C, C and C, or custom +modules such as C in the example above. The module C +requests logging from the ZOOM module itself, which may be helpful for +debugging. + +Note that calling this function does not in any way change the logging +state: it merely returns a value. To change the state, this value +must be passed to C. + +=head2 module_level() + + $level = ZOOM::Log::module_level("zoom"); + ZOOM::Log::log($level, "all systems clear: thrusters invogriated"); + +Returns the integer corresponding to the single log-level specified as +the parameter, or zero if that level has not been registered by a +prior call to C. Since C accepts either a numeric +log-level or a string, there is no reason to call this function; but, +what the heck, maybe you enjoy that kind of thing. Who are we to +judge? + +=head2 init_level() + + ZOOM::Log::init_level($level); + +Initialises the log-level to the specified integer, which is a bitmask +of values, typically as returned from C. All subsequent +calls to C made with a log-level that matches one of the bits +in this mask will result in a log-message being emitted. All logging +can be turned off by calling C. + +=head2 init_prefix() + + ZOOM::Log::init_prefix($0); + +Initialises a prefix string to be included in all log-messages. + +=head2 init_file() + + ZOOM::Log::init_file("/tmp/myapp.log"); + +Initialises the output file to be used for logging: subsequent +log-messages are written to the nominated file. If this function is +not called, log-messages are written to the standard error stream. + +=head2 init() + + ZOOM::Log::init($level, $0, "/tmp/myapp.log"); + +Initialises the log-level, the logging prefix and the logging output +file in a single operation. + +=head2 time_format() + + ZOOM::Log::time_format("%Y-%m-%d %H:%M:%S"); + +Sets the format in which log-messages' timestamps are emitted, by +means of a format-string like that used in the C function +C. The example above emits year, month, day, hours, +minutes and seconds in big-endian order, such that timestamps can be +sorted lexicographically. + +=head2 init_max_size() + +(This doesn't seem to work, so I won't bother describing it.) + +=head2 log() + + ZOOM::Log::log(8192, "reducing to warp-factor $wf"); + ZOOM::Log::log("myapp", "starting up with pid ", $$); + +Provided that the first argument, log-level, is among the modules +previously established by C, this function emits a +log-message made up of a timestamp, the prefix supplied to +C, if any, and the concatenation of all arguments after +the first. The message is written to the standard output stream, or +to the file previous specified by C if this has been +called. + +The log-level argument may be either a numeric value, as returned from +C, or a string containing the module name. + =head1 SEE ALSO The ZOOM abstract API,