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.73.2"><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
4 </p><pre class="synopsis">
5 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
8 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
11 void ZOOM_resultset_destroy(ZOOM_resultset r);
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,
25 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
28 size_t ZOOM_resultset_size (ZOOM_resultset r);
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>.
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="zoom.resultset.options"></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><tr><td>
64 rpnCharset</td><td>Character set for RPN terms.
65 If this is set, ZOOM C will assume that the ZOOM application is
66 running UTF-8. Terms in RPN queries are then converted to the
67 rpnCharset. If this is unset, ZOOM C will not assume any encoding
68 of RPN terms and no conversion is performed.
69 </td><td>none</td></tr></tbody></table></div></div><br class="table-break"><p>
70 For servers that support Search Info report, the following
71 options may be read using <code class="function">ZOOM_resultset_get</code>.
72 This detailed information is read after a successful search has
75 This information is a list of of items, where each item is
76 information about a term or subquery. All items in the list
78 <code class="literal">SearchResult.</code><em class="replaceable"><code>no</code></em>
79 where no presents the item number (0=first, 1=second).
80 Read <code class="literal">searchresult.size</code> to determine the
82 </p><div class="table"><a name="zoom.search.info.report.options"></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>
83 number of search result entries. This option is-nonexistant
84 if no entries are returned by the server.
85 </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>
86 searchresult.<em class="replaceable"><code>no</code></em>.interpretation.term
87 </td><td>interpretation term</td></tr><tr><td>
88 searchresult.<em class="replaceable"><code>no</code></em>.recommendation.term
89 </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="zoom.z3950.resultset.behavior"></a>3.1. Z39.50 Protocol behavior</h3></div></div></div><p>
90 The creation of a result set involves at least a SearchRequest
91 - SearchResponse protocol handshake. Following that, if a sort
92 criteria was specified as part of the query, a SortRequest -
93 SortResponse handshake takes place. Note that it is necessary to
94 perform sorting before any retrieval takes place, so no records will
95 be returned from the target as part of the SearchResponse because these
96 would be unsorted. Hence, piggyback is disabled when sort criteria
97 are set. Following Search - and a possible sort - Retrieval takes
98 place - as one or more Present Requests/Response pairs being
101 The API allows for two different modes for retrieval. A high level
102 mode which is somewhat more powerful and a low level one.
103 The low level is enabled when searching on a Connection object
104 for which the settings
105 <code class="literal">smallSetUpperBound</code>,
106 <code class="literal">mediumSetPresentNumber</code> and
107 <code class="literal">largeSetLowerBound</code> are set. The low level mode
108 thus allows you to precisely set how records are returned as part
109 of a search response as offered by the Z39.50 protocol.
110 Since the client may be retrieving records as part of the
111 search response, this mode doesn't work well if sorting is used.
113 The high-level mode allows you to fetch a range of records from
114 the result set with a given start offset. When you use this mode
115 the client will automatically use piggyback if that is possible
116 with the target and perform one or more present requests as needed.
117 Even if the target returns fewer records as part of a present response
118 because of a record size limit, etc. the client will repeat sending
119 present requests. As an example, if option <code class="literal">start</code>
120 is 0 (default) and <code class="literal">count</code> is 4, and
121 <code class="literal">piggyback</code> is 1 (default) and no sorting criteria
122 is specified, then the client will attempt to retrieve the 4
123 records as part the search response (using piggyback). On the other
124 hand, if either <code class="literal">start</code> is positive or if
125 a sorting criteria is set, or if <code class="literal">piggyback</code>
126 is 0, then the client will not perform piggyback but send Present
129 If either of the options <code class="literal">mediumSetElementSetName</code> and
130 <code class="literal">smallSetElementSetName</code> are unset, the value
131 of option <code class="literal">elementSetName</code> is used for piggyback
132 searches. This means that for the high-level mode you only have
133 to specify one elementSetName option rather than three.
134 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.sru.resultset.behavior"></a>3.2. SRU Protocol behavior</h3></div></div></div><p>
135 Current version of YAZ does not take advantage of a result set id
136 returned by the SRU server. Future versions might do, however.
137 Since, the ZOOM driver does not save result set IDs any
138 present (retrieval) is transformed to a SRU SearchRetrieveRequest
139 with same query but, possibly, different offsets.
141 Option <code class="literal">schema</code> specifies SRU schema
142 for retrieval. However, options <code class="literal">elementSetName</code> and
143 <code class="literal">preferredRecordSyntax</code> are ignored.
145 Options <code class="literal">start</code> and <code class="literal">count</code>
146 are supported by SRU.
147 The remaining options
148 <code class="literal">piggyback</code>,
149 <code class="literal">smallSetUpperBound</code>,
150 <code class="literal">largeSetLowerBound</code>,
151 <code class="literal">mediumSetPresentNumber</code>,
152 <code class="literal">mediumSetElementSetName</code>,
153 <code class="literal">smallSetElementSetName</code> are
156 SRU supports CQL queries, <span class="emphasis"><em>not</em></span> PQF.
157 If PQF is used, however, the PQF query is transferred anyway
158 using non-standard element <code class="literal">pQuery</code> in
159 SRU SearchRetrieveRequest.
161 Unfortunately, SRU does not define a database setting. Hence,
162 <code class="literal">databaseName</code> is unsupported and ignored.
163 However, the path part in host parameter for functions
164 <code class="function">ZOOM_connecton_new</code> and
165 <code class="function">ZOOM_connection_connect</code> acts as a
166 database (at least for the YAZ SRU server).
167 </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>