Added MarcXchange support.

[yaz-moved-to-github.git] / doc / tools.xml

diff --git a/doc/tools.xml b/doc/tools.xml
index add24b4..d9a57b7 100644 (file)
--- a/doc/tools.xml
+++ b/doc/tools.xml
@@ -1,4 +1,4 @@
-<!-- $Id: tools.xml,v 1.41 2004-11-21 21:55:15 adam Exp $ -->
+<!-- $Id: tools.xml,v 1.44 2005-02-08 13:51:30 adam Exp $ -->
  <chapter id="tools"><title>Supporting Tools</title>
   
   <para>
@@ -1803,12 +1803,12 @@ typedef struct oident
    production use of those applications.  
   </para>
   <para>
-   The log functions are declared in header <filename>yaz/ylog.h</filename>
+   The log functions are declared in header <filename>yaz/log.h</filename>
     and implemented in <filename>src/log.c</filename>.
     Due to name clash with syslog and some math utilities the logging
     interface has been modified as of YAZ 2.0.29. The obsolete interface
-    is still available if the application includes
-    <filename>yaz/log.h</filename>. The key points of the interface are:
+    is still available if in header file <filename>yaz/log.h</filename>.
+    The key points of the interface are:
   </para>
   <screen>
    void yaz_log(int level, const char *fmt, ...)
@@ -1835,10 +1835,11 @@ typedef struct oident
    The <literal>log level</literal> is a bit mask, that says on which level(s)
    the log entry should be made, and optionally set some behaviour of the
    logging. In the most simple cases, it can be one of <literal>YLOG_FATAL,
-     YLOG_DEBUG, YLOG_WARN, YLOG_LOG</literal>. Those can be combined with bits
-    that modify the way the log entry is written:<literal>YLOG_ERRNO,
-     YLOG_NOTIME, YLOG_FLUSH</literal>.
-    Most of the rest of the bits are deprecated, and should not be used.
+   YLOG_DEBUG, YLOG_WARN, YLOG_LOG</literal>. Those can be combined with bits
+   that modify the way the log entry is written:<literal>YLOG_ERRNO,
+   YLOG_NOTIME, YLOG_FLUSH</literal>.
+   Most of the rest of the bits are deprecated, and should not be used. Use
+   the dynamic log levels instead.
   </para>
 
   <para>
@@ -1874,6 +1875,17 @@ typedef struct oident
   </para>
 
   <para>
+   Yaz uses the following dynamic log levels:
+   <literal>server, session, request, requestdetail</literal> for the server
+   functionality.
+   <literal>zoom</literal> for the zoom client api.
+   <literal>ztest</literal> for the simple test server.
+   <literal>malloc, nmem, odr, eventl</literal> for internal debugging of yaz itself.
+   Of course, any program using yaz is welcome to define as many new ones, as
+   it needs.
+  </para>
+
+  <para>
    By default the log is written to stderr, but this can be changed by a call
    to <function>yaz_log_init_file</function> or
    <function>yaz_log_init</function>. If the log is directed to a file, the
@@ -1884,6 +1896,15 @@ typedef struct oident
    rotation feature.
   </para>
 
+  <screen>
+  A typical yaz-log looks like this
+  13:23:14-23/11 yaz-ztest(1) [session] Starting session from tcp:127.0.0.1 (pid=30968)
+  13:23:14-23/11 yaz-ztest(1) [request] Init from 'YAZ' (81) (ver 2.0.28) OK
+  13:23:17-23/11 yaz-ztest(1) [request] Search Z: @attrset Bib-1 foo  OK:7 hits
+  13:23:22-23/11 yaz-ztest(1) [request] Present: [1] 2+2  OK 2 records returned
+  13:24:13-23/11 yaz-ztest(1) [request] Close OK
+  </screen>
+
   <para>
    The log entries start with a time stamp. This can be omitted by setting the
    <literal>YLOG_NOTIME</literal> bit in the loglevel. This way automatic tests
@@ -1894,10 +1915,11 @@ typedef struct oident
   </para>
 
   <para>
-   Next in a log line comes the prefix, often the name of the program. Then
+   Next in a log line comes the prefix, often the name of the program. For
+   yaz-based servers, it can also contain the session number. Then
    comes one or more logbits in square brackets, depending on the logging
    level set by <function>yaz_log_init_level</function> and the loglevel
-   passed to <function>yaz_log_init_level</function>. Finally comes all format
+   passed to <function>yaz_log_init_level</function>. Finally comes the format
    string and additional values passed to <function>yaz_log</function>
   </para>
 
@@ -1915,7 +1937,10 @@ typedef struct oident
   </para>
 
   <para>
-   The dynamic log levels and log rotation were introduced in &yaz; 2.0.28.
+   The dynamic log levels and log rotation were introduced in &yaz; 2.0.28. At
+   the same time, the log bit names were changed from
+   <literal>LOG_something</literal> to <literal>YLOG_something</literal>, 
+   to avoid collision with <filename>syslog.h</filename>.
   </para>
 
   </sect1>
@@ -1942,6 +1967,7 @@ typedef struct oident
     #define YAZ_MARC_OAIMARC   2
     #define YAZ_MARC_MARCXML   3
     #define YAZ_MARC_ISO2709   4
+    #define YAZ_MARC_XCHANGE   5
 
     /* supply iconv handle for character set conversion .. */
     void yaz_marc_iconv(yaz_marc_t mt, yaz_iconv_t cd);