-### Add documentation for logging.
-
-# $Id: ZOOM.pod,v 1.26 2005-12-22 11:58:03 mike Exp $
+# $Id: ZOOM.pod,v 1.31 2006-04-03 14:08:29 mike Exp $
use strict;
use warnings;
use ZOOM;
eval {
- $conn = new ZOOM::Connection($host, $port)
+ $conn = new ZOOM::Connection($host, $port,
+ databaseName => "mydb");
$conn->option(preferredRecordSyntax => "usmarc");
$rs = $conn->search_pqf('@attr 1=4 dinosaur');
$n = $rs->size();
C<ZOOM::Query::PQF>
and
C<ZOOM::Query::CQL2RPN>.
+Finally, it also provides a
+C<ZOOM::Query::Log>
+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.
$conn = new ZOOM::Connection("indexdata.dk:210/gils");
$conn = new ZOOM::Connection("tcp:indexdata.dk:210/gils");
$conn = new ZOOM::Connection("http:indexdata.dk:210/gils");
+ $conn = new ZOOM::Connection("indexdata.dk", 210,
+ databaseName => "mydb",
+ preferredRecordSyntax => "marc");
Creates a new Connection object, and immediately connects it to the
specified server. If you want to make a new Connection object but
number of the Z39.50 server to connect to; in the latter case, the
single argument is a YAZ service-specifier string of the form
+When the two-option form is used (which may be done using a vacuous
+second argument of zero), any number of additional argument pairs may
+be provided, which are interpreted as key-value pairs to be set as
+options after the Connection object is created but before it is
+connected to the server. This is a convenient way to set options,
+including those that must be set before connecting such as
+authentication tokens.
+
=over 4
=item
=head4 render()
- print $rec->render()
+ print $rec->render();
+ print $rec->render("charset=latin1,utf8");
Returns a human-readable representation of the record. Beyond that,
no promises are made: careful programs should not make assumptions
about the format of the returned string.
+If the optional argument is provided, then it is interpreted as in the
+C<get()> method (q.v.)
+
This method is useful mostly for debugging.
=head4 raw()
- use MARC::Record
+ use MARC::Record;
$raw = $rec->raw();
$marc = new_from_usmarc MARC::Record($raw);
+ $trans = $rec->render("charset=latin1,utf8");
Returns an opaque blob of data that is the raw form of the record.
Exactly what this is, and what you can do with it, varies depending on
module; GRS-1 record will be ... gosh, what an interesting question.
But no-one uses GRS-1 any more, do they?
+If the optional argument is provided, then it is interpreted as in the
+C<get()> method (q.v.)
+
+=head4 get()
+
+ $raw = $rec->get("raw");
+ $rendered = $rec->get("render");
+ $trans = $rec->get("render;charset=latin1,utf8");
+ $trans = $rec->get("render", "charset=latin1,utf8");
+
+This is the underlying method used by C<render()> and C<raw()>, and
+which in turn delegates to the C<ZOOM_record_get()> function of the
+underlying ZOOM-C library. Most applications will find it more
+natural to work with C<render()> and C<raw()>.
+
+C<get()> may be called with either one or two arguments. The
+two-argument form is syntactic sugar: the two arguments are simply
+joined with a semi-colon to make a single argument, so the third and
+fourth example invocations above are equivalent. The second argument
+(or portion of the first argument following the semicolon) is used in
+the C<type> argument of C<ZOOM_record_get()>, as described in
+http://www.indexdata.com/yaz/doc/zoom.records.tkl
+This is useful primarily for invoking the character-set transformation
+- in the examples above, from ISO Latin-1 to UTF-8 Unicode.
+
=head4 clone() / destroy()
$rec = $rs->record($i);
finally, destroy the package.
Package options are listed at
-http://indexdata.com/yaz/doc/zoom.ext.html
+http://indexdata.com/yaz/doc/zoom.ext.tkl
The particular options that have meaning are determined by the
top-level operation string specified as the argument to C<send()>.
=head4 send()
- $p->send("createdb");
+ $p->send("create");
Sends a package to the server associated with the Connection that
created it. Problems are reported by throwing an exception. The
C<QUERY_PQF>,
C<SORTBY>,
C<CLONE>,
-C<PACKAGE>
+C<PACKAGE>,
+C<SCANTERM>
and
-C<SCANTERM>,
+C<LOGLEVEL>,
each of which specifies a client-side error. These codes constitute
the C<ZOOM> diagnostic set.
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<ZOOM::Log> module. Note that C<ZOOM::Log> is not a class, and it
+is not possible to create C<ZOOM::Log> 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<mask_str()> and C<init_level()> once each, as above, and will then
+repeatedly call C<log()>.
+
+=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<fatal>, C<debug> and C<warn>, or custom
+modules such as C<myapp> in the example above. The module C<zoom>
+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<init_level()>.
+
+=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<mask_str()>. Since C<log()> 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<mask_str()>. All subsequent
+calls to C<log()> 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<init_level(0)>.
+
+=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<strftime()>. 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<init_level()>, this function emits a
+log-message made up of a timestamp, the prefix supplied to
+C<init_prefix()>, 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<init_file()> if this has been
+called.
+
+The log-level argument may be either a numeric value, as returned from
+C<module_level()>, or a string containing the module name.
+
=head1 SEE ALSO
The ZOOM abstract API,
projects / ZOOM-Perl-moved-to-github.git / blobdiff