dependencies/yaz_3.0.14/doc/tools.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 9. Supporting Tools</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="index.html" title="YAZ User's Guide and Reference"><link rel="prev" href="soap.srw.html" title="4. SRU"><link rel="next" href="tools.oid.html" title="2. Object Identifiers"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 9. Supporting Tools</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="soap.srw.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="tools.oid.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="tools"></a>Chapter 9. Supporting Tools</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="tools.html#tools.query">1. Query Syntax Parsers</a></span></dt><dd><dl><dt><span class="sect2"><a href="tools.html#PQF">1.1. Prefix Query Format</a></span></dt><dd><dl><dt><span class="sect3"><a href="tools.html#PQF-prox">1.1.1. Using Proximity Operators with PQF</a></span></dt><dt><span class="sect3"><a href="tools.html#pqf-examples">1.1.2. PQF queries</a></span></dt></dl></dd><dt><span class="sect2"><a href="tools.html#CCL">1.2. CCL</a></span></dt><dd><dl><dt><span class="sect3"><a href="tools.html#ccl.syntax">1.2.1. CCL Syntax</a></span></dt><dt><span class="sect3"><a href="tools.html#ccl.qualifiers">1.2.2. CCL Qualifiers</a></span></dt><dt><span class="sect3"><a href="tools.html#ccl.api">1.2.3. CCL API</a></span></dt></dl></dd><dt><span class="sect2"><a href="tools.html#cql">1.3. CQL</a></span></dt><dd><dl><dt><span class="sect3"><a href="tools.html#cql.parsing">1.3.1. CQL parsing</a></span></dt><dt><span class="sect3"><a href="tools.html#cql.tree">1.3.2. CQL tree</a></span></dt><dt><span class="sect3"><a href="tools.html#cql.to.pqf">1.3.3. CQL to PQF conversion</a></span></dt><dt><span class="sect3"><a href="tools.html#cql.to.rpn">1.3.4. Specification of CQL to RPN mappings</a></span></dt><dt><span class="sect3"><a href="tools.html#cql.xcql">1.3.5. CQL to XCQL conversion</a></span></dt></dl></dd></dl></dd><dt><span class="sect1"><a href="tools.oid.html">2. Object Identifiers</a></span></dt><dd><dl><dt><span class="sect2"><a href="tools.oid.html#tools.oid.database">2.1. OID database</a></span></dt><dt><span class="sect2"><a href="tools.oid.html#tools.oid.std">2.2. Standard OIDs</a></span></dt><dt><span class="sect2"><a href="tools.oid.html#tools.oid.oident">2.3. OID oident</a></span></dt></dl></dd><dt><span class="sect1"><a href="tools.nmem.html">3. Nibble Memory</a></span></dt><dt><span class="sect1"><a href="tools.log.html">4. Log</a></span></dt><dt><span class="sect1"><a href="marc.html">5. MARC</a></span></dt><dt><span class="sect1"><a href="tools.retrieval.html">6. Retrieval Facility</a></span></dt><dd><dl><dt><span class="sect2"><a href="tools.retrieval.html#tools.retrieval.format">6.1. Retrieval XML format</a></span></dt><dt><span class="sect2"><a href="tools.retrieval.html#tools.retrieval.examples">6.2. Retrieval Facility Examples</a></span></dt><dt><span class="sect2"><a href="tools.retrieval.html#tools.retrieval.api">6.3. API</a></span></dt></dl></dd></dl></div><p>
   2    In support of the service API - primarily the ASN module, which
   3    provides the pro-grammatic interface to the Z39.50 APDUs, YAZ contains
   4    a collection of tools that support the development of applications.
   5   </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tools.query"></a>1. Query Syntax Parsers</h2></div></div></div><p>
   6     Since the type-1 (RPN) query structure has no direct, useful string
   7     representation, every origin application needs to provide some form of
   8     mapping from a local query notation or representation to a
   9     <span class="token">Z_RPNQuery</span> structure. Some programmers will prefer to
  10     construct the query manually, perhaps using
  11     <code class="function">odr_malloc()</code> to simplify memory management.
  12     The YAZ distribution includes three separate, query-generating tools
  13     that may be of use to you.
  14    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="PQF"></a>1.1. Prefix Query Format</h3></div></div></div><p>
  15      Since RPN or reverse polish notation is really just a fancy way of
  16      describing a suffix notation format (operator follows operands), it
  17      would seem that the confusion is total when we now introduce a prefix
  18      notation for RPN. The reason is one of simple laziness - it's somewhat
  19      simpler to interpret a prefix format, and this utility was designed
  20      for maximum simplicity, to provide a baseline representation for use
  21      in simple test applications and scripting environments (like Tcl). The
  22      demonstration client included with YAZ uses the PQF.
  23     </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
  24       The PQF have been adopted by other parties developing Z39.50
  25       software. It is often referred to as Prefix Query Notation
  26       - PQN.
  27      </p></div><p>
  28      The PQF is defined by the pquery module in the YAZ library.
  29      There are two sets of function that have similar behavior. First
  30      set operates on a PQF parser handle, second set doesn't. First set
  31      set of functions are more flexible than the second set. Second set
  32      is obsolete and is only provided to ensure backwards compatibility.
  33     </p><p>
  34      First set of functions all operate on a PQF parser handle:
  35     </p><pre class="synopsis">
  36      #include &lt;yaz/pquery.h&gt;
  37
  38      YAZ_PQF_Parser yaz_pqf_create (void);
  39
  40      void yaz_pqf_destroy (YAZ_PQF_Parser p);
  41
  42      Z_RPNQuery *yaz_pqf_parse (YAZ_PQF_Parser p, ODR o, const char *qbuf);
  43
  44      Z_AttributesPlusTerm *yaz_pqf_scan (YAZ_PQF_Parser p, ODR o,
  45                           Odr_oid **attributeSetId, const char *qbuf);
  46
  47
  48      int yaz_pqf_error (YAZ_PQF_Parser p, const char **msg, size_t *off);
  49     </pre><p>
  50      A PQF parser is created and destructed by functions
  51      <code class="function">yaz_pqf_create</code> and
  52      <code class="function">yaz_pqf_destroy</code> respectively.
  53      Function <code class="function">yaz_pqf_parse</code> parses query given
  54      by string <code class="literal">qbuf</code>. If parsing was successful,
  55      a Z39.50 RPN Query is returned which is created using ODR stream
  56      <code class="literal">o</code>. If parsing failed, a NULL pointer is
  57      returned.
  58      Function <code class="function">yaz_pqf_scan</code> takes a scan query in
  59      <code class="literal">qbuf</code>. If parsing was successful, the function
  60      returns attributes plus term pointer and modifies
  61      <code class="literal">attributeSetId</code> to hold attribute set for the
  62      scan request - both allocated using ODR stream <code class="literal">o</code>.
  63      If parsing failed, yaz_pqf_scan returns a NULL pointer.
  64      Error information for bad queries can be obtained by a call to
  65      <code class="function">yaz_pqf_error</code> which returns an error code and
  66      modifies <code class="literal">*msg</code> to point to an error description,
  67      and modifies <code class="literal">*off</code> to the offset within last
  68      query were parsing failed.
  69     </p><p>
  70      The second set of functions are declared as follows:
  71     </p><pre class="synopsis">
  72      #include &lt;yaz/pquery.h&gt;
  73
  74      Z_RPNQuery *p_query_rpn (ODR o, oid_proto proto, const char *qbuf);
  75
  76      Z_AttributesPlusTerm *p_query_scan (ODR o, oid_proto proto,
  77                              Odr_oid **attributeSetP, const char *qbuf);
  78
  79      int p_query_attset (const char *arg);
  80     </pre><p>
  81      The function <code class="function">p_query_rpn()</code> takes as arguments an
  82       <acronym class="acronym">ODR</acronym> stream (see section <a class="link" href="odr.html" title="Chapter 10. The ODR Module">The ODR Module</a>)
  83      to provide a memory source (the structure created is released on
  84      the next call to <code class="function">odr_reset()</code> on the stream), a
  85      protocol identifier (one of the constants <span class="token">PROTO_Z3950</span> and
  86      <span class="token">PROTO_SR</span>), an attribute set reference, and
  87      finally a null-terminated string holding the query string.
  88     </p><p>
  89      If the parse went well, <code class="function">p_query_rpn()</code> returns a
  90      pointer to a <code class="literal">Z_RPNQuery</code> structure which can be
  91      placed directly into a <code class="literal">Z_SearchRequest</code>.
  92      If parsing failed, due to syntax error, a NULL pointer is returned.
  93     </p><p>
  94      The <code class="literal">p_query_attset</code> specifies which attribute set
  95      to use if the query doesn't specify one by the
  96      <code class="literal">@attrset</code> operator.
  97      The <code class="literal">p_query_attset</code> returns 0 if the argument is a
  98      valid attribute set specifier; otherwise the function returns -1.
  99     </p><p>
 100      The grammar of the PQF is as follows:
 101     </p><div class="literallayout"><p><br>
 102      query ::= top-set query-struct.<br>
 103 <br>
 104      top-set ::= [ '@attrset' string ]<br>
 105 <br>
 106      query-struct ::= attr-spec | simple | complex | '@term' term-type query<br>
 107 <br>
 108      attr-spec ::= '@attr' [ string ] string query-struct<br>
 109 <br>
 110      complex ::= operator query-struct query-struct.<br>
 111 <br>
 112      operator ::= '@and' | '@or' | '@not' | '@prox' proximity.<br>
 113 <br>
 114      simple ::= result-set | term.<br>
 115 <br>
 116      result-set ::= '@set' string.<br>
 117 <br>
 118      term ::= string.<br>
 119 <br>
 120      proximity ::= exclusion distance ordered relation which-code unit-code.<br>
 121 <br>
 122      exclusion ::= '1' | '0' | 'void'.<br>
 123 <br>
 124      distance ::= integer.<br>
 125 <br>
 126      ordered ::= '1' | '0'.<br>
 127 <br>
 128      relation ::= integer.<br>
 129 <br>
 130      which-code ::= 'known' | 'private' | integer.<br>
 131 <br>
 132      unit-code ::= integer.<br>
 133 <br>
 134      term-type ::= 'general' | 'numeric' | 'string' | 'oid' | 'datetime' | 'null'.<br>
 135     </p></div><p>
 136      You will note that the syntax above is a fairly faithful
 137      representation of RPN, except for the Attribute, which has been
 138      moved a step away from the term, allowing you to associate one or more
 139      attributes with an entire query structure. The parser will
 140      automatically apply the given attributes to each term as required.
 141     </p><p>
 142      The @attr operator is followed by an attribute specification
 143      (<code class="literal">attr-spec</code> above). The specification consists
 144      of an optional attribute set, an attribute type-value pair and
 145      a sub-query. The attribute type-value pair is packed in one string:
 146      an attribute type, an equals sign, and an attribute value, like this:
 147      <code class="literal">@attr 1=1003</code>.
 148      The type is always an integer but the value may be either an
 149      integer or a string (if it doesn't start with a digit character).
 150      A string attribute-value is encoded as a Type-1 ``complex''
 151      attribute with the list of values containing the single string
 152      specified, and including no semantic indicators.
 153     </p><p>
 154      Version 3 of the Z39.50 specification defines various encoding of terms.
 155      Use <code class="literal">@term </code> <em class="replaceable"><code>type</code></em>
 156      <em class="replaceable"><code>string</code></em>,
 157      where type is one of: <code class="literal">general</code>,
 158      <code class="literal">numeric</code> or <code class="literal">string</code>
 159      (for InternationalString).
 160      If no term type has been given, the <code class="literal">general</code> form
 161      is used.  This is the only encoding allowed in both versions 2 and 3
 162      of the Z39.50 standard.
 163     </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="PQF-prox"></a>1.1.1. Using Proximity Operators with PQF</h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 164           This is an advanced topic, describing how to construct
 165           queries that make very specific requirements on the
 166           relative location of their operands.
 167           You may wish to skip this section and go straight to
 168           <a class="link" href="tools.html#pqf-examples" title="1.1.2. PQF queries">the example PQF queries</a>.
 169         </p><p>
 170           </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>
 171               Most Z39.50 servers do not support proximity searching, or
 172               support only a small subset of the full functionality that
 173               can be expressed using the PQF proximity operator.  Be
 174               aware that the ability to <span class="emphasis"><em>express</em></span> a
 175               query in PQF is no guarantee that any given server will
 176               be able to <span class="emphasis"><em>execute</em></span> it.
 177             </p></div><p>
 178         </p></div><p>
 179         The proximity operator <code class="literal">@prox</code> is a special
 180         and more restrictive version of the conjunction operator
 181         <code class="literal">@and</code>.  Its semantics are described in
 182         section 3.7.2 (Proximity) of Z39.50 the standard itself, which
 183         can be read on-line at
 184         <a class="ulink" href="http://www.loc.gov/z3950/agency/markup/09.html#3.7.2" target="_top">http://www.loc.gov/z3950/agency/markup/09.html#3.7.2</a>
 185       </p><p>
 186         In PQF, the proximity operation is represented by a sequence
 187         of the form
 188         </p><pre class="screen">
 189 @prox <em class="replaceable"><code>exclusion</code></em> <em class="replaceable"><code>distance</code></em> <em class="replaceable"><code>ordered</code></em> <em class="replaceable"><code>relation</code></em> <em class="replaceable"><code>which-code</code></em> <em class="replaceable"><code>unit-code</code></em>
 190         </pre><p>
 191         in which the meanings of the parameters are as described in in
 192         the standard, and they can take the following values:
 193         </p><div class="itemizedlist"><ul type="disc"><li><p><b>exclusion. </b>
 194             0 = false (i.e. the proximity condition specified by the
 195             remaining parameters must be satisfied) or
 196             1 = true (the proximity condition specified by the
 197             remaining parameters must <span class="emphasis"><em>not</em></span> be
 198             satisifed).
 199           </p></li><li><p><b>distance. </b>
 200             An integer specifying the difference between the locations
 201             of the operands: e.g. two adjacent words would have
 202             distance=1 since their locations differ by one unit.
 203           </p></li><li><p><b>ordered. </b>
 204             1 = ordered (the operands must occur in the order the
 205             query specifies them) or
 206             0 = unordered (they may appear in either order).
 207           </p></li><li><p><b>relation. </b>
 208             Recognised values are
 209             1 (lessThan),
 210             2 (lessThanOrEqual),
 211             3 (equal),
 212             4 (greaterThanOrEqual),
 213             5 (greaterThan) and
 214             6 (notEqual).
 215           </p></li><li><p><b>which-code. </b>
 216             <code class="literal">known</code>
 217             or
 218             <code class="literal">k</code>
 219             (the unit-code parameter is taken from the well-known list
 220             of alternatives described in below) or
 221             <code class="literal">private</code>
 222             or
 223             <code class="literal">p</code>
 224             (the unit-code paramater has semantics specific to an
 225             out-of-band agreement such as a profile).
 226           </p></li><li><p><b>unit-code. </b>
 227             If the which-code parameter is <code class="literal">known</code>
 228             then the recognised values are
 229             1 (character),
 230             2 (word),
 231             3 (sentence),
 232             4 (paragraph),
 233             5 (section),
 234             6 (chapter),
 235             7 (document),
 236             8 (element),
 237             9 (subelement),
 238             10 (elementType) and
 239             11 (byte).
 240             If which-code is <code class="literal">private</code> then the
 241             acceptable values are determined by the profile.
 242           </p></li></ul></div><p>
 243         (The numeric values of the relation and well-known unit-code
 244         parameters are taken straight from
 245         <a class="ulink" href="http://www.loc.gov/z3950/agency/asn1.html#ProximityOperator" target="_top">the ASN.1</a> of the proximity structure in the standard.)
 246       </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="pqf-examples"></a>1.1.2. PQF queries</h4></div></div></div><div class="example"><a name="example.pqf.simple.terms"></a><p class="title"><b>Example 9.1. PQF queries using simple terms</b></p><div class="example-contents"><p>
 247        </p><pre class="screen">
 248         dylan
 249
 250         "bob dylan"
 251        </pre><p>
 252       </p></div></div><br class="example-break"><div class="example"><a name="pqf.example.pqf.boolean.operators"></a><p class="title"><b>Example 9.2. PQF boolean operators</b></p><div class="example-contents"><p>
 253        </p><pre class="screen">
 254         @or "dylan" "zimmerman"
 255
 256         @and @or dylan zimmerman when
 257
 258         @and when @or dylan zimmerman
 259        </pre><p>
 260       </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.result.sets"></a><p class="title"><b>Example 9.3. PQF references to result sets</b></p><div class="example-contents"><p>
 261        </p><pre class="screen">
 262         @set Result-1
 263
 264         @and @set seta @set setb
 265        </pre><p>
 266       </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.attributes"></a><p class="title"><b>Example 9.4. Attributes for terms</b></p><div class="example-contents"><p>
 267        </p><pre class="screen">
 268         @attr 1=4 computer
 269
 270         @attr 1=4 @attr 4=1 "self portrait"
 271
 272         @attrset exp1 @attr 1=1 CategoryList
 273
 274         @attr gils 1=2008 Copenhagen
 275
 276         @attr 1=/book/title computer
 277        </pre><p>
 278       </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.proximity"></a><p class="title"><b>Example 9.5. PQF Proximity queries</b></p><div class="example-contents"><p>
 279        </p><pre class="screen">
 280         @prox 0 3 1 2 k 2 dylan zimmerman
 281        </pre><p>
 282        </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 283          Here the parameters 0, 3, 1, 2, k and 2 represent exclusion,
 284          distance, ordered, relation, which-code and unit-code, in that
 285          order.  So:
 286          </p><div class="itemizedlist"><ul type="disc"><li><p>
 287             exclusion = 0: the proximity condition must hold
 288            </p></li><li><p>
 289             distance = 3: the terms must be three units apart
 290            </p></li><li><p>
 291             ordered = 1: they must occur in the order they are specified
 292            </p></li><li><p>
 293             relation = 2: lessThanOrEqual (to the distance of 3 units)
 294            </p></li><li><p>
 295             which-code is ``known'', so the standard unit-codes are used
 296            </p></li><li><p>
 297             unit-code = 2: word.
 298            </p></li></ul></div><p>
 299          So the whole proximity query means that the words
 300          <code class="literal">dylan</code> and <code class="literal">zimmerman</code> must
 301          both occur in the record, in that order, differing in position
 302          by three or fewer words (i.e. with two or fewer words between
 303          them.)  The query would find ``Bob Dylan, aka. Robert
 304          Zimmerman'', but not ``Bob Dylan, born as Robert Zimmerman''
 305          since the distance in this case is four.
 306         </p></div><p>
 307       </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.search.term.type"></a><p class="title"><b>Example 9.6. PQF specification of search term type</b></p><div class="example-contents"><p>
 308        </p><pre class="screen">
 309         @term string "a UTF-8 string, maybe?"
 310        </pre><p>
 311       </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.mixed.queries"></a><p class="title"><b>Example 9.7. PQF mixed queries</b></p><div class="example-contents"><p>
 312        </p><pre class="screen">
 313         @or @and bob dylan @set Result-1
 314
 315         @attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming"
 316
 317         @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109
 318       </pre><p>
 319        </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 320          The last of these examples is a spatial search: in
 321          <a class="ulink" href="http://www.gils.net/prof_v2.html#sec_7_4" target="_top">the GILS attribute set</a>,
 322          access point
 323          2038 indicates West Bounding Coordinate and
 324          2030 indicates East Bounding Coordinate,
 325          so the query is for areas extending from -114 degrees
 326          to no more than -109 degrees.
 327         </p></div><p>
 328       </p></div></div><br class="example-break"></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="CCL"></a>1.2. CCL</h3></div></div></div><p>
 329      Not all users enjoy typing in prefix query structures and numerical
 330      attribute values, even in a minimalistic test client. In the library
 331      world, the more intuitive Common Command Language - CCL (ISO 8777)
 332      has enjoyed some popularity - especially before the widespread
 333      availability of graphical interfaces. It is still useful in
 334      applications where you for some reason or other need to provide a
 335      symbolic language for expressing boolean query structures.
 336     </p><p>
 337      The EUROPAGATE research project working under the Libraries programme
 338      of the European Commission's DG XIII has, amongst other useful tools,
 339      implemented a general-purpose CCL parser which produces an output
 340      structure that can be trivially converted to the internal RPN
 341      representation of YAZ (The <code class="literal">Z_RPNQuery</code> structure).
 342      Since the CCL utility - along with the rest of the software
 343      produced by EUROPAGATE - is made freely available on a liberal
 344      license, it is included as a supplement to YAZ.
 345     </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ccl.syntax"></a>1.2.1. CCL Syntax</h4></div></div></div><p>
 346       The CCL parser obeys the following grammar for the FIND argument.
 347       The syntax is annotated by in the lines prefixed by
 348       <code class="literal">--</code>.
 349      </p><pre class="screen">
 350       CCL-Find ::= CCL-Find Op Elements
 351                 | Elements.
 352
 353       Op ::= "and" | "or" | "not"
 354       -- The above means that Elements are separated by boolean operators.
 355
 356       Elements ::= '(' CCL-Find ')'
 357                 | Set
 358                 | Terms
 359                 | Qualifiers Relation Terms
 360                 | Qualifiers Relation '(' CCL-Find ')'
 361                 | Qualifiers '=' string '-' string
 362       -- Elements is either a recursive definition, a result set reference, a
 363       -- list of terms, qualifiers followed by terms, qualifiers followed
 364       -- by a recursive definition or qualifiers in a range (lower - upper).
 365
 366       Set ::= 'set' = string
 367       -- Reference to a result set
 368
 369       Terms ::= Terms Prox Term
 370              | Term
 371       -- Proximity of terms.
 372
 373       Term ::= Term string
 374             | string
 375       -- This basically means that a term may include a blank
 376
 377       Qualifiers ::= Qualifiers ',' string
 378                   | string
 379       -- Qualifiers is a list of strings separated by comma
 380
 381       Relation ::= '=' | '&gt;=' | '&lt;=' | '&lt;&gt;' | '&gt;' | '&lt;'
 382       -- Relational operators. This really doesn't follow the ISO8777
 383       -- standard.
 384
 385       Prox ::= '%' | '!'
 386       -- Proximity operator
 387
 388      </pre><div class="example"><a name="example.ccl.queries"></a><p class="title"><b>Example 9.8. CCL queries</b></p><div class="example-contents"><p>
 389        The following queries are all valid:
 390       </p><pre class="screen">
 391        dylan
 392
 393        "bob dylan"
 394
 395        dylan or zimmerman
 396
 397        set=1
 398
 399        (dylan and bob) or set=1
 400
 401       </pre><p>
 402        Assuming that the qualifiers <code class="literal">ti</code>,
 403        <code class="literal">au</code>
 404        and <code class="literal">date</code> are defined we may use:
 405       </p><pre class="screen">
 406        ti=self portrait
 407
 408        au=(bob dylan and slow train coming)
 409
 410        date&gt;1980 and (ti=((self portrait)))
 411
 412       </pre></div></div><br class="example-break"></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ccl.qualifiers"></a>1.2.2. CCL Qualifiers</h4></div></div></div><p>
 413       Qualifiers are used to direct the search to a particular searchable
 414       index, such as title (ti) and author indexes (au). The CCL standard
 415       itself doesn't specify a particular set of qualifiers, but it does
 416       suggest a few short-hand notations. You can customize the CCL parser
 417       to support a particular set of qualifiers to reflect the current target
 418       profile. Traditionally, a qualifier would map to a particular
 419       use-attribute within the BIB-1 attribute set. It is also
 420       possible to set other attributes, such as the structure
 421       attribute.
 422      </p><p>
 423       A  CCL profile is a set of predefined CCL qualifiers that may be
 424       read from a file or set in the CCL API.
 425       The YAZ client reads its CCL qualifiers from a file named
 426       <code class="filename">default.bib</code>. There are four types of
 427       lines in a CCL profile: qualifier specification,
 428       qualifier alias, comments and directives.
 429      </p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ccl.qualifier.specification"></a>1.2.2.1. Qualifier specification</h5></div></div></div><p>
 430        A qualifier specification is of the form:
 431       </p><p>
 432        <em class="replaceable"><code>qualifier-name</code></em>
 433        [<em class="replaceable"><code>attributeset</code></em><code class="literal">,</code>]<em class="replaceable"><code>type</code></em><code class="literal">=</code><em class="replaceable"><code>val</code></em>
 434        [<em class="replaceable"><code>attributeset</code></em><code class="literal">,</code>]<em class="replaceable"><code>type</code></em><code class="literal">=</code><em class="replaceable"><code>val</code></em> ...
 435       </p><p>
 436        where <em class="replaceable"><code>qualifier-name</code></em> is the name of the
 437        qualifier to be used (eg. <code class="literal">ti</code>),
 438        <em class="replaceable"><code>type</code></em> is attribute type in the attribute
 439        set (Bib-1 is used if no attribute set is given) and
 440        <em class="replaceable"><code>val</code></em> is attribute value.
 441        The <em class="replaceable"><code>type</code></em> can be specified as an
 442        integer or as it be specified either as a single-letter:
 443        <code class="literal">u</code> for use,
 444        <code class="literal">r</code> for relation,<code class="literal">p</code> for position,
 445        <code class="literal">s</code> for structure,<code class="literal">t</code> for truncation
 446        or <code class="literal">c</code> for completeness.
 447        The attributes for the special qualifier name <code class="literal">term</code>
 448        are used when no CCL qualifier is given in a query.
 449        </p><div class="table"><a name="ccl.common.bib1.attributes"></a><p class="title"><b>Table 9.1. Common Bib-1 attributes</b></p><div class="table-contents"><table summary="Common Bib-1 attributes" border="1"><colgroup><col><col></colgroup><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">u=</code><em class="replaceable"><code>value</code></em></td><td>
 450             Use attribute (1). Common use attributes are
 451             1 Personal-name, 4 Title, 7 ISBN, 8 ISSN, 30 Date,
 452             62 Subject, 1003 Author), 1016 Any. Specify value
 453             as an integer.
 454            </td></tr><tr><td><code class="literal">r=</code><em class="replaceable"><code>value</code></em></td><td>
 455             Relation attribute (2). Common values are
 456             1 &lt;, 2 &lt;=, 3 =, 4 &gt;=, 5 &gt;, 6 &lt;&gt;,
 457             100 phonetic, 101 stem, 102 relevance, 103 always matches.
 458            </td></tr><tr><td><code class="literal">p=</code><em class="replaceable"><code>value</code></em></td><td>
 459             Position attribute (3). Values: 1 first in field, 2
 460             first in any subfield, 3 any position in field.
 461            </td></tr><tr><td><code class="literal">s=</code><em class="replaceable"><code>value</code></em></td><td>
 462             Structure attribute (4). Values: 1 phrase, 2 word,
 463             3 key, 4 year, 5 date, 6 word list, 100 date (un),
 464             101 name (norm), 102 name (un), 103 structure, 104 urx,
 465             105 free-form-text, 106 document-text, 107 local-number,
 466             108 string, 109 numeric string.
 467            </td></tr><tr><td><code class="literal">t=</code><em class="replaceable"><code>value</code></em></td><td>
 468             Truncation attribute (5). Values: 1 right, 2 left,
 469             3 left&amp; right, 100 none, 101 process #, 102 regular-1,
 470             103 regular-2, 104 CCL.
 471            </td></tr><tr><td><code class="literal">c=</code><em class="replaceable"><code>value</code></em></td><td>
 472             Completeness attribute (6). Values: 1 incomplete subfield,
 473             2 complete subfield, 3 complete field.
 474            </td></tr></tbody></table></div></div><p><br class="table-break">
 475       </p><p>
 476        Refer to the complete
 477        <a class="ulink" href="http://www.loc.gov/z3950/agency/defns/bib1.html" target="_top">list of Bib-1 attributes</a>
 478       </p><p>
 479        It is also possible to specify non-numeric attribute values,
 480        which are used in combination with certain types.
 481        The special combinations are:
 482
 483        </p><div class="table"><a name="ccl.special.attribute.combos"></a><p class="title"><b>Table 9.2. Special attribute combos</b></p><div class="table-contents"><table summary="Special attribute combos" border="1"><colgroup><col><col></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">s=pw</code></td><td>
 484             The structure is set to either word or phrase depending
 485             on the number of tokens in a term (phrase-word).
 486            </td></tr><tr><td><code class="literal">s=al</code></td><td>
 487             Each token in the term is ANDed. (and-list).
 488             This does not set the structure at all.
 489            </td></tr><tr><td><code class="literal">s=ol</code></td><td>
 490             Each token in the term is ORed. (or-list).
 491             This does not set the structure at all.
 492            </td></tr><tr><td><code class="literal">r=o</code></td><td>
 493             Allows ranges and the operators greather-than, less-than, ...
 494             equals.
 495             This sets Bib-1 relation attribute accordingly (relation
 496             ordered). A query construct is only treated as a range if
 497             dash is used and that is surrounded by white-space. So
 498             <code class="literal">-1980</code> is treated as term
 499             <code class="literal">"-1980"</code> not <code class="literal">&lt;= 1980</code>.
 500             If <code class="literal">- 1980</code> is used, however, that is
 501             treated as a range.
 502            </td></tr><tr><td><code class="literal">r=r</code></td><td>
 503             Similar to <code class="literal">r=o</code> but assumes that terms
 504             are non-negative (not prefixed with <code class="literal">-</code>).
 505             Thus, a dash will always be treated as a range.
 506             The construct <code class="literal">1980-1990</code> is
 507             treated as a range with <code class="literal">r=r</code> but as a
 508             single term <code class="literal">"1980-1990"</code> with
 509             <code class="literal">r=o</code>. The special attribute
 510             <code class="literal">r=r</code> is available in YAZ 2.0.24 or later.
 511            </td></tr><tr><td><code class="literal">t=l</code></td><td>
 512             Allows term to be left-truncated.
 513             If term is of the form <code class="literal">?x</code>, the resulting
 514             Type-1 term is <code class="literal">x</code> and truncation is left.
 515            </td></tr><tr><td><code class="literal">t=r</code></td><td>
 516             Allows term to be right-truncated.
 517             If term is of the form <code class="literal">x?</code>, the resulting
 518             Type-1 term is <code class="literal">x</code> and truncation is right.
 519            </td></tr><tr><td><code class="literal">t=n</code></td><td>
 520             If term is does not include <code class="literal">?</code>, the
 521             truncation attribute is set to none (100).
 522            </td></tr><tr><td><code class="literal">t=b</code></td><td>
 523             Allows term to be both left&amp;right truncated.
 524             If term is of the form <code class="literal">?x?</code>, the
 525             resulting term is <code class="literal">x</code> and trunctation is
 526             set to both left&amp;right.
 527            </td></tr></tbody></table></div></div><p><br class="table-break">
 528       </p><div class="example"><a name="example.ccl.profile"></a><p class="title"><b>Example 9.9. CCL profile</b></p><div class="example-contents"><p>
 529         Consider the following definition:
 530        </p><pre class="screen">
 531         ti       u=4 s=1
 532         au       u=1 s=1
 533         term     s=105
 534         ranked   r=102
 535         date     u=30 r=o
 536       </pre><p>
 537         <code class="literal">ti</code> and <code class="literal">au</code> both set
 538         structure attribute to phrase (s=1).
 539         <code class="literal">ti</code>
 540         sets the use-attribute to 4. <code class="literal">au</code> sets the
 541         use-attribute to 1.
 542         When no qualifiers are used in the query the structure-attribute is
 543         set to free-form-text (105) (rule for <code class="literal">term</code>).
 544         The <code class="literal">date</code> sets the relation attribute to
 545         the relation used in the CCL query and sets the use attribute
 546         to 30 (Bib-1 Date).
 547        </p><p>
 548         You can combine attributes. To Search for "ranked title" you
 549         can do
 550         </p><pre class="screen">
 551          ti,ranked=knuth computer
 552         </pre><p>
 553         which will set relation=ranked, use=title, structure=phrase.
 554        </p><p>
 555         Query
 556         </p><pre class="screen">
 557          date &gt; 1980
 558         </pre><p>
 559         is a valid query. But
 560         </p><pre class="screen">
 561          ti &gt; 1980
 562         </pre><p>
 563         is invalid.
 564        </p></div></div><br class="example-break"></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ccl.qualifier.alias"></a>1.2.2.2. Qualifier alias</h5></div></div></div><p>
 565        A qualifier alias is of the form:
 566       </p><p>
 567        <em class="replaceable"><code>q</code></em>
 568        <em class="replaceable"><code>q1</code></em> <em class="replaceable"><code>q2</code></em> ..
 569       </p><p>
 570        which declares <em class="replaceable"><code>q</code></em> to
 571        be an alias for <em class="replaceable"><code>q1</code></em>,
 572        <em class="replaceable"><code>q2</code></em>... such that the CCL
 573        query <em class="replaceable"><code>q=x</code></em> is equivalent to
 574        <em class="replaceable"><code>q1=x or q2=x or ...</code></em>.
 575       </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ccl.comments"></a>1.2.2.3. Comments</h5></div></div></div><p>
 576        Lines with white space or lines that begin with
 577        character <code class="literal">#</code> are treated as comments.
 578       </p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="ccl.directives"></a>1.2.2.4. Directives</h5></div></div></div><p>
 579        Directive specifications takes the form
 580       </p><p><code class="literal">@</code><em class="replaceable"><code>directive</code></em> <em class="replaceable"><code>value</code></em>
 581       </p><div class="table"><a name="ccl.directives.table"></a><p class="title"><b>Table 9.3. CCL directives</b></p><div class="table-contents"><table summary="CCL directives" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Name</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>truncation</td><td>Truncation character</td><td><code class="literal">?</code></td></tr><tr><td>field</td><td>Specifies how multiple fields are to be
 582            combined. There are two modes: <code class="literal">or</code>:
 583            multiple qualifier fields are ORed,
 584            <code class="literal">merge</code>: attributes for the qualifier
 585            fields are merged and assigned to one term.
 586            </td><td><code class="literal">merge</code></td></tr><tr><td>case</td><td>Specificies if CCL operatores and qualifiers should be
 587            compared with case sensitivity or not. Specify 0 for
 588            case sensitive; 1 for case insensitive.</td><td><code class="literal">0</code></td></tr><tr><td>and</td><td>Specifies token for CCL operator AND.</td><td><code class="literal">and</code></td></tr><tr><td>or</td><td>Specifies token for CCL operator OR.</td><td><code class="literal">or</code></td></tr><tr><td>not</td><td>Specifies token for CCL operator NOT.</td><td><code class="literal">not</code></td></tr><tr><td>set</td><td>Specifies token for CCL operator SET.</td><td><code class="literal">set</code></td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="ccl.api"></a>1.2.3. CCL API</h4></div></div></div><p>
 589       All public definitions can be found in the header file
 590       <code class="filename">ccl.h</code>. A profile identifier is of type
 591       <code class="literal">CCL_bibset</code>. A profile must be created with the call
 592       to the function <code class="function">ccl_qual_mk</code> which returns a profile
 593       handle of type <code class="literal">CCL_bibset</code>.
 594      </p><p>
 595       To read a file containing qualifier definitions the function
 596       <code class="function">ccl_qual_file</code> may be convenient. This function
 597       takes an already opened <code class="literal">FILE</code> handle pointer as
 598       argument along with a <code class="literal">CCL_bibset</code> handle.
 599      </p><p>
 600       To parse a simple string with a FIND query use the function
 601      </p><pre class="screen">
 602 struct ccl_rpn_node *ccl_find_str (CCL_bibset bibset, const char *str,
 603                                    int *error, int *pos);
 604      </pre><p>
 605       which takes the CCL profile (<code class="literal">bibset</code>) and query
 606       (<code class="literal">str</code>) as input. Upon successful completion the RPN
 607       tree is returned. If an error occur, such as a syntax error, the integer
 608       pointed to by <code class="literal">error</code> holds the error code and
 609       <code class="literal">pos</code> holds the offset inside query string in which
 610       the parsing failed.
 611      </p><p>
 612       An English representation of the error may be obtained by calling
 613       the <code class="literal">ccl_err_msg</code> function. The error codes are
 614       listed in <code class="filename">ccl.h</code>.
 615      </p><p>
 616       To convert the CCL RPN tree (type
 617       <code class="literal">struct ccl_rpn_node *</code>)
 618       to the Z_RPNQuery of YAZ the function <code class="function">ccl_rpn_query</code>
 619       must be used. This function which is part of YAZ is implemented in
 620       <code class="filename">yaz-ccl.c</code>.
 621       After calling this function the CCL RPN tree is probably no longer
 622       needed. The <code class="literal">ccl_rpn_delete</code> destroys the CCL RPN tree.
 623      </p><p>
 624       A CCL profile may be destroyed by calling the
 625       <code class="function">ccl_qual_rm</code> function.
 626      </p><p>
 627       The token names for the CCL operators may be changed by setting the
 628       globals (all type <code class="literal">char *</code>)
 629       <code class="literal">ccl_token_and</code>, <code class="literal">ccl_token_or</code>,
 630       <code class="literal">ccl_token_not</code> and <code class="literal">ccl_token_set</code>.
 631       An operator may have aliases, i.e. there may be more than one name for
 632       the operator. To do this, separate each alias with a space character.
 633      </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="cql"></a>1.3. CQL</h3></div></div></div><p>
 634      <a class="ulink" href="http://www.loc.gov/standards/sru/cql/" target="_top">CQL</a>
 635       - Common Query Language - was defined for the
 636      <a class="ulink" href="http://www.loc.gov/standards/sru/" target="_top">SRU</a> protocol.
 637      In many ways CQL has a similar syntax to CCL.
 638      The objective of CQL is different. Where CCL aims to be
 639      an end-user language, CQL is <span class="emphasis"><em>the</em></span> protocol
 640      query language for SRU.
 641     </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>
 642       If you are new to CQL, read the
 643       <a class="ulink" href="http://zing.z3950.org/cql/intro.html" target="_top">Gentle Introduction</a>.
 644      </p></div><p>
 645      The CQL parser in YAZ provides the following:
 646      </p><div class="itemizedlist"><ul type="disc"><li><p>
 647         It parses and validates a CQL query.
 648        </p></li><li><p>
 649         It generates a C structure that allows you to convert
 650         a CQL query to some other query language, such as SQL.
 651        </p></li><li><p>
 652         The parser converts a valid CQL query to PQF, thus providing a
 653         way to use CQL for both SRU servers and Z39.50 targets at the
 654         same time.
 655        </p></li><li><p>
 656         The parser converts CQL to
 657         <a class="ulink" href="http://www.loc.gov/standards/sru/xml-files/srw-types.xsd" target="_top">XCQL</a>.
 658         XCQL is an XML representation of CQL.
 659         XCQL is part of the SRU specification. However, since SRU
 660         supports CQL only, we don't expect XCQL to be widely used.
 661         Furthermore, CQL has the advantage over XCQL that it is
 662         easy to read.
 663        </p></li></ul></div><p>
 664     </p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cql.parsing"></a>1.3.1. CQL parsing</h4></div></div></div><p>
 665       A CQL parser is represented by the <code class="literal">CQL_parser</code>
 666       handle. Its contents should be considered YAZ internal (private).
 667       </p><pre class="synopsis">
 668 #include &lt;yaz/cql.h&gt;
 669
 670 typedef struct cql_parser *CQL_parser;
 671
 672 CQL_parser cql_parser_create(void);
 673 void cql_parser_destroy(CQL_parser cp);
 674       </pre><p>
 675      A parser is created by <code class="function">cql_parser_create</code> and
 676      is destroyed by <code class="function">cql_parser_destroy</code>.
 677      </p><p>
 678       To parse a CQL query string, the following function
 679       is provided:
 680       </p><pre class="synopsis">
 681 int cql_parser_string(CQL_parser cp, const char *str);
 682       </pre><p>
 683       A CQL query is parsed by the <code class="function">cql_parser_string</code>
 684       which takes a query <em class="parameter"><code>str</code></em>.
 685       If the query was valid (no syntax errors), then zero is returned;
 686       otherwise -1 is returned to indicate a syntax error.
 687      </p><p>
 688       </p><pre class="synopsis">
 689 int cql_parser_stream(CQL_parser cp,
 690                       int (*getbyte)(void *client_data),
 691                       void (*ungetbyte)(int b, void *client_data),
 692                       void *client_data);
 693
 694 int cql_parser_stdio(CQL_parser cp, FILE *f);
 695       </pre><p>
 696       The functions <code class="function">cql_parser_stream</code> and
 697       <code class="function">cql_parser_stdio</code> parses a CQL query
 698       - just like <code class="function">cql_parser_string</code>.
 699       The only difference is that the CQL query can be
 700       fed to the parser in different ways.
 701       The <code class="function">cql_parser_stream</code> uses a generic
 702       byte stream as input. The <code class="function">cql_parser_stdio</code>
 703       uses a <code class="literal">FILE</code> handle which is opened for reading.
 704      </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cql.tree"></a>1.3.2. CQL tree</h4></div></div></div><p>
 705       The the query string is valid, the CQL parser
 706       generates a tree representing the structure of the
 707       CQL query.
 708      </p><p>
 709       </p><pre class="synopsis">
 710 struct cql_node *cql_parser_result(CQL_parser cp);
 711       </pre><p>
 712       <code class="function">cql_parser_result</code> returns the
 713       a pointer to the root node of the resulting tree.
 714      </p><p>
 715       Each node in a CQL tree is represented by a
 716       <code class="literal">struct cql_node</code>.
 717       It is defined as follows:
 718       </p><pre class="synopsis">
 719 #define CQL_NODE_ST 1
 720 #define CQL_NODE_BOOL 2
 721 struct cql_node {
 722     int which;
 723     union {
 724         struct {
 725             char *index;
 726             char *index_uri;
 727             char *term;
 728             char *relation;
 729             char *relation_uri;
 730             struct cql_node *modifiers;
 731         } st;
 732         struct {
 733             char *value;
 734             struct cql_node *left;
 735             struct cql_node *right;
 736             struct cql_node *modifiers;
 737         } boolean;
 738     } u;
 739 };
 740       </pre><p>
 741       There are two node types: search term (ST) and boolean (BOOL).
 742       A modifier is treated as a search term too.
 743      </p><p>
 744       The search term node has five members:
 745       </p><div class="itemizedlist"><ul type="disc"><li><p>
 746          <code class="literal">index</code>: index for search term.
 747          If an index is unspecified for a search term,
 748          <code class="literal">index</code> will be NULL.
 749         </p></li><li><p>
 750          <code class="literal">index_uri</code>: index URi for search term
 751          or NULL if none could be resolved for the index.
 752         </p></li><li><p>
 753          <code class="literal">term</code>: the search term itself.
 754         </p></li><li><p>
 755          <code class="literal">relation</code>: relation for search term.
 756         </p></li><li><p>
 757          <code class="literal">relation_uri</code>: relation URI for search term.
 758         </p></li><li><p>
 759          <code class="literal">modifiers</code>: relation modifiers for search
 760          term. The <code class="literal">modifiers</code> list itself of cql_nodes
 761          each of type <code class="literal">ST</code>.
 762         </p></li></ul></div><p>
 763      </p><p>
 764       The boolean node represents both <code class="literal">and</code>,
 765       <code class="literal">or</code>, not as well as
 766       proximity.
 767       </p><div class="itemizedlist"><ul type="disc"><li><p>
 768          <code class="literal">left</code> and <code class="literal">right</code>: left
 769          - and right operand respectively.
 770         </p></li><li><p>
 771          <code class="literal">modifiers</code>: proximity arguments.
 772         </p></li></ul></div><p>
 773      </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cql.to.pqf"></a>1.3.3. CQL to PQF conversion</h4></div></div></div><p>
 774       Conversion to PQF (and Z39.50 RPN) is tricky by the fact
 775       that the resulting RPN depends on the Z39.50 target
 776       capabilities (combinations of supported attributes).
 777       In addition, the CQL and SRU operates on index prefixes
 778       (URI or strings), whereas the RPN uses Object Identifiers
 779       for attribute sets.
 780      </p><p>
 781       The CQL library of YAZ defines a <code class="literal">cql_transform_t</code>
 782       type. It represents a particular mapping between CQL and RPN.
 783       This handle is created and destroyed by the functions:
 784      </p><pre class="synopsis">
 785 cql_transform_t cql_transform_open_FILE (FILE *f);
 786 cql_transform_t cql_transform_open_fname(const char *fname);
 787 void cql_transform_close(cql_transform_t ct);
 788       </pre><p>
 789       The first two functions create a tranformation handle from
 790       either an already open FILE or from a filename respectively.
 791      </p><p>
 792       The handle is destroyed by <code class="function">cql_transform_close</code>
 793       in which case no further reference of the handle is allowed.
 794      </p><p>
 795       When a <code class="literal">cql_transform_t</code> handle has been created
 796       you can convert to RPN.
 797       </p><pre class="synopsis">
 798 int cql_transform_buf(cql_transform_t ct,
 799                       struct cql_node *cn, char *out, int max);
 800       </pre><p>
 801       This function converts the CQL tree <code class="literal">cn</code>
 802       using handle <code class="literal">ct</code>.
 803       For the resulting PQF, you supply a buffer <code class="literal">out</code>
 804       which must be able to hold at at least <code class="literal">max</code>
 805       characters.
 806      </p><p>
 807       If conversion failed, <code class="function">cql_transform_buf</code>
 808       returns a non-zero SRU error code; otherwise zero is returned
 809       (conversion successful).  The meanings of the numeric error
 810       codes are listed in the SRU specifications at
 811       <a class="ulink" href="http://www.loc.gov/standards/sru/resources/diagnostics-list.html" target="_top">http://www.loc.gov/standards/sru/resources/diagnostics-list.html</a>
 812      </p><p>
 813       If conversion fails, more information can be obtained by calling
 814       </p><pre class="synopsis">
 815 int cql_transform_error(cql_transform_t ct, char **addinfop);
 816       </pre><p>
 817       This function returns the most recently returned numeric
 818       error-code and sets the string-pointer at
 819       <code class="literal">*addinfop</code> to point to a string containing
 820       additional information about the error that occurred: for
 821       example, if the error code is 15 (``Illegal or unsupported context
 822       set''), the additional information is the name of the requested
 823       context set that was not recognised.
 824      </p><p>
 825       The SRU error-codes may be translated into brief human-readable
 826       error messages using
 827       </p><pre class="synopsis">
 828 const char *cql_strerror(int code);
 829       </pre><p>
 830      </p><p>
 831       If you wish to be able to produce a PQF result in a different
 832       way, there are two alternatives.
 833       </p><pre class="synopsis">
 834 void cql_transform_pr(cql_transform_t ct,
 835                       struct cql_node *cn,
 836                       void (*pr)(const char *buf, void *client_data),
 837                       void *client_data);
 838
 839 int cql_transform_FILE(cql_transform_t ct,
 840                        struct cql_node *cn, FILE *f);
 841       </pre><p>
 842       The former function produces output to a user-defined
 843       output stream. The latter writes the result to an already
 844       open <code class="literal">FILE</code>.
 845      </p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cql.to.rpn"></a>1.3.4. Specification of CQL to RPN mappings</h4></div></div></div><p>
 846       The file supplied to functions
 847       <code class="function">cql_transform_open_FILE</code>,
 848       <code class="function">cql_transform_open_fname</code> follows
 849       a structure found in many Unix utilities.
 850       It consists of mapping specifications - one per line.
 851       Lines starting with <code class="literal">#</code> are ignored (comments).
 852      </p><p>
 853       Each line is of the form
 854       </p><div class="literallayout"><p><br>
 855        <em class="replaceable"><code>CQL pattern</code></em><code class="literal"> = </code> <em class="replaceable"><code> RPN equivalent</code></em><br>
 856       </p></div><p>
 857      </p><p>
 858       An RPN pattern is a simple attribute list. Each attribute pair
 859       takes the form:
 860       </p><div class="literallayout"><p><br>
 861        [<em class="replaceable"><code>set</code></em>] <em class="replaceable"><code>type</code></em><code class="literal">=</code><em class="replaceable"><code>value</code></em><br>
 862       </p></div><p>
 863       The attribute <em class="replaceable"><code>set</code></em> is optional.
 864       The <em class="replaceable"><code>type</code></em> is the attribute type,
 865       <em class="replaceable"><code>value</code></em> the attribute value.
 866      </p><p>
 867       The character <code class="literal">*</code> (asterisk) has special meaning
 868       when used in the RPN pattern.
 869       Each occurrence of <code class="literal">*</code> is substituted with the
 870       CQL matching name (index, relation, qualifier etc).
 871       This facility can be used to copy a CQL name verbatim to the RPN result.
 872      </p><p>
 873       The following CQL patterns are recognized:
 874       </p><div class="variablelist"><dl><dt><span class="term">
 875          <code class="literal">index.</code><em class="replaceable"><code>set</code></em><code class="literal">.</code><em class="replaceable"><code>name</code></em>
 876         </span></dt><dd><p>
 877           This pattern is invoked when a CQL index, such as
 878           dc.title is converted. <em class="replaceable"><code>set</code></em>
 879           and <em class="replaceable"><code>name</code></em> are the context set and index
 880           name respectively.
 881           Typically, the RPN specifies an equivalent use attribute.
 882          </p><p>
 883           For terms not bound by an index the pattern
 884           <code class="literal">index.cql.serverChoice</code> is used.
 885           Here, the prefix <code class="literal">cql</code> is defined as
 886           <code class="literal">http://www.loc.gov/zing/cql/cql-indexes/v1.0/</code>.
 887           If this pattern is not defined, the mapping will fail.
 888          </p><p>
 889           The pattern,
 890           <code class="literal">index.</code><em class="replaceable"><code>set</code></em><code class="literal">.*</code>
 891           is used when no other index pattern is matched.
 892         </p></dd><dt><span class="term">
 893          <code class="literal">qualifier.</code><em class="replaceable"><code>set</code></em><code class="literal">.</code><em class="replaceable"><code>name</code></em>
 894          (DEPRECATED)
 895         </span></dt><dd><p>
 896           For backwards compatibility, this is recognised as a synonym of
 897           <code class="literal">index.</code><em class="replaceable"><code>set</code></em><code class="literal">.</code><em class="replaceable"><code>name</code></em>
 898          </p></dd><dt><span class="term">
 899          <code class="literal">relation.</code><em class="replaceable"><code>relation</code></em>
 900         </span></dt><dd><p>
 901           This pattern specifies how a CQL relation is mapped to RPN.
 902           <em class="replaceable"><code>pattern</code></em> is name of relation
 903           operator. Since <code class="literal">=</code> is used as
 904           separator between CQL pattern and RPN, CQL relations
 905           including <code class="literal">=</code> cannot be
 906           used directly. To avoid a conflict, the names
 907           <code class="literal">ge</code>,
 908           <code class="literal">eq</code>,
 909           <code class="literal">le</code>,
 910           must be used for CQL operators, greater-than-or-equal,
 911           equal, less-than-or-equal respectively.
 912           The RPN pattern is supposed to include a relation attribute.
 913          </p><p>
 914           For terms not bound by a relation, the pattern
 915           <code class="literal">relation.scr</code> is used. If the pattern
 916           is not defined, the mapping will fail.
 917          </p><p>
 918           The special pattern, <code class="literal">relation.*</code> is used
 919           when no other relation pattern is matched.
 920          </p></dd><dt><span class="term">
 921          <code class="literal">relationModifier.</code><em class="replaceable"><code>mod</code></em>
 922         </span></dt><dd><p>
 923           This pattern specifies how a CQL relation modifier is mapped to RPN.
 924           The RPN pattern is usually a relation attribute.
 925          </p></dd><dt><span class="term">
 926          <code class="literal">structure.</code><em class="replaceable"><code>type</code></em>
 927         </span></dt><dd><p>
 928           This pattern specifies how a CQL structure is mapped to RPN.
 929           Note that this CQL pattern is somewhat to similar to
 930           CQL pattern <code class="literal">relation</code>.
 931           The <em class="replaceable"><code>type</code></em> is a CQL relation.
 932          </p><p>
 933           The pattern, <code class="literal">structure.*</code> is used
 934           when no other structure pattern is matched.
 935           Usually, the RPN equivalent specifies a structure attribute.
 936          </p></dd><dt><span class="term">
 937          <code class="literal">position.</code><em class="replaceable"><code>type</code></em>
 938         </span></dt><dd><p>
 939           This pattern specifies how the anchor (position) of
 940           CQL is mapped to RPN.
 941           The <em class="replaceable"><code>type</code></em> is one
 942           of <code class="literal">first</code>, <code class="literal">any</code>,
 943           <code class="literal">last</code>, <code class="literal">firstAndLast</code>.
 944          </p><p>
 945           The pattern, <code class="literal">position.*</code> is used
 946           when no other position pattern is matched.
 947          </p></dd><dt><span class="term">
 948          <code class="literal">set.</code><em class="replaceable"><code>prefix</code></em>
 949         </span></dt><dd><p>
 950           This specification defines a CQL context set for a given prefix.
 951           The value on the right hand side is the URI for the set -
 952           <span class="emphasis"><em>not</em></span> RPN. All prefixes used in
 953           index patterns must be defined this way.
 954          </p></dd><dt><span class="term">
 955          <code class="literal">set</code>
 956         </span></dt><dd><p>
 957           This specification defines a default CQL context set for index names.
 958           The value on the right hand side is the URI for the set.
 959          </p></dd></dl></div><p>
 960      </p><div class="example"><a name="example.cql.to.rpn.mapping"></a><p class="title"><b>Example 9.10. CQL to RPN mapping file</b></p><div class="example-contents"><p>
 961        This simple file defines two context sets, three indexes and three
 962        relations, a position pattern and a default structure.
 963       </p><pre class="programlisting">
 964        set.cql  = http://www.loc.gov/zing/cql/context-sets/cql/v1.1/
 965        set.dc   = http://www.loc.gov/zing/cql/dc-indexes/v1.0/
 966
 967        index.cql.serverChoice = 1=1016
 968        index.dc.title         = 1=4
 969        index.dc.subject       = 1=21
 970
 971        relation.&lt;             = 2=1
 972        relation.eq            = 2=3
 973        relation.scr           = 2=3
 974
 975        position.any           = 3=3 6=1
 976
 977        structure.*            = 4=1
 978
 979       </pre><p>
 980        With the mappings above, the CQL query
 981        </p><pre class="screen">
 982         computer
 983        </pre><p>
 984        is converted to the PQF:
 985        </p><pre class="screen">
 986         @attr 1=1016 @attr 2=3 @attr 4=1 @attr 3=3 @attr 6=1 "computer"
 987        </pre><p>
 988        by rules <code class="literal">index.cql.serverChoice</code>,
 989        <code class="literal">relation.scr</code>, <code class="literal">structure.*</code>,
 990        <code class="literal">position.any</code>.
 991       </p><p>
 992        CQL query
 993        </p><pre class="screen">
 994         computer^
 995        </pre><p>
 996        is rejected, since <code class="literal">position.right</code> is
 997        undefined.
 998       </p><p>
 999        CQL query
1000        </p><pre class="screen">
1001         &gt;my = "http://www.loc.gov/zing/cql/dc-indexes/v1.0/" my.title = x
1002        </pre><p>
1003        is converted to
1004        </p><pre class="screen">
1005         @attr 1=4 @attr 2=3 @attr 4=1 @attr 3=3 @attr 6=1 "x"
1006        </pre><p>
1007       </p></div></div><br class="example-break"><div class="example"><a name="example.cql.to.rpn.string"></a><p class="title"><b>Example 9.11. CQL to RPN string attributes</b></p><div class="example-contents"><p>
1008        In this example we allow any index to be passed to RPN as
1009        a use attribute.
1010       </p><pre class="programlisting">
1011        # Identifiers for prefixes used in this file. (index.*)
1012        set.cql  = info:srw/cql-context-set/1/cql-v1.1
1013        set.rpn  = http://bogus/rpn
1014        set      = http://bogus/rpn
1015
1016        # The default index when none is specified by the query
1017        index.cql.serverChoice     = 1=any
1018
1019        index.rpn.*                = 1=*
1020        relation.eq                = 2=3
1021        structure.*                = 4=1
1022        position.any               = 3=3
1023
1024       </pre><p>
1025        The <code class="literal">http://bogus/rpn</code> context set is also the default
1026        so we can make queries such as
1027        </p><pre class="screen">
1028         title = a
1029        </pre><p>
1030        which is converted to
1031        </p><pre class="screen">
1032         @attr 2=3 @attr 4=1 @attr 3=3 @attr 1=title "a"
1033        </pre><p>
1034       </p></div></div><br class="example-break"><div class="example"><a name="example.cql.to.rpn.bathprofile"></a><p class="title"><b>Example 9.12. CQL to RPN using Bath Profile</b></p><div class="example-contents"><p>
1035        The file <code class="filename">etc/pqf.properties</code> has mappings from
1036        the Bath Profile and Dublin Core to RPN.
1037        If YAZ is installed as a package it's usually located
1038        in <code class="filename">/usr/share/yaz/etc</code> and part of the
1039        development package, such as <code class="literal">libyaz-dev</code>.
1040       </p></div></div><br class="example-break"></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="cql.xcql"></a>1.3.5. CQL to XCQL conversion</h4></div></div></div><p>
1041       Conversion from CQL to XCQL is trivial and does not
1042       require a mapping to be defined.
1043       There three functions to choose from depending on the
1044       way you wish to store the resulting output (XML buffer
1045       containing XCQL).
1046       </p><pre class="synopsis">
1047 int cql_to_xml_buf(struct cql_node *cn, char *out, int max);
1048 void cql_to_xml(struct cql_node *cn,
1049                 void (*pr)(const char *buf, void *client_data),
1050                 void *client_data);
1051 void cql_to_xml_stdio(struct cql_node *cn, FILE *f);
1052       </pre><p>
1053       Function <code class="function">cql_to_xml_buf</code> converts
1054       to XCQL and stores result in a user supplied buffer of a given
1055       max size.
1056      </p><p>
1057       <code class="function">cql_to_xml</code> writes the result in
1058       a user defined output stream.
1059       <code class="function">cql_to_xml_stdio</code> writes to a
1060       a file.
1061      </p></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="soap.srw.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="tools.oid.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. SRU </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2. Object Identifiers</td></tr></table></div></body></html>