dependencies/yaz-2.1.28/doc/zoom.resultsets.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3. Result sets</title><meta name="generator" content="DocBook XSL Stylesheets V1.70.1"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="zoom.html" title="Chapter 3. ZOOM"><link rel="prev" href="zoom.query.html" title="2. Queries"><link rel="next" href="zoom.records.html" title="4. Records"></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">3. Result sets</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="zoom.query.html">Prev</a> </td><th width="60%" align="center">Chapter 3. ZOOM</th><td width="20%" align="right"> <a accesskey="n" href="zoom.records.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zoom.resultsets"></a>3. Result sets</h2></div></div></div><p>
   2     The result set object is a container for records returned from
   3     a target.
   4    </p><pre class="synopsis">
   5      ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
   6                                            ZOOM_query q);
   7
   8      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
   9                                                const char *q);
  10
  11      void ZOOM_resultset_destroy(ZOOM_resultset r);
  12    </pre><p>
  13     Function <code class="function">ZOOM_connection_search</code> creates
  14      a result set given a connection and query.
  15     Destroy a result set by calling
  16     <code class="function">ZOOM_resultset_destroy</code>.
  17     Simple clients may using PQF only may use function
  18     <code class="function">ZOOM_connection_search_pqf</code> in which case
  19     creating query objects is not necessary.
  20    </p><pre class="synopsis">
  21      void ZOOM_resultset_option_set (ZOOM_resultset r,
  22                                       const char *key,
  23                                       const char *val);
  24
  25      const char *ZOOM_resultset_option_get (ZOOM_resultset r,
  26                                              const char *key);
  27
  28      size_t ZOOM_resultset_size (ZOOM_resultset r);
  29    </pre><p>
  30     Functions <code class="function">ZOOM_resultset_options_set</code> and
  31     <code class="function">ZOOM_resultset_get</code> sets and gets an option
  32     for a result set similar to <code class="function">ZOOM_connection_option_get</code>
  33     and <code class="function">ZOOM_connection_option_set</code>.
  34    </p><p>
  35     The number of hits also called result-count is returned by
  36     function <code class="function">ZOOM_resultset_size</code>.
  37    </p><div class="table"><a name="id2563917"></a><p class="title"><b>Table 3.2. ZOOM Result set Options</b></p><div class="table-contents"><table summary="ZOOM Result set Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>
  38         start</td><td>Offset of first record to be
  39         retrieved from target. First record has offset 0 unlike the
  40         protocol specifications where first record has position 1.
  41        </td><td>0</td></tr><tr><td>
  42         count</td><td>Number of records to be retrieved.
  43        </td><td>0</td></tr><tr><td>
  44         presentChunk</td><td>The number of records to be
  45         requested from the server in each chunk (present requst).  The
  46         value 0 means to request all the records in a single chunk.
  47         (The old <code class="literal">step</code>
  48         option is also supported for the benefit of old applications.)
  49        </td><td>0</td></tr><tr><td>
  50         elementSetName</td><td>Element-Set name of records.
  51         Most targets should honor element set name <code class="literal">B</code>
  52         and <code class="literal">F</code> for brief and full respectively.
  53        </td><td>none</td></tr><tr><td>
  54         preferredRecordSyntax</td><td>Preferred Syntax, such as
  55         <code class="literal">USMARC</code>, <code class="literal">SUTRS</code>, etc.
  56        </td><td>none</td></tr><tr><td>
  57         schema</td><td>Schema for retrieval, such as
  58         <code class="literal">Gils-schema</code>, <code class="literal">Geo-schema</code>, etc.
  59        </td><td>none</td></tr><tr><td>
  60         setname</td><td>Name of Result Set (Result Set ID).
  61         If this option isn't set, the ZOOM module will automatically
  62         allocate a result set name.
  63        </td><td>default</td></tr></tbody></table></div></div><br class="table-break"><p>
  64     For servers that support Search Info report, the following
  65     options may be read using <code class="function">ZOOM_resultset_get</code>.
  66     This detailed information is read after a successful search has
  67     completed.
  68    </p><p>
  69     This information is a list of of items, where each item is
  70     information about a term or subquery. All items in the list
  71     are prefixed by
  72     <code class="literal">SearchResult.</code><em class="replaceable"><code>no</code></em>
  73     where no presents the item number (0=first, 1=second).
  74     Read <code class="literal">searchresult.size</code> to determine the
  75     number of items.
  76    </p><div class="table"><a name="id2564123"></a><p class="title"><b>Table 3.3. Search Info Report options</b></p><div class="table-contents"><table summary="Search Info Report options" border="1"><colgroup><col><col></colgroup><thead><tr><th>Option</th><th>Description</th></tr></thead><tbody><tr><td>searchresult.size</td><td>
  77         number of search result entries. This option is-nonexistant
  78         if no entries are returned by the server.
  79        </td></tr><tr><td>searchresult.<em class="replaceable"><code>no</code></em>.id</td><td>sub query ID</td></tr><tr><td>searchresult.<em class="replaceable"><code>no</code></em>.count</td><td>result count for item (number of hits)</td></tr><tr><td>searchresult.<em class="replaceable"><code>no</code></em>.subquery.term</td><td>subquery term</td></tr><tr><td>
  80         searchresult.<em class="replaceable"><code>no</code></em>.interpretation.term
  81        </td><td>interpretation term</td></tr><tr><td>
  82         searchresult.<em class="replaceable"><code>no</code></em>.recommendation.term
  83        </td><td>recommendation term</td></tr></tbody></table></div></div><br class="table-break"><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564248"></a>3.1. Z39.50 Protocol behavior</h3></div></div></div><p>
  84      The creation of a result set involves at least a SearchRequest
  85      - SearchResponse protocol handshake. Following that, if a sort
  86      criteria was specified as part of the query, a SortRequest -
  87      SortResponse handshake takes place. Note that it is necessary to
  88      perform sorting before any retrieval takes place, so no records will
  89      be returned from the target as part of the SearchResponse because these
  90      would be unsorted. Hence, piggyback is disabled when sort criteria
  91      are set. Following Search - and a possible sort - Retrieval takes
  92      place - as one or more Present Requests/Response pairs being
  93      transferred.
  94      </p><p>
  95      The API allows for two different modes for retrieval. A high level
  96      mode which is somewhat more powerful and a low level one.
  97      The low level is enabled when searching on a Connection object
  98      for which the settings
  99      <code class="literal">smallSetUpperBound</code>,
 100      <code class="literal">mediumSetPresentNumber</code> and
 101      <code class="literal">largeSetLowerBound</code> are set. The low level mode
 102      thus allows you to precisely set how records are returned as part
 103      of a search response as offered by the Z39.50 protocol.
 104      Since the client may be retrieving records as part of the
 105      search response, this mode doesn't work well if sorting is used.
 106      </p><p>
 107      The high-level mode allows you to fetch a range of records from
 108      the result set with a given start offset. When you use this mode
 109      the client will automatically use piggyback if that is possible
 110      with the target and perform one or more present requests as needed.
 111      Even if the target returns fewer records as part of a present response
 112      because of a record size limit, etc. the client will repeat sending
 113      present requests. As an example, if option <code class="literal">start</code>
 114      is 0 (default) and <code class="literal">count</code> is 4, and
 115      <code class="literal">piggyback</code> is 1 (default) and no sorting criteria
 116      is specified, then the client will attempt to retrieve the 4
 117      records as part the search response (using piggyback). On the other
 118      hand, if either <code class="literal">start</code> is positive or if
 119      a sorting criteria is set, or if <code class="literal">piggyback</code>
 120      is 0, then the client will not perform piggyback but send Present
 121      Requests instead.
 122     </p><p>
 123      If either of the options <code class="literal">mediumSetElementSetName</code> and
 124      <code class="literal">smallSetElementSetName</code> are unset, the value
 125      of option <code class="literal">elementSetName</code> is used for piggyback
 126      searches. This means that for the high-level mode you only have
 127      to specify one elementSetName option rather than three.
 128      </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2564373"></a>3.2. SRU Protocol behavior</h3></div></div></div><p>
 129      Current version of YAZ does not take advantage of a result set id
 130      returned by the SRU server. Future versions might do, however.
 131      Since, the ZOOM driver does not save result set IDs any
 132      present (retrieval) is transformed to a SRU SearchRetrieveRequest
 133      with same query but, possibly, different offsets.
 134     </p><p>
 135      Option <code class="literal">schema</code> specifies SRU schema
 136      for retrieval. However, options <code class="literal">elementSetName</code> and
 137      <code class="literal">preferredRecordSyntax</code> are ignored.
 138     </p><p>
 139      Options <code class="literal">start</code> and <code class="literal">count</code>
 140      are supported by SRU.
 141      The remaining options
 142      <code class="literal">piggyback</code>,
 143      <code class="literal">smallSetUpperBound</code>,
 144      <code class="literal">largeSetLowerBound</code>,
 145      <code class="literal">mediumSetPresentNumber</code>,
 146      <code class="literal">mediumSetElementSetName</code>,
 147       <code class="literal">smallSetElementSetName</code> are
 148      unsupported.
 149     </p><p>
 150      SRU supports CQL queries, <span class="emphasis"><em>not</em></span> PQF.
 151      If PQF is used, however, the PQF query is transferred anyway
 152      using non-standard element <code class="literal">pQuery</code> in
 153      SRU SearchRetrieveRequest.
 154     </p><p>
 155      Unfortunately, SRU does not define a database setting. Hence,
 156      <code class="literal">databaseName</code> is unsupported and ignored.
 157      However, the path part in host parameter for functions
 158      <code class="function">ZOOM_connecton_new</code> and
 159      <code class="function">ZOOM_connection_connect</code> acts as a
 160      database (at least for the YAZ SRU server).
 161     </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="zoom.query.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="zoom.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="zoom.records.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. Queries </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4. Records</td></tr></table></div></body></html>