From 7520ed846be21307038247f134786749d392ed83 Mon Sep 17 00:00:00 2001 From: mike Date: Thu, 22 Dec 2005 14:11:17 +0000 Subject: [PATCH] Documentation for logging facilities. --- lib/ZOOM.pod | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 112 insertions(+), 5 deletions(-) diff --git a/lib/ZOOM.pod b/lib/ZOOM.pod index f0d8dec..bf706ea 100644 --- a/lib/ZOOM.pod +++ b/lib/ZOOM.pod @@ -1,6 +1,4 @@ -### Add documentation for logging. - -# $Id: ZOOM.pod,v 1.26 2005-12-22 11:58:03 mike Exp $ +# $Id: ZOOM.pod,v 1.27 2005-12-22 14:11:17 mike Exp $ use strict; use warnings; @@ -57,6 +55,9 @@ C, C and 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. @@ -1184,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. @@ -1217,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, -- 1.7.10.4