X-Git-Url: http://git.indexdata.com/?a=blobdiff_plain;f=doc%2Ftools.xml;h=1d79005aa4e9b89fd29175ca96f406b31d5c0fa3;hb=60f5103f542e3f6dd2e22b6df7015f7bc4b3a937;hp=01fb2c558d294f0e48b674a6102b3eb19015b9cb;hpb=a94620ffd6001681474a94f5de767f168d772d1c;p=yaz-moved-to-github.git diff --git a/doc/tools.xml b/doc/tools.xml index 01fb2c5..1d79005 100644 --- a/doc/tools.xml +++ b/doc/tools.xml @@ -1,4 +1,4 @@ - + Supporting Tools @@ -225,7 +225,7 @@ @and. Its semantics are described in section 3.7.2 (Proximity) of Z39.50 the standard itself, which can be read on-line at - + In PQF, the proximity operation is represented by a sequence @@ -294,7 +294,7 @@ (The numeric values of the relation and well-known unit-code parameters are taken straight from - the ASN.1 of the proximity structure in the standard.) @@ -305,6 +305,7 @@ dylan + "bob dylan" @@ -313,7 +314,9 @@ @or "dylan" "zimmerman" + @and @or dylan zimmerman when + @and when @or dylan zimmerman @@ -322,7 +325,8 @@ @set Result-1 - @and @set seta setb + + @and @set seta @set setb @@ -330,9 +334,13 @@ @attr 1=4 computer + @attr 1=4 @attr 4=1 "self portrait" + @attrset exp1 @attr 1=1 CategoryList + @attr gils 1=2008 Copenhagen + @attr 1=/book/title computer @@ -632,10 +640,8 @@ - The complete list of Bib-1 attributes can be found - - here - . + Refer to the complete + list of Bib-1 attributes It is also possible to specify non-numeric attribute values, @@ -932,10 +938,9 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, CQL - CQL + CQL - Common Query Language - was defined for the - SRW - protocol. + SRW protocol. In many ways CQL has a similar syntax to CCL. The objective of CQL is different. Where CCL aims to be an end-user language, CQL is the protocol @@ -944,8 +949,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, If you are new to CQL, read the - Gentle - Introduction. + Gentle Introduction. @@ -972,8 +976,7 @@ struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str, The parser converts CQL to - - XCQL. + XCQL. XCQL is an XML representation of CQL. XCQL is part of the SRW specification. However, since SRU supports CQL only, we don't expect XCQL to be widely used. @@ -1081,6 +1084,8 @@ struct cql_node { If an index is unspecified for a search term, index will be NULL. + + index_uri: index URi for search term or NULL if none could be resolved for the index. @@ -1174,7 +1179,7 @@ int cql_transform_buf(cql_transform_t ct, returns a non-zero SRW error code; otherwise zero is returned (conversion successful). The meanings of the numeric error codes are listed in the SRW specifications at - + If conversion fails, more information can be obtained by calling @@ -1214,7 +1219,7 @@ int cql_transform_FILE(cql_transform_t ct, - Specification of CQL to RPN mapping + Specification of CQL to RPN mappings The file supplied to functions cql_transform_open_FILE, @@ -1598,7 +1603,7 @@ typedef struct oident again, corresponding to the specific OIDs defined by the standard. Refer to the - + Registry of Z39.50 Object Identifiers for the whole list. @@ -1798,14 +1803,17 @@ typedef struct oident Log - Yaz has evolved a fairly complex log system which should be useful both - for debugging &yaz; itself, debugging applications that use yaz, and for + &yaz; has evolved a fairly complex log system which should be useful both + for debugging &yaz; itself, debugging applications that use &yaz;, and for production use of those applications. - The log functions are declared in log.h and - implemented in log.c. The key points of the interface - are: + The log functions are declared in header yaz/log.h + and implemented in src/log.c. + 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 in header file yaz/log.h. + The key points of the interface are: void yaz_log(int level, const char *fmt, ...) @@ -1831,15 +1839,16 @@ typedef struct oident The log level 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 LOG_FATAL, - LOG_DEBUG, LOG_WARN, LOG_LOG. Those can be combined with bits - that modify the way the log entry is written:LOG_ERRNO, LOG_NOTIME, - LOG_FLUSH. Most of the rest of the bits are deprecated, and - should not be used. + logging. In the most simple cases, it can be one of YLOG_FATAL, + YLOG_DEBUG, YLOG_WARN, YLOG_LOG. Those can be combined with bits + that modify the way the log entry is written:YLOG_ERRNO, + YLOG_NOTIME, YLOG_FLUSH. + Most of the rest of the bits are deprecated, and should not be used. Use + the dynamic log levels instead. - Applications that use yaz, should not use the LOG_LOG for ordinary + Applications that use &yaz;, should not use the LOG_LOG for ordinary messages, but should make use of the dynamic loglevel system. This consists of two parts, defining the loglevel and checking it. @@ -1849,7 +1858,7 @@ typedef struct oident yaz_log_mask_str to define which log levels are to be logged. This string should be a comma-separated list of log level names, and can contain both hard-coded names and dynamic ones. The log level - calculation starts with LOG_DEFAULT_LEVEL and adds a bit + calculation starts with YLOG_DEFAULT_LEVEL and adds a bit for each word it meets, unless the word starts with a '-', in which case it clears the bit. If the string 'none' is found, all bits are cleared. Typically this string comes from the command-line, @@ -1871,6 +1880,17 @@ typedef struct oident + Yaz uses the following dynamic log levels: + server, session, request, requestdetail for the server + functionality. + zoom for the zoom client api. + ztest for the simple test server. + malloc, nmem, odr, eventl for internal debugging of yaz itself. + Of course, any program using yaz is welcome to define as many new ones, as + it needs. + + + By default the log is written to stderr, but this can be changed by a call to yaz_log_init_file or yaz_log_init. If the log is directed to a file, the @@ -1881,9 +1901,18 @@ typedef struct oident rotation feature. + + 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 + + The log entries start with a time stamp. This can be omitted by setting the - LOG_NOTIME bit in the loglevel. This way automatic tests + YLOG_NOTIME bit in the loglevel. This way automatic tests can be hoped to produce identical log files, that are easy to diff. The format of the time stamp can be set with yaz_log_time_format, which takes a format string just @@ -1891,15 +1920,16 @@ typedef struct oident - 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 yaz_log_init_level and the loglevel - passed to yaz_log_init_level. Finally comes all format + passed to yaz_log_init_level. Finally comes the format string and additional values passed to yaz_log - The log level LOG_LOGLVL, enabled by the string + The log level YLOG_LOGLVL, enabled by the string loglevel, will log all the log-level affecting operations. This can come in handy if you need to know what other log levels would be useful. Grep the logfile for [loglevel]. @@ -1912,7 +1942,10 @@ typedef struct oident - 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 + LOG_something to YLOG_something, + to avoid collision with syslog.h. @@ -1939,6 +1972,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);