node-zoom

<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�7.�Supporting Tools</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" 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�7.�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"><div class="titlepage"><div><div><h1 class="title"><a name="tools"></a>Chapter�7.�Supporting Tools</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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><dt><span class="sect3"><a href="tools.html#rpn.to.cql">1.3.6. PQF to CQL 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></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><dd><dl><dt><span class="sect2"><a href="marc.html#tools.turbomarc">5.1. TurboMARC</a></span></dt></dl></dd><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><dt><span class="sect1"><a href="sorting.html">7. Sorting</a></span></dt><dd><dl><dt><span class="sect2"><a href="sorting.html#idp50992096">7.1. Using the Z39.50 sort service</a></span></dt><dt><span class="sect2"><a href="sorting.html#idp50995920">7.2. Type-7 sort</a></span></dt></dl></dd><dt><span class="sect1"><a href="facets.html">8. Facets</a></span></dt></dl></div><p> In support of the service API - primarily the ASN module, which provides the pro-grammatic interface to the Z39.50 APDUs, YAZ contains a collection of tools that support the development of applications. </p><div class="sect1"><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> Since the type-1 (RPN) query structure has no direct, useful string representation, every origin application needs to provide some form of mapping from a local query notation or representation to a <span class="token">Z_RPNQuery</span> structure. Some programmers will prefer to construct the query manually, perhaps using <code class="function">odr_malloc()</code> to simplify memory management. The YAZ distribution includes three separate, query-generating tools that may be of use to you. </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="PQF"></a>1.1.�Prefix Query Format</h3></div></div></div><p> Since RPN or reverse polish notation is really just a fancy way of describing a suffix notation format (operator follows operands), it would seem that the confusion is total when we now introduce a prefix notation for RPN. The reason is one of simple laziness - it's somewhat simpler to interpret a prefix format, and this utility was designed for maximum simplicity, to provide a baseline representation for use in simple test applications and scripting environments (like Tcl). The demonstration client included with YAZ uses the PQF. </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> The PQF have been adopted by other parties developing Z39.50 software. It is often referred to as Prefix Query Notation - PQN. </p></div><p> The PQF is defined by the pquery module in the YAZ library. There are two sets of function that have similar behavior. First set operates on a PQF parser handle, second set doesn't. First set set of functions are more flexible than the second set. Second set is obsolete and is only provided to ensure backwards compatibility. </p><p> First set of functions all operate on a PQF parser handle: </p><pre class="synopsis"> #include <yaz/pquery.h> YAZ_PQF_Parser yaz_pqf_create(void); void yaz_pqf_destroy(YAZ_PQF_Parser p); Z_RPNQuery *yaz_pqf_parse(YAZ_PQF_Parser p, ODR o, const char *qbuf); Z_AttributesPlusTerm *yaz_pqf_scan(YAZ_PQF_Parser p, ODR o, Odr_oid **attributeSetId, const char *qbuf); int yaz_pqf_error(YAZ_PQF_Parser p, const char **msg, size_t *off); </pre><p> A PQF parser is created and destructed by functions <code class="function">yaz_pqf_create</code> and <code class="function">yaz_pqf_destroy</code> respectively. Function <code class="function">yaz_pqf_parse</code> parses query given by string <code class="literal">qbuf</code>. If parsing was successful, a Z39.50 RPN Query is returned which is created using ODR stream <code class="literal">o</code>. If parsing failed, a NULL pointer is returned. Function <code class="function">yaz_pqf_scan</code> takes a scan query in <code class="literal">qbuf</code>. If parsing was successful, the function returns attributes plus term pointer and modifies <code class="literal">attributeSetId</code> to hold attribute set for the scan request - both allocated using ODR stream <code class="literal">o</code>. If parsing failed, yaz_pqf_scan returns a NULL pointer. Error information for bad queries can be obtained by a call to <code class="function">yaz_pqf_error</code> which returns an error code and modifies <code class="literal">*msg</code> to point to an error description, and modifies <code class="literal">*off</code> to the offset within last query were parsing failed. </p><p> The second set of functions are declared as follows: </p><pre class="synopsis"> #include <yaz/pquery.h> Z_RPNQuery *p_query_rpn(ODR o, oid_proto proto, const char *qbuf); Z_AttributesPlusTerm *p_query_scan(ODR o, oid_proto proto, Odr_oid **attributeSetP, const char *qbuf); int p_query_attset(const char *arg); </pre><p> The function <code class="function">p_query_rpn()</code> takes as arguments an <acronym class="acronym">ODR</acronym> stream (see section <a class="link" href="odr.html" title="Chapter�8.�The ODR Module">The ODR Module</a>) to provide a memory source (the structure created is released on the next call to <code class="function">odr_reset()</code> on the stream), a protocol identifier (one of the constants <span class="token">PROTO_Z3950</span> and <span class="token">PROTO_SR</span>), an attribute set reference, and finally a null-terminated string holding the query string. </p><p> If the parse went well, <code class="function">p_query_rpn()</code> returns a pointer to a <code class="literal">Z_RPNQuery</code> structure which can be placed directly into a <code class="literal">Z_SearchRequest</code>. If parsing failed, due to syntax error, a NULL pointer is returned. </p><p> The <code class="literal">p_query_attset</code> specifies which attribute set to use if the query doesn't specify one by the <code class="literal">@attrset</code> operator. The <code class="literal">p_query_attset</code> returns 0 if the argument is a valid attribute set specifier; otherwise the function returns -1. </p><p> The grammar of the PQF is as follows: </p><div class="literallayout"><p><br> ��query�::=�top-set�query-struct.<br> <br> ��top-set�::=�[�'@attrset'�string�]<br> <br> ��query-struct�::=�attr-spec�|�simple�|�complex�|�'@term'�term-type�query<br> <br> ��attr-spec�::=�'@attr'�[�string�]�string�query-struct<br> <br> ��complex�::=�operator�query-struct�query-struct.<br> <br> ��operator�::=�'@and'�|�'@or'�|�'@not'�|�'@prox'�proximity.<br> <br> ��simple�::=�result-set�|�term.<br> <br> ��result-set�::=�'@set'�string.<br> <br> ��term�::=�string.<br> <br> ��proximity�::=�exclusion�distance�ordered�relation�which-code�unit-code.<br> <br> ��exclusion�::=�'1'�|�'0'�|�'void'.<br> <br> ��distance�::=�integer.<br> <br> ��ordered�::=�'1'�|�'0'.<br> <br> ��relation�::=�integer.<br> <br> ��which-code�::=�'known'�|�'private'�|�integer.<br> <br> ��unit-code�::=�integer.<br> <br> ��term-type�::=�'general'�|�'numeric'�|�'string'�|�'oid'�|�'datetime'�|�'null'.<br> ��</p></div><p> You will note that the syntax above is a fairly faithful representation of RPN, except for the Attribute, which has been moved a step away from the term, allowing you to associate one or more attributes with an entire query structure. The parser will automatically apply the given attributes to each term as required. </p><p> The @attr operator is followed by an attribute specification (<code class="literal">attr-spec</code> above). The specification consists of an optional attribute set, an attribute type-value pair and a sub-query. The attribute type-value pair is packed in one string: an attribute type, an equals sign, and an attribute value, like this: <code class="literal">@attr 1=1003</code>. The type is always an integer but the value may be either an integer or a string (if it doesn't start with a digit character). A string attribute-value is encoded as a Type-1 ``complex'' attribute with the list of values containing the single string specified, and including no semantic indicators. </p><p> Version 3 of the Z39.50 specification defines various encoding of terms. Use <code class="literal">@term </code> <em class="replaceable"><code>type</code></em> <em class="replaceable"><code>string</code></em>, where type is one of: <code class="literal">general</code>, <code class="literal">numeric</code> or <code class="literal">string</code> (for InternationalString). If no term type has been given, the <code class="literal">general</code> form is used. This is the only encoding allowed in both versions 2 and 3 of the Z39.50 standard. </p><div class="sect3"><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> This is an advanced topic, describing how to construct queries that make very specific requirements on the relative location of their operands. You may wish to skip this section and go straight to <a class="link" href="tools.html#pqf-examples" title="1.1.2.�PQF queries">the example PQF queries</a>. </p><p> </p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p> Most Z39.50 servers do not support proximity searching, or support only a small subset of the full functionality that can be expressed using the PQF proximity operator. Be aware that the ability to <span class="emphasis"><em>express</em></span> a query in PQF is no guarantee that any given server will be able to <span class="emphasis"><em>execute</em></span> it. </p></div><p> </p></div><p> The proximity operator <code class="literal">@prox</code> is a special and more restrictive version of the conjunction operator <code class="literal">@and</code>. Its semantics are described in section 3.7.2 (Proximity) of Z39.50 the standard itself, which can be read on-line at <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> </p><p> In PQF, the proximity operation is represented by a sequence of the form </p><pre class="screen"> @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> </pre><p> in which the meanings of the parameters are as described in in the standard, and they can take the following values: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>exclusion.�</b> 0 = false (i.e. the proximity condition specified by the remaining parameters must be satisfied) or 1 = true (the proximity condition specified by the remaining parameters must <span class="emphasis"><em>not</em></span> be satisifed). </p></li><li class="listitem"><p><b>distance.�</b> An integer specifying the difference between the locations of the operands: e.g. two adjacent words would have distance=1 since their locations differ by one unit. </p></li><li class="listitem"><p><b>ordered.�</b> 1 = ordered (the operands must occur in the order the query specifies them) or 0 = unordered (they may appear in either order). </p></li><li class="listitem"><p><b>relation.�</b> Recognised values are 1 (lessThan), 2 (lessThanOrEqual), 3 (equal), 4 (greaterThanOrEqual), 5 (greaterThan) and 6 (notEqual). </p></li><li class="listitem"><p><b>which-code.�</b> <code class="literal">known</code> or <code class="literal">k</code> (the unit-code parameter is taken from the well-known list of alternatives described in below) or <code class="literal">private</code> or <code class="literal">p</code> (the unit-code paramater has semantics specific to an out-of-band agreement such as a profile). </p></li><li class="listitem"><p><b>unit-code.�</b> If the which-code parameter is <code class="literal">known</code> then the recognised values are 1 (character), 2 (word), 3 (sentence), 4 (paragraph), 5 (section), 6 (chapter), 7 (document), 8 (element), 9 (subelement), 10 (elementType) and 11 (byte). If which-code is <code class="literal">private</code> then the acceptable values are determined by the profile. </p></li></ul></div><p> (The numeric values of the relation and well-known unit-code parameters are taken straight from <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.) </p></div><div class="sect3"><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�7.1.�PQF queries using simple terms</b></p><div class="example-contents"><p> </p><pre class="screen"> dylan "bob dylan" </pre><p> </p></div></div><br class="example-break"><div class="example"><a name="pqf.example.pqf.boolean.operators"></a><p class="title"><b>Example�7.2.�PQF boolean operators</b></p><div class="example-contents"><p> </p><pre class="screen"> @or "dylan" "zimmerman" @and @or dylan zimmerman when @and when @or dylan zimmerman </pre><p> </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.result.sets"></a><p class="title"><b>Example�7.3.�PQF references to result sets</b></p><div class="example-contents"><p> </p><pre class="screen"> @set Result-1 @and @set seta @set setb </pre><p> </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.attributes"></a><p class="title"><b>Example�7.4.�Attributes for terms</b></p><div class="example-contents"><p> </p><pre class="screen"> @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 </pre><p> </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.proximity"></a><p class="title"><b>Example�7.5.�PQF Proximity queries</b></p><div class="example-contents"><p> </p><pre class="screen"> @prox 0 3 1 2 k 2 dylan zimmerman </pre><p> Here the parameters 0, 3, 1, 2, k and 2 represent exclusion, distance, ordered, relation, which-code and unit-code, in that order. So: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>exclusion = 0: the proximity condition must hold</p></li><li class="listitem"><p>distance = 3: the terms must be three units apart</p></li><li class="listitem"><p> ordered = 1: they must occur in the order they are specified </p></li><li class="listitem"><p> relation = 2: lessThanOrEqual (to the distance of 3 units) </p></li><li class="listitem"><p> which-code is ``known'', so the standard unit-codes are used </p></li><li class="listitem"><p>unit-code = 2: word.</p></li></ul></div><p> So the whole proximity query means that the words <code class="literal">dylan</code> and <code class="literal">zimmerman</code> must both occur in the record, in that order, differing in position by three or fewer words (i.e. with two or fewer words between them.) The query would find ``Bob Dylan, aka. Robert Zimmerman'', but not ``Bob Dylan, born as Robert Zimmerman'' since the distance in this case is four. </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.search.term.type"></a><p class="title"><b>Example�7.6.�PQF specification of search term type</b></p><div class="example-contents"><p> </p><pre class="screen"> @term string "a UTF-8 string, maybe?" </pre><p> </p></div></div><br class="example-break"><div class="example"><a name="example.pqf.mixed.queries"></a><p class="title"><b>Example�7.7.�PQF mixed queries</b></p><div class="example-contents"><p> </p><pre class="screen"> @or @and bob dylan @set Result-1 @attr 4=1 @and @attr 1=1 "bob dylan" @attr 1=4 "slow train coming" @and @attr 2=4 @attr gils 1=2038 -114 @attr 2=2 @attr gils 1=2039 -109 </pre><p> The last of these examples is a spatial search: in <a class="ulink" href="http://www.gils.net/prof_v2.html#sec_7_4" target="_top">the GILS attribute set</a>, access point 2038 indicates West Bounding Coordinate and 2030 indicates East Bounding Coordinate, so the query is for areas extending from -114 degrees to no more than -109 degrees. </p></div></div><br class="example-break"></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="CCL"></a>1.2.�CCL</h3></div></div></div><p> Not all users enjoy typing in prefix query structures and numerical attribute values, even in a minimalistic test client. In the library world, the more intuitive Common Command Language - CCL (ISO 8777) has enjoyed some popularity - especially before the widespread availability of graphical interfaces. It is still useful in applications where you for some reason or other need to provide a symbolic language for expressing boolean query structures. </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="ccl.syntax"></a>1.2.1.�CCL Syntax</h4></div></div></div><p> The CCL parser obeys the following grammar for the FIND argument. The syntax is annotated by in the lines prefixed by <code class="literal">--</code>. </p><pre class="screen"> CCL-Find ::= CCL-Find Op Elements | Elements. Op ::= "and" | "or" | "not" -- The above means that Elements are separated by boolean operators. Elements ::= '(' CCL-Find ')' | Set | Terms | Qualifiers Relation Terms | Qualifiers Relation '(' CCL-Find ')' | Qualifiers '=' string '-' string -- Elements is either a recursive definition, a result set reference, a -- list of terms, qualifiers followed by terms, qualifiers followed -- by a recursive definition or qualifiers in a range (lower - upper). Set ::= 'set' = string -- Reference to a result set Terms ::= Terms Prox Term | Term -- Proximity of terms. Term ::= Term string | string -- This basically means that a term may include a blank Qualifiers ::= Qualifiers ',' string | string -- Qualifiers is a list of strings separated by comma Relation ::= '=' | '>=' | '<=' | '<>' | '>' | '<' -- Relational operators. This really doesn't follow the ISO8777 -- standard. Prox ::= '%' | '!' -- Proximity operator </pre><div class="example"><a name="example.ccl.queries"></a><p class="title"><b>Example�7.8.�CCL queries</b></p><div class="example-contents"><p> The following queries are all valid: </p><pre class="screen"> dylan "bob dylan" dylan or zimmerman set=1 (dylan and bob) or set=1 righttrunc? "notrunc?" singlechar#mask </pre><p> Assuming that the qualifiers <code class="literal">ti</code>, <code class="literal">au</code> and <code class="literal">date</code> are defined we may use: </p><pre class="screen"> ti=self portrait au=(bob dylan and slow train coming) date>1980 and (ti=((self portrait))) </pre></div></div><br class="example-break"></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="ccl.qualifiers"></a>1.2.2.�CCL Qualifiers</h4></div></div></div><p> Qualifiers are used to direct the search to a particular searchable index, such as title (ti) and author indexes (au). The CCL standard itself doesn't specify a particular set of qualifiers, but it does suggest a few short-hand notations. You can customize the CCL parser to support a particular set of qualifiers to reflect the current target profile. Traditionally, a qualifier would map to a particular use-attribute within the BIB-1 attribute set. It is also possible to set other attributes, such as the structure attribute. </p><p> A CCL profile is a set of predefined CCL qualifiers that may be read from a file or set in the CCL API. The YAZ client reads its CCL qualifiers from a file named <code class="filename">default.bib</code>. There are four types of lines in a CCL profile: qualifier specification, qualifier alias, comments and directives. </p><div class="sect4"><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> A qualifier specification is of the form: </p><p> <em class="replaceable"><code>qualifier-name</code></em> [<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> [<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> ... </p><p> where <em class="replaceable"><code>qualifier-name</code></em> is the name of the qualifier to be used (eg. <code class="literal">ti</code>), <em class="replaceable"><code>type</code></em> is attribute type in the attribute set (Bib-1 is used if no attribute set is given) and <em class="replaceable"><code>val</code></em> is attribute value. The <em class="replaceable"><code>type</code></em> can be specified as an integer or as it be specified either as a single-letter: <code class="literal">u</code> for use, <code class="literal">r</code> for relation,<code class="literal">p</code> for position, <code class="literal">s</code> for structure,<code class="literal">t</code> for truncation or <code class="literal">c</code> for completeness. The attributes for the special qualifier name <code class="literal">term</code> are used when no CCL qualifier is given in a query. </p><div class="table"><a name="ccl.common.bib1.attributes"></a><p class="title"><b>Table�7.1.�Common Bib-1 attributes</b></p><div class="table-contents"><table summary="Common Bib-1 attributes" border="1"><colgroup><col class="type"><col class="description"></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> Use attribute (1). Common use attributes are 1 Personal-name, 4 Title, 7 ISBN, 8 ISSN, 30 Date, 62 Subject, 1003 Author), 1016 Any. Specify value as an integer. </td></tr><tr><td><code class="literal">r=</code><em class="replaceable"><code>value</code></em></td><td> Relation attribute (2). Common values are 1 <, 2 <=, 3 =, 4 >=, 5 >, 6 <>, 100 phonetic, 101 stem, 102 relevance, 103 always matches. </td></tr><tr><td><code class="literal">p=</code><em class="replaceable"><code>value</code></em></td><td> Position attribute (3). Values: 1 first in field, 2 first in any subfield, 3 any position in field. </td></tr><tr><td><code class="literal">s=</code><em class="replaceable"><code>value</code></em></td><td> Structure attribute (4). Values: 1 phrase, 2 word, 3 key, 4 year, 5 date, 6 word list, 100 date (un), 101 name (norm), 102 name (un), 103 structure, 104 urx, 105 free-form-text, 106 document-text, 107 local-number, 108 string, 109 numeric string. </td></tr><tr><td><code class="literal">t=</code><em class="replaceable"><code>value</code></em></td><td> Truncation attribute (5). Values: 1 right, 2 left, 3 left& right, 100 none, 101 process #, 102 regular-1, 103 regular-2, 104 CCL. </td></tr><tr><td><code class="literal">c=</code><em class="replaceable"><code>value</code></em></td><td> Completeness attribute (6). Values: 1 incomplete subfield, 2 complete subfield, 3 complete field. </td></tr></tbody></table></div></div><p><br class="table-break"> </p><p> Refer to <a class="xref" href="bib1.html" title="Bib-1 Attribute Set"><span class="refentrytitle">Bib-1 Attribute Set</span>(7)</a> or the complete <a class="ulink" href="http://www.loc.gov/z3950/agency/defns/bib1.html" target="_top">list of Bib-1 attributes</a> </p><p> It is also possible to specify non-numeric attribute values, which are used in combination with certain types. The special combinations are: </p><div class="table"><a name="ccl.special.attribute.combos"></a><p class="title"><b>Table�7.2.�Special attribute combos</b></p><div class="table-contents"><table summary="Special attribute combos" border="1"><colgroup><col class="name"><col class="description"></colgroup><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody><tr><td><code class="literal">s=pw</code></td><td> The structure is set to either word or phrase depending on the number of tokens in a term (phrase-word). </td></tr><tr><td><code class="literal">s=al</code></td><td> Each token in the term is ANDed. (and-list). This does not set the structure at all. </td></tr><tr><td><code class="literal">s=ol</code></td><td> Each token in the term is ORed. (or-list). This does not set the structure at all. </td></tr><tr><td><code class="literal">s=ag</code></td><td> Tokens that appears as phrases (with blank in them) gets structure phrase attached (4=1). Tokens that appear to be words gets structure word attached (4=2). Phrases and words are ANDed. This is a variant of s=al and s=pw, with the main difference that words are not split (with operator AND) but instead kept in one RPN token. This facility appeared in YAZ 4.2.38. </td></tr><tr><td><code class="literal">r=o</code></td><td> Allows ranges and the operators greather-than, less-than, ... equals. This sets Bib-1 relation attribute accordingly (relation ordered). A query construct is only treated as a range if dash is used and that is surrounded by white-space. So <code class="literal">-1980</code> is treated as term <code class="literal">"-1980"</code> not <code class="literal"><= 1980</code>. If <code class="literal">- 1980</code> is used, however, that is treated as a range. </td></tr><tr><td><code class="literal">r=r</code></td><td> Similar to <code class="literal">r=o</code> but assumes that terms are non-negative (not prefixed with <code class="literal">-</code>). Thus, a dash will always be treated as a range. The construct <code class="literal">1980-1990</code> is treated as a range with <code class="literal">r=r</code> but as a single term <code class="literal">"1980-1990"</code> with <code class="literal">r=o</code>. The special attribute <code class="literal">r=r</code> is available in YAZ 2.0.24 or later. </td></tr><tr><td><code class="literal">r=omiteq</code></td><td> This will omit relation=equals (@attr 2=3) when r=o / r=r is used. This is useful for servers that somehow breaks when an explicit relation=equals is used. Omitting the relation is usually safe because "equals" is the default behavior. This tweak was added in YAZ version 5.1.2. </td></tr><tr><td><code class="literal">t=l</code></td><td> Allows term to be left-truncated. If term is of the form <code class="literal">?x</code>, the resulting Type-1 term is <code class="literal">x</code> and truncation is left. </td></tr><tr><td><code class="literal">t=r</code></td><td> Allows term to be right-truncated. If term is of the form <code class="literal">x?</code>, the resulting Type-1 term is <code class="literal">x</code> and truncation is right. </td></tr><tr><td><code class="literal">t=n</code></td><td> If term is does not include <code class="literal">?</code>, the truncation attribute is set to none (100). </td></tr><tr><td><code class="literal">t=b</code></td><td> Allows term to be both left&right truncated. If term is of the form <code class="literal">?x?</code>, the resulting term is <code class="literal">x</code> and trunctation is set to both left&right. </td></tr><tr><td><code class="literal">t=x</code></td><td> Allows masking anywhere in a term, thus fully supporting # (mask one character) and ? (zero or more of any). If masking is used, trunction is set to 102 (regexp-1 in term) and the term is converted accordingly to a regular expression. </td></tr><tr><td><code class="literal">t=z</code></td><td> Allows masking anywhere in a term, thus fully supporting # (mask one character) and ? (zero or more of any). If masking is used, trunction is set to 104 (Z39.58 in term) and the term is converted accordingly to Z39.58 masking term - actually the same truncation as CCL itself. </td></tr></tbody></table></div></div><p><br class="table-break"> </p><div class="example"><a name="example.ccl.profile"></a><p class="title"><b>Example�7.9.�CCL profile</b></p><div class="example-contents"><p> Consider the following definition: </p><pre class="screen"> ti u=4 s=1 au u=1 s=1 term s=105 ranked r=102 date u=30 r=o </pre><p> <code class="literal">ti</code> and <code class="literal">au</code> both set structure attribute to phrase (s=1). <code class="literal">ti</code> sets the use-attribute to 4. <code class="literal">au</code> sets the use-attribute to 1. When no qualifiers are used in the query the structure-attribute is set to free-form-text (105) (rule for <code class="literal">term</code>). The <code class="literal">date</code> sets the relation attribute to the relation used in the CCL query and sets the use attribute to 30 (Bib-1 Date). </p><p> You can combine attributes. To Search for "ranked title" you can do </p><pre class="screen"> ti,ranked=knuth computer </pre><p> which will set relation=ranked, use=title, structure=phrase. </p><p> Query </p><pre class="screen"> date > 1980 </pre><p> is a valid query. But </p><pre class="screen"> ti > 1980 </pre><p> is invalid. </p></div></div><br class="example-break"></div><div class="sect4"><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> A qualifier alias is of the form: </p><p> <em class="replaceable"><code>q</code></em> <em class="replaceable"><code>q1</code></em> <em class="replaceable"><code>q2</code></em> .. </p><p> which declares <em class="replaceable"><code>q</code></em> to be an alias for <em class="replaceable"><code>q1</code></em>, <em class="replaceable"><code>q2</code></em>... such that the CCL query <em class="replaceable"><code>q=x</code></em> is equivalent to <em class="replaceable"><code>q1=x or q2=x or ...</code></em>. </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="ccl.comments"></a>1.2.2.3.�Comments</h5></div></div></div><p> Lines with white space or lines that begin with character <code class="literal">#</code> are treated as comments. </p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="ccl.directives"></a>1.2.2.4.�Directives</h5></div></div></div><p> Directive specifications takes the form </p><p><code class="literal">@</code><em class="replaceable"><code>directive</code></em> <em class="replaceable"><code>value</code></em> </p><div class="table"><a name="ccl.directives.table"></a><p class="title"><b>Table�7.3.�CCL directives</b></p><div class="table-contents"><table summary="CCL directives" border="1"><colgroup><col class="name"><col class="description"><col class="default"></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>mask</td><td>Masking character. Requires YAZ 4.2.58 or later</td><td><code class="literal">#</code></td></tr><tr><td>field</td><td>Specifies how multiple fields are to be combined. There are two modes: <code class="literal">or</code>: multiple qualifier fields are ORed, <code class="literal">merge</code>: attributes for the qualifier fields are merged and assigned to one term. </td><td><code class="literal">merge</code></td></tr><tr><td>case</td><td>Specifies if CCL operators and qualifiers should be compared with case sensitivity or not. Specify 1 for case sensitive; 0 for case insensitive.</td><td><code class="literal">1</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"><div class="titlepage"><div><div><h4 class="title"><a name="ccl.api"></a>1.2.3.�CCL API</h4></div></div></div><p> All public definitions can be found in the header file <code class="filename">ccl.h</code>. A profile identifier is of type <code class="literal">CCL_bibset</code>. A profile must be created with the call to the function <code class="function">ccl_qual_mk</code> which returns a profile handle of type <code class="literal">CCL_bibset</code>. </p><p> To read a file containing qualifier definitions the function <code class="function">ccl_qual_file</code> may be convenient. This function takes an already opened <code class="literal">FILE</code> handle pointer as argument along with a <code class="literal">CCL_bibset</code> handle. </p><p> To parse a simple string with a FIND query use the function </p><pre class="screen"> struct ccl_rpn_node *ccl_find_str(CCL_bibset bibset, const char *str, int *error, int *pos); </pre><p> which takes the CCL profile (<code class="literal">bibset</code>) and query (<code class="literal">str</code>) as input. Upon successful completion the RPN tree is returned. If an error occur, such as a syntax error, the integer pointed to by <code class="literal">error</code> holds the error code and <code class="literal">pos</code> holds the offset inside query string in which the parsing failed. </p><p> An English representation of the error may be obtained by calling the <code class="literal">ccl_err_msg</code> function. The error codes are listed in <code class="filename">ccl.h</code>. </p><p> To convert the CCL RPN tree (type <code class="literal">struct ccl_rpn_node *</code>) to the Z_RPNQuery of YAZ the function <code class="function">ccl_rpn_query</code> must be used. This function which is part of YAZ is implemented in <code class="filename">yaz-ccl.c</code>. After calling this function the CCL RPN tree is probably no longer needed. The <code class="literal">ccl_rpn_delete</code> destroys the CCL RPN tree. </p><p> A CCL profile may be destroyed by calling the <code class="function">ccl_qual_rm</code> function. </p><p> The token names for the CCL operators may be changed by setting the globals (all type <code class="literal">char *</code>) <code class="literal">ccl_token_and</code>, <code class="literal">ccl_token_or</code>, <code class="literal">ccl_token_not</code> and <code class="literal">ccl_token_set</code>. An operator may have aliases, i.e. there may be more than one name for the operator. To do this, separate each alias with a space character. </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="cql"></a>1.3.�CQL</h3></div></div></div><p> <a class="ulink" href="http://www.loc.gov/standards/sru/cql/" target="_top">CQL</a> - Common Query Language - was defined for the <a class="ulink" href="http://www.loc.gov/standards/sru/" target="_top">SRU</a> 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 <span class="emphasis"><em>the</em></span> protocol query language for SRU. </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p> If you are new to CQL, read the <a class="ulink" href="http://zing.z3950.org/cql/intro.html" target="_top">Gentle Introduction</a>. </p></div><p> The CQL parser in YAZ provides the following: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> It parses and validates a CQL query. </p></li><li class="listitem"><p> It generates a C structure that allows you to convert a CQL query to some other query language, such as SQL. </p></li><li class="listitem"><p> The parser converts a valid CQL query to PQF, thus providing a way to use CQL for both SRU servers and Z39.50 targets at the same time. </p></li><li class="listitem"><p> The parser converts CQL to XCQL. XCQL is an XML representation of CQL. XCQL is part of the SRU specification. However, since SRU supports CQL only, we don't expect XCQL to be widely used. Furthermore, CQL has the advantage over XCQL that it is easy to read. </p></li></ul></div><p> </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="cql.parsing"></a>1.3.1.�CQL parsing</h4></div></div></div><p> A CQL parser is represented by the <code class="literal">CQL_parser</code> handle. Its contents should be considered YAZ internal (private). </p><pre class="synopsis"> #include <yaz/cql.h> typedef struct cql_parser *CQL_parser; CQL_parser cql_parser_create(void); void cql_parser_destroy(CQL_parser cp); </pre><p> A parser is created by <code class="function">cql_parser_create</code> and is destroyed by <code class="function">cql_parser_destroy</code>. </p><p> To parse a CQL query string, the following function is provided: </p><pre class="synopsis"> int cql_parser_string(CQL_parser cp, const char *str); </pre><p> A CQL query is parsed by the <code class="function">cql_parser_string</code> which takes a query <em class="parameter"><code>str</code></em>. If the query was valid (no syntax errors), then zero is returned; otherwise -1 is returned to indicate a syntax error. </p><p> </p><pre class="synopsis"> int cql_parser_stream(CQL_parser cp, int (*getbyte)(void *client_data), void (*ungetbyte)(int b, void *client_data), void *client_data); int cql_parser_stdio(CQL_parser cp, FILE *f); </pre><p> The functions <code class="function">cql_parser_stream</code> and <code class="function">cql_parser_stdio</code> parses a CQL query - just like <code class="function">cql_parser_string</code>. The only difference is that the CQL query can be fed to the parser in different ways. The <code class="function">cql_parser_stream</code> uses a generic byte stream as input. The <code class="function">cql_parser_stdio</code> uses a <code class="literal">FILE</code> handle which is opened for reading. </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="cql.tree"></a>1.3.2.�CQL tree</h4></div></div></div><p> The the query string is valid, the CQL parser generates a tree representing the structure of the CQL query. </p><p> </p><pre class="synopsis"> struct cql_node *cql_parser_result(CQL_parser cp); </pre><p> <code class="function">cql_parser_result</code> returns the a pointer to the root node of the resulting tree. </p><p> Each node in a CQL tree is represented by a <code class="literal">struct cql_node</code>. It is defined as follows: </p><pre class="synopsis"> #define CQL_NODE_ST 1 #define CQL_NODE_BOOL 2 #define CQL_NODE_SORT 3 struct cql_node { int which; union { struct { char *index; char *index_uri; char *term; char *relation; char *relation_uri; struct cql_node *modifiers; } st; struct { char *value; struct cql_node *left; struct cql_node *right; struct cql_node *modifiers; } boolean; struct { char *index; struct cql_node *next; struct cql_node *modifiers; struct cql_node *search; } sort; } u; }; </pre><p> There are three node types: search term (ST), boolean (BOOL) and sortby (SORT). A modifier is treated as a search term too. </p><p> The search term node has five members: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <code class="literal">index</code>: index for search term. If an index is unspecified for a search term, <code class="literal">index</code> will be NULL. </p></li><li class="listitem"><p> <code class="literal">index_uri</code>: index URi for search term or NULL if none could be resolved for the index. </p></li><li class="listitem"><p> <code class="literal">term</code>: the search term itself. </p></li><li class="listitem"><p> <code class="literal">relation</code>: relation for search term. </p></li><li class="listitem"><p> <code class="literal">relation_uri</code>: relation URI for search term. </p></li><li class="listitem"><p> <code class="literal">modifiers</code>: relation modifiers for search term. The <code class="literal">modifiers</code> list itself of cql_nodes each of type <code class="literal">ST</code>. </p></li></ul></div><p> </p><p> The boolean node represents <code class="literal">and</code>, <code class="literal">or</code>, <code class="literal">not</code> + proximity. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <code class="literal">left</code> and <code class="literal">right</code>: left - and right operand respectively. </p></li><li class="listitem"><p> <code class="literal">modifiers</code>: proximity arguments. </p></li></ul></div><p> </p><p> The sort node represents both the SORTBY clause. </p></div><div class="sect3"><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> Conversion to PQF (and Z39.50 RPN) is tricky by the fact that the resulting RPN depends on the Z39.50 target capabilities (combinations of supported attributes). In addition, the CQL and SRU operates on index prefixes (URI or strings), whereas the RPN uses Object Identifiers for attribute sets. </p><p> The CQL library of YAZ defines a <code class="literal">cql_transform_t</code> type. It represents a particular mapping between CQL and RPN. This handle is created and destroyed by the functions: </p><pre class="synopsis"> cql_transform_t cql_transform_open_FILE (FILE *f); cql_transform_t cql_transform_open_fname(const char *fname); void cql_transform_close(cql_transform_t ct); </pre><p> The first two functions create a tranformation handle from either an already open FILE or from a filename respectively. </p><p> The handle is destroyed by <code class="function">cql_transform_close</code> in which case no further reference of the handle is allowed. </p><p> When a <code class="literal">cql_transform_t</code> handle has been created you can convert to RPN. </p><pre class="synopsis"> int cql_transform_buf(cql_transform_t ct, struct cql_node *cn, char *out, int max); </pre><p> This function converts the CQL tree <code class="literal">cn</code> using handle <code class="literal">ct</code>. For the resulting PQF, you supply a buffer <code class="literal">out</code> which must be able to hold at at least <code class="literal">max</code> characters. </p><p> If conversion failed, <code class="function">cql_transform_buf</code> returns a non-zero SRU