+ Functions <function>ZOOM_resultset_options_set</function> and
+ <function>ZOOM_resultset_get</function> sets and gets an option
+ for a result set similar to <function>ZOOM_connection_option_get</function>
+ and <function>ZOOM_connection_option_set</function>.
+ </para>
+ <para>
+ The number of hits also called result-count is returned by
+ function <function>ZOOM_resultset_size</function>.
+ </para>
+ <table id="zoom.resultset.options"
+ frame="top"><title>ZOOM Result set Options</title>
+ <tgroup cols="3">
+ <colspec colwidth="4*" colname="name"></colspec>
+ <colspec colwidth="7*" colname="description"></colspec>
+ <colspec colwidth="2*" colname="default"></colspec>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row><entry>
+ start</entry><entry>Offset of first record to be
+ retrieved from target. First record has offset 0 unlike the
+ protocol specifications where first record has position 1.
+ This option affects ZOOM_resultset_search and
+ ZOOM_resultset_search_pqf and must be set before any of
+ these functions are invoked. If a range of
+ records must be fetched manually after search,
+ function ZOOM_resultset_records should be used.
+ </entry><entry>0</entry></row>
+ <row><entry>
+ count</entry><entry>Number of records to be retrieved.
+ This option affects ZOOM_resultset_search and
+ ZOOM_resultset_search_pqf and must be set before any of
+ these functions are invoked.
+ </entry><entry>0</entry></row>
+ <row><entry>
+ presentChunk</entry><entry>The number of records to be
+ requested from the server in each chunk (present request). The
+ value 0 means to request all the records in a single chunk.
+ (The old <literal>step</literal>
+ option is also supported for the benefit of old applications.)
+ </entry><entry>0</entry></row>
+ <row><entry>
+ elementSetName</entry><entry>Element-Set name of records.
+ Most targets should honor element set name <literal>B</literal>
+ and <literal>F</literal> for brief and full respectively.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ preferredRecordSyntax</entry><entry>Preferred Syntax, such as
+ <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ schema</entry><entry>Schema for retrieval, such as
+ <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ setname</entry><entry>Name of Result Set (Result Set ID).
+ If this option isn't set, the ZOOM module will automatically
+ allocate a result set name.
+ </entry><entry>default</entry></row>
+ <row><entry>
+ rpnCharset</entry><entry>Character set for RPN terms.
+ If this is set, ZOOM C will assume that the ZOOM application is
+ running UTF-8. Terms in RPN queries are then converted to the
+ rpnCharset. If this is unset, ZOOM C will not assume any encoding
+ of RPN terms and no conversion is performed.
+ </entry><entry>none</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ For servers that support Search Info report, the following
+ options may be read using <function>ZOOM_resultset_get</function>.
+ This detailed information is read after a successful search has
+ completed.
+ </para>
+ <para>
+ This information is a list of of items, where each item is
+ information about a term or subquery. All items in the list
+ are prefixed by
+ <literal>SearchResult.</literal><replaceable>no</replaceable>
+ where no presents the item number (0=first, 1=second).
+ Read <literal>searchresult.size</literal> to determine the
+ number of items.
+ </para>
+ <table id="zoom.search.info.report.options"
+ frame="top"><title>Search Info Report Options</title>
+ <tgroup cols="2">
+ <colspec colwidth="4*" colname="name"></colspec>
+ <colspec colwidth="7*" colname="description"></colspec>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>searchresult.size</entry>
+ <entry>
+ number of search result entries. This option is-nonexistant
+ if no entries are returned by the server.
+ </entry>
+ </row>
+ <row>
+ <entry>searchresult.<replaceable>no</replaceable>.id</entry>
+ <entry>sub query ID</entry>
+ </row>
+ <row>
+ <entry>searchresult.<replaceable>no</replaceable>.count</entry>
+ <entry>result count for item (number of hits)</entry>
+ </row>
+ <row>
+ <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
+ <entry>subquery term</entry>
+ </row>
+ <row>
+ <entry>
+ searchresult.<replaceable>no</replaceable>.interpretation.term
+ </entry>
+ <entry>interpretation term</entry>
+ </row>
+ <row>
+ <entry>
+ searchresult.<replaceable>no</replaceable>.recommendation.term
+ </entry>
+ <entry>recommendation term</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <sect2 id="zoom.z3950.resultset.sort">
+ <title>Z39.50 Result-set Sort</title>
+ <synopsis>
+ void ZOOM_resultset_sort(ZOOM_resultset r,
+ const char *sort_type, const char *sort_spec);
+
+ int ZOOM_resultset_sort1(ZOOM_resultset r,
+ const char *sort_type, const char *sort_spec);
+ </synopsis>
+ <para>
+ <function>ZOOM_resultset_sort</function> and
+ <function>ZOOM_resultset_sort1</function> both sort an existing
+ result-set. The sort_type parameter is not use. Set it to "yaz".
+ The sort_spec is same notation as ZOOM_query_sortby and identical
+ to that offered by yaz-client's
+ <link linkend="sortspec">sort command</link>.
+ </para>
+ <para>
+ These functions only work for Z39.50. Use the more generic utility
+ <link linkend="zoom.query.sortby2">
+ <function>ZOOM_query_sortby2</function></link>
+ for other protocols (and even Z39.50).
+ </para>
+ </sect2>
+ <sect2 id="zoom.z3950.resultset.behavior">
+ <title>Z39.50 Protocol behavior</title>
+ <para>
+ The creation of a result set involves at least a SearchRequest
+ - SearchResponse protocol handshake. Following that, if a sort
+ criteria was specified as part of the query, a SortRequest -
+ SortResponse handshake takes place. Note that it is necessary to
+ perform sorting before any retrieval takes place, so no records will
+ be returned from the target as part of the SearchResponse because these
+ would be unsorted. Hence, piggyback is disabled when sort criteria
+ are set. Following Search - and a possible sort - Retrieval takes
+ place - as one or more Present Requests/Response pairs being
+ transferred.
+ </para>
+ <para>
+ The API allows for two different modes for retrieval. A high level
+ mode which is somewhat more powerful and a low level one.
+ The low level is enabled when searching on a Connection object
+ for which the settings
+ <literal>smallSetUpperBound</literal>,
+ <literal>mediumSetPresentNumber</literal> and
+ <literal>largeSetLowerBound</literal> are set. The low level mode
+ thus allows you to precisely set how records are returned as part
+ of a search response as offered by the Z39.50 protocol.
+ Since the client may be retrieving records as part of the
+ search response, this mode doesn't work well if sorting is used.
+ </para>
+ <para>
+ The high-level mode allows you to fetch a range of records from
+ the result set with a given start offset. When you use this mode
+ the client will automatically use piggyback if that is possible
+ with the target and perform one or more present requests as needed.
+ Even if the target returns fewer records as part of a present response
+ because of a record size limit, etc. the client will repeat sending
+ present requests. As an example, if option <literal>start</literal>
+ is 0 (default) and <literal>count</literal> is 4, and
+ <literal>piggyback</literal> is 1 (default) and no sorting criteria
+ is specified, then the client will attempt to retrieve the 4
+ records as part the search response (using piggyback). On the other
+ hand, if either <literal>start</literal> is positive or if
+ a sorting criteria is set, or if <literal>piggyback</literal>
+ is 0, then the client will not perform piggyback but send Present
+ Requests instead.
+ </para>
+ <para>
+ If either of the options <literal>mediumSetElementSetName</literal> and
+ <literal>smallSetElementSetName</literal> are unset, the value
+ of option <literal>elementSetName</literal> is used for piggyback
+ searches. This means that for the high-level mode you only have
+ to specify one elementSetName option rather than three.
+ </para>
+ </sect2>
+ <sect2 id="zoom.sru.resultset.behavior">
+ <title>SRU Protocol behavior</title>
+ <para>
+ Current version of &yaz; does not take advantage of a result set id
+ returned by the SRU server. Future versions might do, however.
+ Since, the ZOOM driver does not save result set IDs any
+ present (retrieval) is transformed to a SRU SearchRetrieveRequest
+ with same query but, possibly, different offsets.
+ </para>
+ <para>
+ Option <literal>schema</literal> specifies SRU schema
+ for retrieval. However, options <literal>elementSetName</literal> and
+ <literal>preferredRecordSyntax</literal> are ignored.
+ </para>
+ <para>
+ Options <literal>start</literal> and <literal>count</literal>
+ are supported by SRU.
+ The remaining options
+ <literal>piggyback</literal>,
+ <literal>smallSetUpperBound</literal>,
+ <literal>largeSetLowerBound</literal>,
+ <literal>mediumSetPresentNumber</literal>,
+ <literal>mediumSetElementSetName</literal>,
+ <literal>smallSetElementSetName</literal> are
+ unsupported.
+ </para>
+ <para>
+ SRU supports CQL queries, <emphasis>not</emphasis> PQF.
+ If PQF is used, however, the PQF query is transferred anyway
+ using non-standard element <literal>pQuery</literal> in
+ SRU SearchRetrieveRequest.
+ </para>
+ <para>
+ Solr queries has to be done in Solr query format.
+ </para>
+ <para>
+ Unfortunately, SRU or Solr does not define a database setting. Hence,
+ <literal>databaseName</literal> is unsupported and ignored.
+ However, the path part in host parameter for functions
+ <function>ZOOM_connecton_new</function> and
+ <function>ZOOM_connection_connect</function> acts as a
+ database (at least for the &yaz; SRU server).
+ </para>
+ </sect2>
+ </sect1>
+ <sect1 id="zoom.records"><title>Records</title>
+ <para>
+ A record object is a retrieval record on the client side -
+ created from result sets.