doc/zoom.xml

   1 <!--
   2 ### Still to document:
   3 ZOOM_connection_errcode(c)
   4 ZOOM_connection_errmsg(c)
   5 ZOOM_connection_addinfo(c)
   6 ZOOM_connection_addinfo(c)
   7 ZOOM_connection_diagset(c);
   8 ZOOM_connection_save_apdu_wrbuf
   9 ZOOM_diag_str(error)
  10 ZOOM_resultset_record_immediate(s, pos)
  11 ZOOM_resultset_cache_reset(r)
  12 ZOOM_options_set_callback(opt, function, handle)
  13 ZOOM_options_create_with_parent2(parent1, parent2)
  14 ZOOM_options_getl(opt, name, len)
  15 ZOOM_options_setl(opt, name, value, len)
  16 ZOOM_options_get_bool(opt, name, defa)
  17 ZOOM_options_get_int(opt, name, defa)
  18 ZOOM_options_set_int(opt, name, value)
  19 -->
  20  <chapter id="zoom"><title>ZOOM</title>
  21   <para>
  22     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
  23    an initiative started by Mike Taylor (Mike is from the UK, which
  24    explains the peculiar name of the model). The goal of &zoom; is to
  25    provide a common Z39.50 client API not bound to a particular
  26    programming language or toolkit.
  27   </para>
  28
  29   <para>
  30     From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
  31     You can make SRU ZOOM connections by specifying scheme
  32     <literal>http://</literal> for the hostname for a connection.
  33     The dialect of SRU used is specified by the value of the
  34     connection's <literal>sru</literal> option, which may be SRU over
  35     HTTP GET (<literal>get</literal>),
  36     SRU over HTTP POST (<literal>post</literal>), (SRU over
  37     SOAP) (<literal>soap</literal>) or <literal>solr</literal>
  38     (<ulink url="&url.solr;">Solr</ulink> Web Service).
  39     Using the facility for embedding options in target strings, a
  40     connection can be forced to use SRU rather the SRW (the default) by
  41     prefixing the target string with <literal>sru=get,</literal>, like this:
  42     <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
  43   </para>
  44   <para>
  45    <ulink url="&url.solr;">Solr</ulink>  protocol support was added to
  46    YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are
  47    HTTP based protocols.
  48   </para>
  49   <para>
  50    The lack of a simple Z39.50 client API for &yaz; has become more
  51    and more apparent over time. So when the first &zoom; specification
  52    became available,
  53    an implementation for &yaz; was quickly developed. For the first time, it is
  54    now as easy (or easier!) to develop clients than servers with &yaz;. This
  55    chapter describes the &zoom; C binding. Before going further, please
  56    reconsider whether C is the right programming language for the job.
  57    There are other language bindings available for &yaz;, and still
  58    more
  59    are in active development. See the
  60    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
  61    more information.
  62   </para>
  63
  64   <para>
  65    In order to fully understand this chapter you should read and
  66    try the example programs <literal>zoomtst1.c</literal>,
  67    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
  68    directory.
  69   </para>
  70
  71   <para>
  72    The C language misses features found in object oriented languages
  73    such as C++, Java, etc. For example, you'll have to manually,
  74    destroy all objects you create, even though you may think of them as
  75    temporary. Most objects has a <literal>_create</literal> - and a
  76    <literal>_destroy</literal> variant.
  77    All objects are in fact pointers to internal stuff, but you don't see
  78    that because of typedefs. All destroy methods should gracefully ignore a
  79    <literal>NULL</literal> pointer.
  80   </para>
  81   <para>
  82    In each of the sections below you'll find a sub section called
  83    protocol behavior, that describes how the API maps to the Z39.50
  84    protocol.
  85   </para>
  86   <sect1 id="zoom-connections"><title>Connections</title>
  87
  88    <para>The Connection object is a session with a target.
  89    </para>
  90    <synopsis>
  91     #include &lt;yaz/zoom.h>
  92
  93     ZOOM_connection ZOOM_connection_new(const char *host, int portnum);
  94
  95     ZOOM_connection ZOOM_connection_create(ZOOM_options options);
  96
  97     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
  98                                  int portnum);
  99     void ZOOM_connection_destroy(ZOOM_connection c);
 100    </synopsis>
 101    <para>
 102     Connection objects are created with either function
 103     <function>ZOOM_connection_new</function> or
 104     <function>ZOOM_connection_create</function>.
 105     The former creates and automatically attempts to establish a network
 106     connection with the target. The latter doesn't establish
 107     a connection immediately, thus allowing you to specify options
 108     before establishing network connection using the function
 109     <function>ZOOM_connection_connect</function>.
 110     If the port number, <literal>portnum</literal>, is zero, the
 111     <literal>host</literal> is consulted for a port specification.
 112     If no port is given, 210 is used. A colon denotes the beginning of
 113     a port number in the host string. If the host string includes a
 114     slash, the following part specifies a database for the connection.
 115    </para>
 116    <para>
 117     You can prefix the host with a scheme followed by colon. The
 118     default scheme is <literal>tcp</literal> (Z39.50 protocol).
 119     The scheme <literal>http</literal> selects SRU/get over HTTP by default,
 120     but can overridded to use SRU/post, SRW and the Solr protocol.
 121    </para>
 122    <para>
 123     You can prefix the scheme-qualified host-string with one or more
 124     comma-separated
 125     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
 126     sequences, each of which represents an option to be set into the
 127     connection structure <emphasis>before</emphasis> the
 128     protocol-level connection is forged and the initialization
 129     handshake takes place.  This facility can be used to provide
 130     authentication credentials, as in host-strings such as:
 131     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
 132    </para>
 133    <para>
 134     Connection objects should be destroyed using the function
 135     <function>ZOOM_connection_destroy</function>.
 136    </para>
 137    <synopsis>
 138     void ZOOM_connection_option_set(ZOOM_connection c,
 139                                     const char *key, const char *val);
 140
 141     void ZOOM_connection_option_setl(ZOOM_connection c,
 142                                      const char *key,
 143                                      const char *val, int len);
 144
 145     const char *ZOOM_connection_option_get(ZOOM_connection c,
 146                                            const char *key);
 147     const char *ZOOM_connection_option_getl(ZOOM_connection c,
 148                                             const char *key,
 149                                             int *lenp);
 150    </synopsis>
 151    <para>
 152     The functions <function>ZOOM_connection_option_set</function> and
 153     <function>ZOOM_connection_option_setl</function> allows you to
 154     set an option given by <parameter>key</parameter> to the value
 155     <parameter>value</parameter> for the connection.
 156     For <function>ZOOM_connection_option_set</function>, the
 157     value is assumed to be a 0-terminated string. Function
 158     <function>ZOOM_connection_option_setl</function> specifies a
 159     value of a certain size (len).
 160    </para>
 161    <para>
 162     Functions <function>ZOOM_connection_option_get</function> and
 163     <function>ZOOM_connection_option_getl</function> returns
 164     the value for an option given by <parameter>key</parameter>.
 165    </para>
 166    <table id="zoom-connection-options" frame="top">
 167     <title>ZOOM Connection Options</title>
 168     <tgroup cols="3">
 169      <colspec colwidth="4*" colname="name"></colspec>
 170      <colspec colwidth="7*" colname="description"></colspec>
 171      <colspec colwidth="3*" colname="default"></colspec>
 172      <thead>
 173       <row>
 174        <entry>Option</entry>
 175        <entry>Description</entry>
 176        <entry>Default</entry>
 177       </row>
 178      </thead>
 179      <tbody>
 180       <row><entry>
 181         implementationName</entry><entry>Name of Your client
 182        </entry><entry>none</entry></row>
 183       <row><entry>
 184         user</entry><entry>Authentication user name
 185        </entry><entry>none</entry></row>
 186       <row><entry>
 187         group</entry><entry>Authentication group name
 188        </entry><entry>none</entry></row>
 189       <row><entry>
 190         password</entry><entry>Authentication password.
 191        </entry><entry>none</entry></row>
 192       <row><entry>
 193         authenticationMode</entry><entry>How authentication is encoded.
 194        </entry><entry>basic</entry></row>
 195       <row><entry>
 196         host</entry><entry>Target host. This setting is "read-only".
 197         It's automatically set internally when connecting to a target.
 198        </entry><entry>none</entry></row>
 199       <row><entry>
 200         proxy</entry><entry>Proxy host. If set, the logical host
 201         is encoded in the otherInfo area of the Z39.50 Init PDU
 202         with OID 1.2.840.10003.10.1000.81.1.
 203        </entry><entry>none</entry></row>
 204       <row><entry>
 205         clientIP</entry><entry>Client IP. If set, is
 206         encoded in the otherInfo area of a Z39.50 PDU with OID
 207         1.2.840.10003.10.1000.81.3. Holds the original IP addreses
 208         of a client. Is used of ZOOM is used in a gateway of some sort.
 209        </entry><entry>none</entry></row>
 210       <row><entry>
 211         async</entry><entry>If true (1) the connection operates in
 212         asynchronous operation which means that all calls are non-blocking
 213         except
 214         <link linkend="zoom.events"><function>ZOOM_event</function></link>.
 215        </entry><entry>0</entry></row>
 216       <row><entry>
 217         maximumRecordSize</entry><entry> Maximum size of single record.
 218        </entry><entry>1 MB</entry></row>
 219       <row><entry>
 220         preferredMessageSize</entry><entry> Maximum size of multiple records.
 221        </entry><entry>1 MB</entry></row>
 222       <row><entry>
 223         lang</entry><entry> Language for negotiation.
 224        </entry><entry>none</entry></row>
 225       <row><entry>
 226         charset</entry><entry> Character set for negotiation.
 227        </entry><entry>none</entry></row>
 228       <row><entry>
 229         serverImplementationId</entry><entry>
 230         Implementation ID of server.  (The old targetImplementationId
 231         option is also supported for the benefit of old applications.)
 232        </entry><entry>none</entry></row>
 233       <row><entry>
 234         targetImplementationName</entry><entry>
 235         Implementation Name of server.  (The old
 236         targetImplementationName option is also supported for the
 237         benefit of old applications.)
 238        </entry><entry>none</entry></row>
 239       <row><entry>
 240         serverImplementationVersion</entry><entry>
 241         Implementation Version of server.  (the old
 242         targetImplementationVersion option is also supported for the
 243         benefit of old applications.)
 244        </entry><entry>none</entry></row>
 245       <row><entry>
 246         databaseName</entry><entry>One or more database names
 247         separated by character plus (<literal>+</literal>), which to
 248         be used by subsequent search requests on this Connection.
 249        </entry><entry>Default</entry></row>
 250       <row><entry>
 251         piggyback</entry><entry>True (1) if piggyback should be
 252         used in searches; false (0) if not.
 253        </entry><entry>1</entry></row>
 254       <row><entry>
 255         smallSetUpperBound</entry><entry>If hits is less than or equal to this
 256         value, then target will return all records using small element set name
 257        </entry><entry>0</entry></row>
 258       <row><entry>
 259         largeSetLowerBound</entry><entry>If hits is greater than this
 260         value, the target will return no records.
 261        </entry><entry>1</entry></row>
 262       <row><entry>
 263         mediumSetPresentNumber</entry><entry>This value represents
 264         the number of records to be returned as part of a search when when
 265         hits is less than or equal to large set lower bound and if hits
 266         is greater than small set upper bound.
 267        </entry><entry>0</entry></row>
 268       <row><entry>
 269         smallSetElementSetName</entry><entry>
 270         The element set name to be used for small result sets.
 271        </entry><entry>none</entry></row>
 272       <row><entry>
 273         mediumSetElementSetName</entry><entry>
 274         The element set name to be for medium-sized result sets.
 275        </entry><entry>none</entry></row>
 276       <row><entry>
 277         init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
 278         After a successful Init, these options may be interrogated to
 279         discover whether the server claims to support the specified
 280         operations.
 281        </entry><entry>none</entry></row>
 282       <row>
 283         <entry>sru</entry><entry>
 284         SRU/Solr transport type. Must be either <literal>soap</literal>,
 285         <literal>get</literal>, <literal>post</literal>, or
 286         <literal>solr</literal>.
 287         </entry><entry>soap</entry></row>
 288       <row><entry>
 289         sru_version</entry><entry>
 290         SRU/SRW version. Should be <literal>1.1</literal>, or
 291         <literal>1.2</literal>. This is , prior to connect, the version
 292         to offer (highest version). And following connect (in fact
 293         first operation), holds the negotiated version with the server
 294         (same or lower version).
 295        </entry><entry>1.2</entry></row>
 296       <row><entry>
 297         facets</entry><entry>
 298         A FacetList is comma-separated list of facet, which is defined
 299         as <literal>AttributeList</literal>  and a optional FacetTerm
 300         (a Term and a frequency). On request the terms is missing.
 301         On response the the list contains the terms that the target
 302         could collect.
 303        </entry><entry>none</entry></row>
 304       <row><entry>
 305         apdulog</entry><entry>
 306         If set to a true value such as "1", a log of low-level
 307         protocol packets is emitted on standard error stream.  This
 308         can be very useful for debugging.
 309        </entry><entry>0</entry></row>
 310       <row><entry>
 311         saveAPDU</entry><entry>
 312         If set to a true value such as "1", a log of low-level
 313         protocol packets is saved. The log can be retrieved by reading
 314         option APDU. Setting saveAPDU always has the side effect of
 315         resetting the currently saved log. This setting is
 316         <emphasis>write-only</emphasis>. If read, NULL will be returned.
 317         It is only recognized in
 318         <function>ZOOM_connection_option_set</function>.
 319        </entry><entry>0</entry></row>
 320       <row><entry>
 321         APDU</entry><entry>
 322         Returns the log of protocol packets. Will be empty if logging
 323         is not enabled (see saveAPDU above). This setting is
 324         <emphasis>read-only</emphasis>. It is only recognized if used
 325         in call to <function>ZOOM_connection_option_get</function> or
 326         <function>ZOOM_connection_option_getl</function>.
 327        </entry><entry></entry></row>
 328       <row><entry>
 329         memcached</entry><entry>
 330         If given and non-empty,
 331         <ulink url="&url.libmemcached;">libMemcached</ulink>
 332         will be configured for the connection.
 333         This option is inspected by ZOOM when a connection is  established.
 334         If the <literal>memcached</literal> option is given
 335         and YAZ is compiled without libMemcached support, an internal
 336         diagnostic (10018) will be thrown.
 337         libMemcached support is available for YAZ 5.0.13 or later. If this
 338         option is supplied for an earlier version of YAZ, it is
 339         <emphasis>ignored</emphasis>.
 340         The value of this option is a string passed verbatim to
 341         the <function>memcached</function> function part of libMemcached.
 342         Refer to man page
 343          <ulink url="http://manned.org/memcached.3">memcached(3)</ulink>.
 344         Earlier versions of libMemcached
 345         do not offer this function. In this case only the option
 346         <literal>--server=</literal><replaceable>host</replaceable> may
 347         be given (YAZ emulates that part of libMemcached).
 348        </entry><entry>none</entry></row>
 349      </tbody>
 350     </tgroup>
 351    </table>
 352    <para>
 353     If either option <literal>lang</literal> or <literal>charset</literal>
 354     is set, then
 355     <ulink url="&url.z39.50.charneg;">
 356      Character Set and Language Negotiation</ulink> is in effect.
 357    </para>
 358    <synopsis>
 359      int ZOOM_connection_error(ZOOM_connection c, const char **cp,
 360                                const char **addinfo);
 361      int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
 362                                  const char **addinfo, const char **dset);
 363    </synopsis>
 364    <para>
 365     Function <function>ZOOM_connection_error</function> checks for
 366     errors for the last operation(s) performed. The function returns
 367     zero if no errors occurred; non-zero otherwise indicating the error.
 368     Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
 369     holds messages for the error and additional-info if passed as
 370     non-<literal>NULL</literal>. Function
 371     <function>ZOOM_connection_error_x</function> is an extended version
 372     of <function>ZOOM_connection_error</function> that is capable of
 373     returning name of diagnostic set in <parameter>dset</parameter>.
 374    </para>
 375    <sect2 id="zoom-connection-z39.50">
 376     <title>Z39.50 Protocol behavior</title>
 377     <para>
 378      The calls <function>ZOOM_connection_new</function> and
 379      <function>ZOOM_connection_connect</function> establishes a TCP/IP
 380       connection and sends an Initialize Request to the target if
 381       possible. In addition, the calls waits for an Initialize Response
 382       from the target and the result is inspected (OK or rejected).
 383     </para>
 384     <para>
 385      If <literal>proxy</literal> is set then the client will establish
 386      a TCP/IP connection with the peer as specified by the
 387      <literal>proxy</literal> host and the hostname as part of the
 388      connect calls will be set as part of the Initialize Request.
 389      The proxy server will then "forward" the PDU's transparently
 390      to the target behind the proxy.
 391     </para>
 392     <para>
 393      For the authentication parameters, if option <literal>user</literal>
 394      is set and both options <literal>group</literal> and
 395      <literal>pass</literal> are unset, then Open style
 396      authentication is used (Version 2/3) in which case the username
 397      is usually followed by a slash, then by a password.
 398      If either <literal>group</literal>
 399      or <literal>pass</literal> is set then idPass authentication
 400      (Version 3 only) is used. If none of the options are set, no
 401      authentication parameters are set as part of the Initialize Request
 402      (obviously).
 403     </para>
 404     <para>
 405      When option <literal>async</literal> is 1, it really means that
 406      all network operations are postponed (and queued) until the
 407      function <literal>ZOOM_event</literal> is invoked. When doing so
 408      it doesn't make sense to check for errors after
 409      <literal>ZOOM_connection_new</literal> is called since that
 410      operation "connecting - and init" is still incomplete and the
 411      API cannot tell the outcome (yet).
 412     </para>
 413     </sect2>
 414    <sect2 id="zoom.sru.init.behavior">
 415     <title>SRU/Solr Protocol behavior</title>
 416     <para>
 417      The HTTP based protocols (SRU, SRW, Solr) doesn't feature an
 418      Inititialize Request, so  the connection phase merely establishes a
 419      TCP/IP connection with the HTTP server.
 420     </para>
 421     <para>Most of the ZOOM connection options do not
 422      affect SRU/Solr and they are ignored. However, future versions
 423      of &yaz; might honor <literal>implementationName</literal> and
 424      put that as part of User-Agent header for HTTP requests.
 425      </para>
 426     <para>
 427      The <literal>charset</literal> is used in the Content-Type header
 428      of HTTP requests.
 429     </para>
 430     <para>
 431      Setting <literal>authentcationMode</literal> specifies how
 432      authentication parameters are encoded for HTTP. The default is
 433      "<literal>basic</literal>" where <literal>user</literal> and
 434      <literal>password</literal> are encoded by using HTTP basic
 435      authentication.
 436      </para>
 437     <para>
 438      If <literal>authentcationMode</literal> is "<literal>url</literal>", then
 439      user and password are encoded in the URL by parameters
 440      <literal>x-username</literal> and <literal>x-password</literal> as
 441      given by the SRU standard.
 442     </para>
 443    </sect2>
 444   </sect1>
 445   <sect1 id="zoom.query"><title>Queries</title>
 446    <para>
 447     Query objects represents queries.
 448    </para>
 449    <synopsis>
 450      ZOOM_query ZOOM_query_create(void);
 451
 452      void ZOOM_query_destroy(ZOOM_query q);
 453
 454      int ZOOM_query_prefix(ZOOM_query q, const char *str);
 455
 456      int ZOOM_query_cql(ZOOM_query s, const char *str);
 457
 458      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
 459
 460      int ZOOM_query_sortby2(ZOOM_query q, const char *strategy,
 461                             const char *criteria);
 462    </synopsis>
 463    <para>
 464     Create query objects using <function>ZOOM_query_create</function>
 465     and destroy them by calling <function>ZOOM_query_destroy</function>.
 466     RPN-queries can be specified in <link linkend="PQF">PQF</link>
 467     notation by using the
 468     function <function>ZOOM_query_prefix</function>.
 469     The <function>ZOOM_query_cql</function> specifies a CQL
 470     query to be sent to the server/target.
 471     More query types will be added in future versions of &yaz;, such as
 472     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
 473     etc. In addition to a search, a sort criteria may be set. Function
 474     <function>ZOOM_query_sortby</function> enables Z39.50 sorting and
 475     it takes sort criteria using the same string notation as
 476     yaz-client's <link linkend="sortspec">sort command</link>.
 477    </para>
 478    <para id="zoom.query.sortby2">
 479     <function>ZOOM_query_sortby2</function> is similar to
 480     <function>ZOOM_query_sortby</function> but allows a strategy for
 481     sorting. The reason for the strategy parameter is that some
 482     protocols offers multiple ways of performing sorting.
 483     For example, Z39.50 has the standard sort, which is performed after
 484     search on an existing result set.
 485     It's also possible to use CQL in Z39.50 as the query type and use
 486     CQL's SORTBY keyword. Finally, Index Data's
 487     Zebra server also allows sorting to be specified as part of RPN (Type 7).
 488    </para>
 489    <table id="zoom-sort-strategy" frame="top">
 490     <title>ZOOM sort strategy</title>
 491     <tgroup cols="2">
 492      <colspec colwidth="2*" colname="name"/>
 493      <colspec colwidth="5*" colname="description"/>
 494      <thead>
 495       <row>
 496        <entry>Name</entry>
 497        <entry>Description</entry>
 498       </row>
 499      </thead>
 500      <tbody>
 501       <row>
 502        <entry>z39.50</entry><entry>Z39.50 resultset sort</entry>
 503       </row>
 504       <row>
 505        <entry>type7</entry><entry>Sorting embedded in RPN(Type-7)</entry>
 506       </row>
 507       <row>
 508        <entry>cql</entry><entry>CQL SORTBY</entry>
 509       </row>
 510       <row>
 511        <entry>sru11</entry><entry>SRU sortKeys parameter</entry>
 512       </row>
 513       <row>
 514        <entry>solr</entry><entry>Solr sort</entry>
 515       </row>
 516       <row>
 517        <entry>embed</entry><entry>type7 for Z39.50, cql for SRU,
 518         solr for Solr protocol</entry>
 519       </row>
 520      </tbody>
 521     </tgroup>
 522    </table>
 523   </sect1>
 524   <sect1 id="zoom.resultsets"><title>Result sets</title>
 525    <para>
 526     The result set object is a container for records returned from
 527     a target.
 528    </para>
 529    <synopsis>
 530      ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
 531
 532      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
 533                                                const char *q);
 534      void ZOOM_resultset_destroy(ZOOM_resultset r);
 535    </synopsis>
 536    <para>
 537     Function <function>ZOOM_connection_search</function> creates
 538     a result set given a connection and query.
 539     Destroy a result set by calling
 540     <function>ZOOM_resultset_destroy</function>.
 541     Simple clients may using PQF only may use function
 542     <function>ZOOM_connection_search_pqf</function> in which case
 543     creating query objects is not necessary.
 544    </para>
 545    <synopsis>
 546      void ZOOM_resultset_option_set(ZOOM_resultset r,
 547                                     const char *key, const char *val);
 548
 549      const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
 550
 551      size_t ZOOM_resultset_size(ZOOM_resultset r);
 552    </synopsis>
 553    <para>
 554     Functions <function>ZOOM_resultset_options_set</function> and
 555     <function>ZOOM_resultset_get</function> sets and gets an option
 556     for a result set similar to <function>ZOOM_connection_option_get</function>
 557     and <function>ZOOM_connection_option_set</function>.
 558    </para>
 559    <para>
 560     The number of hits also called result-count is returned by
 561     function <function>ZOOM_resultset_size</function>.
 562    </para>
 563    <table id="zoom.resultset.options"
 564     frame="top"><title>ZOOM Result set Options</title>
 565     <tgroup cols="3">
 566      <colspec colwidth="4*" colname="name"></colspec>
 567      <colspec colwidth="7*" colname="description"></colspec>
 568      <colspec colwidth="2*" colname="default"></colspec>
 569      <thead>
 570       <row>
 571        <entry>Option</entry>
 572        <entry>Description</entry>
 573        <entry>Default</entry>
 574       </row>
 575      </thead>
 576      <tbody>
 577       <row><entry>
 578         start</entry><entry>Offset of first record to be
 579         retrieved from target. First record has offset 0 unlike the
 580         protocol specifications where first record has position 1.
 581         This option affects ZOOM_resultset_search and
 582         ZOOM_resultset_search_pqf and must be set before any of
 583         these functions are invoked. If a range of
 584         records must be fetched manually after search,
 585         function ZOOM_resultset_records should be used.
 586        </entry><entry>0</entry></row>
 587       <row><entry>
 588         count</entry><entry>Number of records to be retrieved.
 589         This option affects ZOOM_resultset_search and
 590         ZOOM_resultset_search_pqf and must be set before any of
 591         these functions are invoked.
 592        </entry><entry>0</entry></row>
 593       <row><entry>
 594         presentChunk</entry><entry>The number of records to be
 595         requested from the server in each chunk (present request). The
 596         value 0 means to request all the records in a single chunk.
 597         (The old <literal>step</literal>
 598         option is also supported for the benefit of old applications.)
 599        </entry><entry>0</entry></row>
 600       <row><entry>
 601         elementSetName</entry><entry>Element-Set name of records.
 602         Most targets should honor element set name <literal>B</literal>
 603         and <literal>F</literal> for brief and full respectively.
 604        </entry><entry>none</entry></row>
 605       <row><entry>
 606         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
 607         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
 608        </entry><entry>none</entry></row>
 609       <row><entry>
 610         schema</entry><entry>Schema for retrieval, such as
 611         <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
 612        </entry><entry>none</entry></row>
 613       <row><entry>
 614         setname</entry><entry>Name of Result Set (Result Set ID).
 615         If this option isn't set, the ZOOM module will automatically
 616         allocate a result set name.
 617        </entry><entry>default</entry></row>
 618       <row><entry>
 619         rpnCharset</entry><entry>Character set for RPN terms.
 620         If this is set, ZOOM C will assume that the ZOOM application is
 621         running UTF-8. Terms in RPN queries are then converted to the
 622         rpnCharset. If this is unset, ZOOM C will not assume any encoding
 623         of RPN terms and no conversion is performed.
 624        </entry><entry>none</entry></row>
 625      </tbody>
 626     </tgroup>
 627    </table>
 628    <para>
 629     For servers that support Search Info report, the following
 630     options may be read using <function>ZOOM_resultset_get</function>.
 631     This detailed information is read after a successful search has
 632     completed.
 633    </para>
 634    <para>
 635     This information is a list of of items, where each item is
 636     information about a term or subquery. All items in the list
 637     are prefixed by
 638     <literal>SearchResult.</literal><replaceable>no</replaceable>
 639     where no presents the item number (0=first, 1=second).
 640     Read <literal>searchresult.size</literal> to determine the
 641     number of items.
 642    </para>
 643    <table id="zoom.search.info.report.options"
 644     frame="top"><title>Search Info Report Options</title>
 645     <tgroup cols="2">
 646      <colspec colwidth="4*" colname="name"></colspec>
 647      <colspec colwidth="7*" colname="description"></colspec>
 648      <thead>
 649       <row>
 650        <entry>Option</entry>
 651        <entry>Description</entry>
 652       </row>
 653      </thead>
 654      <tbody>
 655       <row>
 656        <entry>searchresult.size</entry>
 657        <entry>
 658         number of search result entries. This option is-nonexistant
 659         if no entries are returned by the server.
 660        </entry>
 661       </row>
 662       <row>
 663        <entry>searchresult.<replaceable>no</replaceable>.id</entry>
 664        <entry>sub query ID</entry>
 665       </row>
 666       <row>
 667        <entry>searchresult.<replaceable>no</replaceable>.count</entry>
 668        <entry>result count for item (number of hits)</entry>
 669       </row>
 670       <row>
 671        <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
 672        <entry>subquery term</entry>
 673       </row>
 674       <row>
 675        <entry>
 676         searchresult.<replaceable>no</replaceable>.interpretation.term
 677        </entry>
 678        <entry>interpretation term</entry>
 679       </row>
 680       <row>
 681        <entry>
 682         searchresult.<replaceable>no</replaceable>.recommendation.term
 683        </entry>
 684        <entry>recommendation term</entry>
 685       </row>
 686      </tbody>
 687     </tgroup>
 688    </table>
 689
 690    <sect2 id="zoom.z3950.resultset.sort">
 691     <title>Z39.50 Result-set Sort</title>
 692     <synopsis>
 693      void ZOOM_resultset_sort(ZOOM_resultset r,
 694                               const char *sort_type, const char *sort_spec);
 695
 696      int ZOOM_resultset_sort1(ZOOM_resultset r,
 697                               const char *sort_type, const char *sort_spec);
 698     </synopsis>
 699     <para>
 700      <function>ZOOM_resultset_sort</function> and
 701      <function>ZOOM_resultset_sort1</function> both sort an existing
 702      result-set. The sort_type parameter is not use. Set it to "yaz".
 703      The sort_spec is same notation as ZOOM_query_sortby and identical
 704      to that offered by yaz-client's
 705      <link linkend="sortspec">sort command</link>.
 706     </para>
 707     <para>
 708      These functions only work for Z39.50. Use the more generic utility
 709      <link linkend="zoom.query.sortby2">
 710       <function>ZOOM_query_sortby2</function></link>
 711      for other protocols (and even Z39.50).
 712     </para>
 713    </sect2>
 714    <sect2 id="zoom.z3950.resultset.behavior">
 715     <title>Z39.50 Protocol behavior</title>
 716     <para>
 717      The creation of a result set involves at least a SearchRequest
 718      - SearchResponse protocol handshake. Following that, if a sort
 719      criteria was specified as part of the query, a SortRequest -
 720      SortResponse handshake takes place. Note that it is necessary to
 721      perform sorting before any retrieval takes place, so no records will
 722      be returned from the target as part of the SearchResponse because these
 723      would be unsorted. Hence, piggyback is disabled when sort criteria
 724      are set. Following Search - and a possible sort - Retrieval takes
 725      place - as one or more Present Requests/Response pairs being
 726      transferred.
 727      </para>
 728     <para>
 729      The API allows for two different modes for retrieval. A high level
 730      mode which is somewhat more powerful and a low level one.
 731      The low level is enabled when searching on a Connection object
 732      for which the settings
 733      <literal>smallSetUpperBound</literal>,
 734      <literal>mediumSetPresentNumber</literal> and
 735      <literal>largeSetLowerBound</literal> are set. The low level mode
 736      thus allows you to precisely set how records are returned as part
 737      of a search response as offered by the Z39.50 protocol.
 738      Since the client may be retrieving records as part of the
 739      search response, this mode doesn't work well if sorting is used.
 740      </para>
 741     <para>
 742      The high-level mode allows you to fetch a range of records from
 743      the result set with a given start offset. When you use this mode
 744      the client will automatically use piggyback if that is possible
 745      with the target and perform one or more present requests as needed.
 746      Even if the target returns fewer records as part of a present response
 747      because of a record size limit, etc. the client will repeat sending
 748      present requests. As an example, if option <literal>start</literal>
 749      is 0 (default) and <literal>count</literal> is 4, and
 750      <literal>piggyback</literal> is 1 (default) and no sorting criteria
 751      is specified, then the client will attempt to retrieve the 4
 752      records as part the search response (using piggyback). On the other
 753      hand, if either <literal>start</literal> is positive or if
 754      a sorting criteria is set, or if <literal>piggyback</literal>
 755      is 0, then the client will not perform piggyback but send Present
 756      Requests instead.
 757     </para>
 758     <para>
 759      If either of the options <literal>mediumSetElementSetName</literal> and
 760      <literal>smallSetElementSetName</literal> are unset, the value
 761      of option <literal>elementSetName</literal> is used for piggyback
 762      searches. This means that for the high-level mode you only have
 763      to specify one elementSetName option rather than three.
 764      </para>
 765    </sect2>
 766    <sect2 id="zoom.sru.resultset.behavior">
 767     <title>SRU Protocol behavior</title>
 768     <para>
 769      Current version of &yaz; does not take advantage of a result set id
 770      returned by the SRU server. Future versions might do, however.
 771      Since, the ZOOM driver does not save result set IDs any
 772      present (retrieval) is transformed to a SRU SearchRetrieveRequest
 773      with same query but, possibly, different offsets.
 774     </para>
 775     <para>
 776      Option <literal>schema</literal> specifies SRU schema
 777      for retrieval. However, options <literal>elementSetName</literal> and
 778      <literal>preferredRecordSyntax</literal> are ignored.
 779     </para>
 780     <para>
 781      Options <literal>start</literal> and <literal>count</literal>
 782      are supported by SRU.
 783      The remaining options
 784      <literal>piggyback</literal>,
 785      <literal>smallSetUpperBound</literal>,
 786      <literal>largeSetLowerBound</literal>,
 787      <literal>mediumSetPresentNumber</literal>,
 788      <literal>mediumSetElementSetName</literal>,
 789       <literal>smallSetElementSetName</literal> are
 790      unsupported.
 791     </para>
 792     <para>
 793      SRU supports CQL queries, <emphasis>not</emphasis> PQF.
 794      If PQF is used, however, the PQF query is transferred anyway
 795      using non-standard element <literal>pQuery</literal> in
 796      SRU SearchRetrieveRequest.
 797     </para>
 798     <para>
 799      Solr queries has to be done in Solr query format.
 800     </para>
 801     <para>
 802      Unfortunately, SRU or Solr does not define a database setting. Hence,
 803      <literal>databaseName</literal> is unsupported and ignored.
 804      However, the path part in host parameter for functions
 805      <function>ZOOM_connecton_new</function> and
 806      <function>ZOOM_connection_connect</function> acts as a
 807      database (at least for the &yaz; SRU server).
 808     </para>
 809    </sect2>
 810   </sect1>
 811   <sect1 id="zoom.records"><title>Records</title>
 812    <para>
 813     A record object is a retrieval record on the client side -
 814     created from result sets.
 815    </para>
 816    <synopsis>
 817      void ZOOM_resultset_records(ZOOM_resultset r,
 818                                  ZOOM_record *recs,
 819                                  size_t start, size_t count);
 820      ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
 821
 822      const char *ZOOM_record_get(ZOOM_record rec, const char *type,
 823                                  size_t *len);
 824
 825      int ZOOM_record_error(ZOOM_record rec, const char **msg,
 826                            const char **addinfo, const char **diagset);
 827
 828      ZOOM_record ZOOM_record_clone(ZOOM_record rec);
 829
 830      void ZOOM_record_destroy(ZOOM_record rec);
 831    </synopsis>
 832    <para>
 833     References to temporary records are returned by functions
 834     <function>ZOOM_resultset_records</function> or
 835     <function>ZOOM_resultset_record</function>.
 836     </para>
 837    <para>
 838     If a persistent reference to a record is desired
 839     <function>ZOOM_record_clone</function> should be used.
 840     It returns a record reference that should be destroyed
 841     by a call to <function>ZOOM_record_destroy</function>.
 842    </para>
 843    <para>
 844     A single record is returned by function
 845     <function>ZOOM_resultset_record</function> that takes a
 846     position as argument. First record has position zero.
 847     If no record could be obtained <literal>NULL</literal> is returned.
 848    </para>
 849    <para>
 850     Error information for a record can be checked with
 851     <function>ZOOM_record_error</function> which returns non-zero
 852     (error code) if record is in error, called <emphasis>Surrogate
 853      Diagnostics</emphasis> in Z39.50.
 854    </para>
 855    <para>
 856     Function <function>ZOOM_resultset_records</function> retrieves
 857     a number of records from a result set. Parameter <literal>start</literal>
 858     and <literal>count</literal> specifies the range of records to
 859     be returned. Upon completion array
 860     <literal>recs[0], ..recs[count-1]</literal>
 861     holds record objects for the records. The array of records
 862      <literal>recs</literal> should be allocated prior the call
 863     <function>ZOOM_resultset_records</function>. Note that for those
 864     records that couldn't be retrieved from the target
 865     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
 866    </para>
 867    <para id="zoom.record.get">
 868     In order to extract information about a single record,
 869     <function>ZOOM_record_get</function> is provided. The
 870     function returns a pointer to certain record information. The
 871     nature (type) of the pointer depends on the parameter,
 872     <parameter>type</parameter>.
 873    </para>
 874    <para>
 875     The <parameter>type</parameter> is a string of the format:
 876    </para>
 877    <para>
 878     <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]
 879    </para>
 880    <para>
 881     where <replaceable>format</replaceable> specifies the format of the
 882     returned record, <replaceable>from</replaceable>
 883     specifies the character set of the record in its original form
 884     (as returned by the server), <replaceable>to</replaceable> specifies
 885     the output (returned)
 886     character set encoding.
 887     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
 888     If charset is not given, then no character set conversion takes place.
 889    </para>
 890
 891    <para>OPAC records may be returned in a different
 892      set from the bibliographic MARC record. If this is this the case,
 893     <replaceable>opacfrom</replaceable> should be set to the character set
 894     of the OPAC record part.
 895    </para>
 896    <note>
 897      <para>
 898        Specifying the OPAC record character set requires YAZ 4.1.5 or later.
 899      </para>
 900    </note>
 901    <para>
 902     The format argument controls whether record data should be XML
 903     pretty-printed (post process operation).
 904     It is enabled only if format value <replaceable>v</replaceable> is
 905     <literal>1</literal> and the record content is XML well-formed.
 906    </para>
 907    <para>
 908     In addition, for certain types, the length
 909     <literal>len</literal> passed will be set to the size in bytes of
 910     the returned information.
 911     </para>
 912    <para>
 913     The following are the supported values for <replaceable>form</replaceable>.
 914     <variablelist>
 915      <varlistentry><term><literal>database</literal></term>
 916       <listitem><para>Database of record is returned
 917         as a C null-terminated string. Return type
 918         <literal>const char *</literal>.
 919        </para></listitem>
 920      </varlistentry>
 921      <varlistentry><term><literal>syntax</literal></term>
 922       <listitem><para>The transfer syntax of the record is returned
 923         as a C null-terminated string containing the symbolic name of
 924         the record syntax, e.g. <literal>Usmarc</literal>. Return type
 925         is
 926         <literal>const char *</literal>.
 927        </para></listitem>
 928      </varlistentry>
 929      <varlistentry><term><literal>schema</literal></term>
 930       <listitem><para>The schema of the record is returned
 931         as a C null-terminated string. Return type is
 932         <literal>const char *</literal>.
 933        </para></listitem>
 934      </varlistentry>
 935      <varlistentry><term><literal>render</literal></term>
 936       <listitem><para>The record is returned in a display friendly
 937         format. Upon completion buffer is returned
 938         (type <literal>const char *</literal>) and length is stored in
 939         <literal>*len</literal>.
 940        </para></listitem>
 941      </varlistentry>
 942      <varlistentry><term><literal>raw</literal></term>
 943       <listitem><para>The record is returned in the internal
 944         YAZ specific format. For GRS-1, Explain, and others, the
 945         raw data is returned as type
 946         <literal>Z_External *</literal> which is just the type for
 947         the member <literal>retrievalRecord</literal> in
 948         type <literal>NamePlusRecord</literal>.
 949         For SUTRS and octet aligned record (including all MARCs) the
 950         octet buffer is returned and the length of the buffer.
 951        </para></listitem>
 952      </varlistentry>
 953      <varlistentry><term><literal>xml</literal></term>
 954       <listitem><para>The record is returned in XML if possible.
 955         SRU, Solr and Z39.50 records with transfer syntax XML are
 956         returned verbatim. MARC records are returned in
 957         <ulink url="&url.marcxml;">
 958          MARCXML
 959          </ulink>
 960         (converted from ISO2709 to MARCXML by YAZ).
 961         OPAC records are also converted to XML and the
 962         bibliographic record is converted to MARCXML (when possible).
 963         GRS-1 records are not supported for this form.
 964         Upon completion, the XML buffer is returned
 965         (type <literal>const char *</literal>) and length is stored in
 966         <literal>*len</literal>.
 967        </para></listitem>
 968      </varlistentry>
 969      <varlistentry><term><literal>opac</literal></term>
 970       <listitem><para>OPAC information for record is returned in XML
 971         if an OPAC record is present at the position given. If no
 972         OPAC record is present, a NULL pointer is returned.
 973        </para></listitem>
 974      </varlistentry>
 975      <varlistentry><term><literal>txml</literal></term>
 976       <listitem><para>The record is returned in TurboMARC if possible.
 977         SRU and Z39.50 records with transfer syntax XML are
 978         returned verbatim. MARC records are returned in
 979         <link linkend="tools.turbomarc">
 980          TurboMARC
 981         </link>
 982         (converted from ISO2709 to TurboMARC by YAZ).
 983         Upon completion, the XML buffer is returned
 984         (type <literal>const char *</literal>) and length is stored in
 985         <literal>*len</literal>.
 986        </para></listitem>
 987      </varlistentry>
 988      <varlistentry><term><literal>json</literal></term>
 989       <listitem><para>Like xml, but MARC records are converted to
 990         <ulink url="&url.marc_in_json;">MARC-in-JSON</ulink>.
 991        </para></listitem>
 992      </varlistentry>
 993
 994     </variablelist>
 995    </para>
 996    <para>
 997     Most
 998     <ulink url="&url.marc21;">MARC21</ulink>
 999     records uses the
1000     <ulink url="&url.marc8;">MARC-8</ulink>
1001     character set encoding.
1002     An application that wishes to display in Latin-1 would use
1003     <screen>
1004      render; charset=marc8,iso-8859-1
1005     </screen>
1006    </para>
1007    <sect2 id="zoom.z3950.record.behavior">
1008     <title>Z39.50 Protocol behavior</title>
1009     <para>
1010      The functions <function>ZOOM_resultset_record</function> and
1011      <function>ZOOM_resultset_records</function> inspects the client-side
1012      record cache. Records not found in cache are fetched using
1013      Present.
1014      The functions may block (and perform network I/O)  - even though option
1015      <literal>async</literal> is 1, because they return records objects.
1016      (and there's no way to return records objects without retrieving them!).
1017      </para>
1018     <para>
1019      There is a trick, however, in the usage of function
1020      <function>ZOOM_resultset_records</function> that allows for
1021      delayed retrieval (and makes it non-blocking). By using
1022      a null pointer for <parameter>recs</parameter> you're indicating
1023      you're not interested in getting records objects
1024      <emphasis>now</emphasis>.
1025     </para>
1026    </sect2>
1027    <sect2 id="zoom.sru.record.behavior">
1028     <title>SRU/Solr Protocol behavior</title>
1029     <para>
1030      The ZOOM driver for SRU/Solr treats records returned by a SRU/Solr server
1031      as if they where Z39.50 records with transfer syntax XML and
1032      no element set name or database name.
1033     </para>
1034    </sect2>
1035   </sect1>
1036   <sect1 id="zoom.facets"><title>Facets</title>
1037    <para>
1038     Facets operations is not part of the official ZOOM specification, but
1039     is an Index Data extension for YAZ-based Z39.50 targets or
1040     <ulink url="&url.solr;">Solr</ulink> targets.
1041     In case the target can and is requested to return facets, using a
1042     result set the ZOOM client can request one or all facet fields.
1043     Using a facet field the client can request the term count and then
1044     interate over the terms.
1045    </para>
1046    <synopsis>
1047     ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
1048
1049     const char ** ZOOM_resultset_facets_names(ZOOM_resultset r);
1050
1051     ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r,
1052                                                     const char *facet_name);
1053
1054     ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r,
1055                                                              int pos);
1056
1057     size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
1058
1059     const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
1060
1061     size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
1062
1063     const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field,
1064                                           size_t idx, int *freq);
1065    </synopsis>
1066    <para>
1067     References to temporary structures are returned by all functions.
1068     They are only valid as long the Result set is valid.
1069     <function>ZOOM_resultset_get_facet_field</function> or
1070     <function>ZOOM_resultset_get_facet_field_by_index</function>.
1071     <function>ZOOM_resultset_facets</function>.
1072     <function>ZOOM_resultset_facets_names</function>.
1073     <function>ZOOM_facet_field_name</function>.
1074     <function>ZOOM_facet_field_get_term</function>.
1075     </para>
1076    <para id="zoom.resultset.get_facet_field">
1077     A single Facet field  is returned by function
1078     <function>ZOOM_resultset_get_facet_field</function> or
1079     <function>ZOOM_resultset_get_facet_field_by_index</function> that takes
1080     a  result set and facet name or positive index respectively. First
1081     facet has position zero. If no facet could be obtained (invalid name
1082     or index out of bounds) <literal>NULL</literal> is returned.
1083    </para>
1084    <para id="zoom.resultset.facets">
1085     An array of facets field can be returned by
1086     <function>ZOOM_resultset_facets</function>. The length of the array is
1087     given by <function>ZOOM_resultset_facets_size</function>. The array is
1088     zero-based and last entry will be at
1089     <function>ZOOM_resultset_facets_size(result_set)</function>-1.
1090    </para>
1091    <para id="zoom.resultset.facets_names">
1092     It is possible to interate over facets by name, by calling
1093     <function>ZOOM_resultset_facets_names</function>.
1094     This will return an const array of char * where each string can be used
1095     as parameter for <function>ZOOM_resultset_get_facet_field</function>.
1096    </para>
1097    <para>
1098    Function <function>ZOOM_facet_field_name</function> gets the request
1099     facet name from a returned facet field.
1100    </para>
1101    <para>
1102     Function <function>ZOOM_facet_field_get_term</function> returns the
1103     idx'th term and term count for a facet field.
1104     Idx must between 0 and
1105     <function>ZOOM_facet_field_term_count</function>-1, otherwise the
1106     returned reference will be <literal>NULL</literal>. On a valid idx, the
1107     value of the freq reference will be the term count.
1108     The <literal>freq</literal> parameter must be valid pointer to integer.
1109    </para>
1110    </sect1>
1111   <sect1 id="zoom.scan"><title>Scan</title>
1112    <para>
1113     This section describes an interface for Scan. Scan is not an
1114     official part of the ZOOM model yet. The result of a scan operation
1115     is the <literal>ZOOM_scanset</literal> which is a set of terms
1116     returned by a target.
1117    </para>
1118
1119    <para>
1120     The Scan interface is supported for both Z39.50, SRU and Solr.
1121    </para>
1122
1123    <synopsis>
1124     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
1125                                       const char *startpqf);
1126
1127     ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
1128                                        ZOOM_query q);
1129
1130     size_t ZOOM_scanset_size(ZOOM_scanset scan);
1131
1132     const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
1133                                   size_t *occ, size_t *len);
1134
1135     const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
1136                                           size_t *occ, size_t *len);
1137
1138     void ZOOM_scanset_destroy(ZOOM_scanset scan);
1139
1140     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
1141                                         const char *key);
1142
1143     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
1144                                  const char *val);
1145     </synopsis>
1146    <para>
1147     The scan set is created by function
1148     <function>ZOOM_connection_scan</function> which performs a scan
1149     operation on the connection using the specified
1150     <parameter>startpqf</parameter>.
1151     If the operation was successful, the size of the scan set can be
1152     retrieved by a call to <function>ZOOM_scanset_size</function>.
1153     Like result sets, the items are numbered 0,..size-1.
1154     To obtain information about a particular scan term, call function
1155     <function>ZOOM_scanset_term</function>. This function takes
1156     a scan set offset <literal>pos</literal> and returns a pointer
1157     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
1158     non-present.
1159     If present, the <literal>occ</literal> and <literal>len</literal>
1160     are set to the number of occurrences and the length
1161     of the actual term respectively.
1162     <function>ZOOM_scanset_display_term</function> is similar to
1163     <function>ZOOM_scanset_term</function> except that it returns
1164     the <emphasis>display term</emphasis> rather than the raw term.
1165     In a few cases, the term is different from display term. Always
1166     use the display term for display and the raw term for subsequent
1167     scan operations (to get more terms, next scan result, etc).
1168    </para>
1169    <para>
1170     A scan set may be freed by a call to function
1171     <function>ZOOM_scanset_destroy</function>.
1172     Functions <function>ZOOM_scanset_option_get</function> and
1173     <function>ZOOM_scanset_option_set</function> retrieves and sets
1174     an option respectively.
1175    </para>
1176
1177    <para>
1178     The <parameter>startpqf</parameter> is a subset of PQF, namely
1179     the Attributes+Term part. Multiple <literal>@attr</literal> can
1180     be used. For example to scan in title (complete) phrases:
1181     <literallayout>
1182      @attr 1=4 @attr 6=2 "science o"
1183     </literallayout>
1184    </para>
1185
1186    <para>
1187     The <function>ZOOM_connecton_scan1</function> is a newer and
1188     more generic alternative to <function>ZOOM_connection_scan</function>
1189     which allows to use both CQL and PQF for Scan.
1190    </para>
1191
1192    <table frame="top" id="zoom.scanset.options">
1193     <title>ZOOM Scan Set Options</title>
1194     <tgroup cols="3">
1195      <colspec colwidth="4*" colname="name"></colspec>
1196      <colspec colwidth="7*" colname="description"></colspec>
1197      <colspec colwidth="2*" colname="default"></colspec>
1198      <thead>
1199       <row>
1200        <entry>Option</entry>
1201        <entry>Description</entry>
1202        <entry>Default</entry>
1203       </row>
1204      </thead>
1205      <tbody>
1206       <row><entry>
1207         number</entry><entry>Number of Scan Terms requested in next scan.
1208         After scan it holds the actual number of terms returned.
1209        </entry><entry>20</entry></row>
1210       <row><entry>
1211         position</entry><entry>Preferred Position of term in response
1212         in next scan; actual position after completion of scan.
1213        </entry><entry>1</entry></row>
1214       <row><entry>
1215         stepSize</entry><entry>Step Size
1216        </entry><entry>0</entry></row>
1217       <row><entry>
1218         scanStatus</entry><entry>An integer indicating the Scan Status
1219         of last scan.
1220        </entry><entry>0</entry></row>
1221       <row><entry>
1222         rpnCharset</entry><entry>Character set for RPN terms.
1223         If this is set, ZOOM C will assume that the ZOOM application is
1224         running UTF-8. Terms in RPN queries are then converted to the
1225         rpnCharset. If this is unset, ZOOM C will not assume any encoding
1226         of RPN terms and no conversion is performed.
1227        </entry><entry>none</entry></row>
1228      </tbody>
1229     </tgroup>
1230    </table>
1231   </sect1>
1232
1233   <sect1 id="zoom.extendedservices"><title>Extended Services</title>
1234    <para>
1235     ZOOM offers an interface to a subset of the Z39.50 extended services
1236     as well as a few privately defined ones:
1237    </para>
1238    <itemizedlist>
1239     <listitem>
1240      <para>
1241       Z39.50 Item Order (ILL).
1242       See <xref linkend="zoom.item.order"/>.
1243      </para>
1244     </listitem>
1245     <listitem>
1246      <para>
1247       Record Update. This allows a client to insert, modify or delete
1248       records.
1249       See <xref linkend="zoom.record.update"/>.
1250      </para>
1251     </listitem>
1252     <listitem>
1253      <para>
1254       Database Create. This a non-standard feature. Allows a client
1255       to create a database.
1256       See <xref linkend="zoom.database.create"/>.
1257      </para>
1258     </listitem>
1259     <listitem>
1260      <para>
1261       Database Drop. This a non-standard feature. Allows a client
1262       to delete/drop a database.
1263       See <xref linkend="zoom.database.drop"/>.
1264      </para>
1265      </listitem>
1266     <listitem>
1267      <para>
1268       Commit operation. This a non-standard feature. Allows a client
1269       to commit operations.
1270       See <xref linkend="zoom.commit"/>.
1271      </para>
1272     </listitem>
1273     <!-- all the ILL PDU options should go here too -->
1274    </itemizedlist>
1275    <para>
1276     To create an extended service operation a <literal>ZOOM_package</literal>
1277     must be created. The operation is a five step operation. The
1278     package is created, package is configured by means of options,
1279     the package is send, result is inspected (by means of options),
1280     the package is destroyed.
1281    </para>
1282    <synopsis>
1283     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
1284                                          ZOOM_options options);
1285
1286     const char *ZOOM_package_option_get(ZOOM_package p,
1287                                         const char *key);
1288     void ZOOM_package_option_set(ZOOM_package p, const char *key,
1289                                  const char *val);
1290     void ZOOM_package_send(ZOOM_package p, const char *type);
1291
1292     void ZOOM_package_destroy(ZOOM_package p);
1293    </synopsis>
1294    <para>
1295     The <function>ZOOM_connection_package</function> creates a
1296     package for the connection given using the options specified.
1297    </para>
1298    <para>
1299     Functions <function>ZOOM_package_option_get</function> and
1300     <function>ZOOM_package_option_set</function> gets and sets
1301     options.
1302    </para>
1303    <para>
1304     <function>ZOOM_package_send</function> sends
1305     the package the via connection specified in
1306     <function>ZOOM_connection_package</function>.
1307     The <parameter>type</parameter> specifies the actual extended service
1308     package type to be sent.
1309    </para>
1310
1311    <table frame="top" id="zoom.extendedservices.options">
1312     <title>Extended Service Common Options</title>
1313     <tgroup cols="3">
1314      <colspec colwidth="4*" colname="name"></colspec>
1315      <colspec colwidth="7*" colname="description"></colspec>
1316      <colspec colwidth="3*" colname="default"></colspec>
1317      <thead>
1318       <row>
1319        <entry>Option</entry>
1320        <entry>Description</entry>
1321        <entry>Default</entry>
1322       </row>
1323      </thead>
1324      <tbody>
1325       <row>
1326        <entry>package-name</entry>
1327        <entry>Extended Service Request package name. Must be specified
1328        as part of a request</entry>
1329        <entry>none</entry>
1330       </row>
1331       <row>
1332        <entry>user-id</entry>
1333        <entry>User ID of Extended Service Package. Is a request option</entry>
1334        <entry>none</entry>
1335       </row>
1336       <row>
1337        <entry>function</entry>
1338        <entry>
1339         Function of package - one of <literal>create</literal>,
1340         <literal>delete</literal>, <literal>modify</literal>. Is
1341         a request option.
1342        </entry>
1343        <entry><literal>create</literal></entry>
1344       </row>
1345       <row>
1346        <entry>waitAction</entry>
1347        <entry>
1348         Wait action for package. Possible values:
1349         <literal>wait</literal>, <literal>waitIfPossible</literal>,
1350         <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
1351        </entry>
1352        <entry><literal>waitIfPossible</literal></entry>
1353       </row>
1354       <row>
1355        <entry>targetReference</entry>
1356        <entry>
1357         Target Reference. This is part of the response as returned
1358         by the server. Read it after a successful operation.
1359        </entry>
1360        <entry><literal>none</literal></entry>
1361       </row>
1362      </tbody>
1363     </tgroup>
1364    </table>
1365
1366    <sect2 id="zoom.item.order"><title>Item Order</title>
1367     <para>
1368      For Item Order, type must be set to <literal>itemorder</literal> in
1369      <function>ZOOM_package_send</function>.
1370     </para>
1371
1372     <table frame="top" id="zoom.item.order.options">
1373      <title>Item Order Options</title>
1374      <tgroup cols="3">
1375       <colspec colwidth="4*" colname="name"></colspec>
1376       <colspec colwidth="7*" colname="description"></colspec>
1377       <colspec colwidth="3*" colname="default"></colspec>
1378       <thead>
1379        <row>
1380         <entry>Option</entry>
1381         <entry>Description</entry>
1382         <entry>Default</entry>
1383        </row>
1384       </thead>
1385       <tbody>
1386        <row>
1387         <entry>contact-name</entry>
1388         <entry>ILL contact name</entry>
1389         <entry>none</entry>
1390        </row>
1391        <row>
1392         <entry>contact-phone</entry>
1393         <entry>ILL contact phone</entry>
1394         <entry>none</entry>
1395        </row>
1396        <row>
1397         <entry>contact-email</entry>
1398         <entry>ILL contact email</entry>
1399         <entry>none</entry>
1400        </row>
1401        <row>
1402         <entry>itemorder-item</entry>
1403         <entry>Position for item (record) requested. An integer</entry>
1404         <entry>1</entry>
1405        </row>
1406       </tbody>
1407      </tgroup>
1408     </table>
1409
1410    </sect2>
1411
1412    <sect2 id="zoom.record.update"><title>Record Update</title>
1413     <para>
1414      For Record Update, type must be set to <literal>update</literal> in
1415      <function>ZOOM_package_send</function>.
1416     </para>
1417
1418     <table frame="top" id="zoom.record.update.options">
1419      <title>Record Update Options</title>
1420      <tgroup cols="3">
1421       <colspec colwidth="4*" colname="name"></colspec>
1422       <colspec colwidth="7*" colname="description"></colspec>
1423       <colspec colwidth="3*" colname="default"></colspec>
1424       <thead>
1425        <row>
1426         <entry>Option</entry>
1427         <entry>Description</entry>
1428         <entry>Default</entry>
1429        </row>
1430       </thead>
1431       <tbody>
1432        <row>
1433         <entry>action</entry>
1434         <entry>
1435          The update action. One of
1436          <literal>specialUpdate</literal>,
1437          <literal>recordInsert</literal>,
1438          <literal>recordReplace</literal>,
1439          <literal>recordDelete</literal>,
1440          <literal>elementUpdate</literal>.
1441         </entry>
1442         <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
1443        </row>
1444        <row>
1445         <entry>recordIdOpaque</entry>
1446         <entry>Opaque Record ID</entry>
1447         <entry>none</entry>
1448        </row>
1449        <row>
1450         <entry>recordIdNumber</entry>
1451         <entry>Record ID number</entry>
1452         <entry>none</entry>
1453        </row>
1454        <row>
1455         <entry>record</entry>
1456         <entry>The record itself</entry>
1457         <entry>none</entry>
1458        </row>
1459        <row>
1460         <entry>recordOpaque</entry>
1461         <entry>Specifies an opaque record which is
1462           encoded as an ASN.1 ANY type with the OID as tiven by option
1463           <literal>syntax</literal> (see below).
1464           Option <literal>recordOpaque</literal> is an alternative
1465           to record - and <literal>record</literal> option (above) is
1466           ignored if recordOpaque is set. This option is only available in
1467           YAZ 3.0.35 and later and is meant to facilitate Updates with
1468           servers from OCLC.
1469         </entry>
1470         <entry>none</entry>
1471        </row>
1472        <row>
1473         <entry>syntax</entry>
1474         <entry>The record syntax (transfer syntax). Is a string that
1475          is a known record syntax.
1476         </entry>
1477         <entry>no syntax</entry>
1478        </row>
1479        <row>
1480         <entry>databaseName</entry>
1481         <entry>Database from connection object</entry>
1482         <entry>Default</entry>
1483        </row>
1484        <row>
1485         <entry>correlationInfo.note</entry>
1486         <entry>Correlation Info Note (string)</entry>
1487         <entry>none</entry>
1488        </row>
1489        <row>
1490         <entry>correlationInfo.id</entry>
1491         <entry>Correlation Info ID (integer)</entry>
1492         <entry>none</entry>
1493        </row>
1494        <row>
1495         <entry>elementSetName</entry>
1496         <entry>Element Set for Record</entry>
1497         <entry>none</entry>
1498        </row>
1499        <row>
1500         <entry>updateVersion</entry>
1501         <entry>Record Update version which holds one of the values
1502          1, 2 or 3. Each version has a distinct OID:
1503          1.2.840.10003.9.5
1504          (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
1505          1.2.840.10003.9.5.1
1506          (second version) and
1507          1.2.840.10003.9.5.1.1
1508          (<ulink url="&url.z39.50.extupdate3;">third and
1509           newest version</ulink>).
1510         </entry>
1511         <entry>3</entry>
1512        </row>
1513       </tbody>
1514      </tgroup>
1515     </table>
1516
1517    </sect2>
1518
1519    <sect2 id="zoom.database.create"><title>Database Create</title>
1520     <para>
1521      For Database Create, type must be set to <literal>create</literal> in
1522      <function>ZOOM_package_send</function>.
1523     </para>
1524
1525     <table frame="top" id="zoom.database.create.options">
1526      <title>Database Create Options</title>
1527      <tgroup cols="3">
1528       <colspec colwidth="4*" colname="name"></colspec>
1529       <colspec colwidth="7*" colname="description"></colspec>
1530       <colspec colwidth="3*" colname="default"></colspec>
1531       <thead>
1532        <row>
1533         <entry>Option</entry>
1534         <entry>Description</entry>
1535         <entry>Default</entry>
1536        </row>
1537       </thead>
1538       <tbody>
1539        <row>
1540         <entry>databaseName</entry>
1541         <entry>Database from connection object</entry>
1542         <entry>Default</entry>
1543        </row>
1544       </tbody>
1545      </tgroup>
1546     </table>
1547    </sect2>
1548
1549    <sect2 id="zoom.database.drop"><title>Database Drop</title>
1550     <para>
1551      For Database Drop, type must be set to <literal>drop</literal> in
1552      <function>ZOOM_package_send</function>.
1553     </para>
1554
1555     <table frame="top" id="zoom.database.drop.options">
1556      <title>Database Drop Options</title>
1557      <tgroup cols="3">
1558       <colspec colwidth="4*" colname="name"></colspec>
1559       <colspec colwidth="7*" colname="description"></colspec>
1560       <colspec colwidth="3*" colname="default"></colspec>
1561       <thead>
1562        <row>
1563         <entry>Option</entry>
1564         <entry>Description</entry>
1565         <entry>Default</entry>
1566        </row>
1567       </thead>
1568       <tbody>
1569        <row>
1570         <entry>databaseName</entry>
1571         <entry>Database from connection object</entry>
1572         <entry>Default</entry>
1573        </row>
1574       </tbody>
1575      </tgroup>
1576     </table>
1577    </sect2>
1578
1579    <sect2 id="zoom.commit"><title>Commit Operation</title>
1580     <para>
1581      For Commit, type must be set to <literal>commit</literal> in
1582      <function>ZOOM_package_send</function>.
1583     </para>
1584    </sect2>
1585
1586    <sect2 id="zoom.extended.services.behavior">
1587     <title>Protocol behavior</title>
1588     <para>
1589      All the extended services are Z39.50-only.
1590     </para>
1591     <note>
1592      <para>
1593       The database create, drop and commit services are privately defined
1594       operations.
1595       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1596       definitions.
1597      </para>
1598     </note>
1599    </sect2>
1600   </sect1>
1601
1602   <sect1 id="zoom.options"><title>Options</title>
1603    <para>
1604     Most &zoom; objects provide a way to specify options to change behavior.
1605     From an implementation point of view a set of options is just like
1606     an associative array / hash.
1607    </para>
1608    <synopsis>
1609      ZOOM_options ZOOM_options_create(void);
1610
1611      ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
1612
1613      void ZOOM_options_destroy(ZOOM_options opt);
1614    </synopsis>
1615    <synopsis>
1616      const char *ZOOM_options_get(ZOOM_options opt, const char *name);
1617
1618      void ZOOM_options_set(ZOOM_options opt, const char *name,
1619                            const char *v);
1620    </synopsis>
1621    <synopsis>
1622      typedef const char *(*ZOOM_options_callback)
1623                             (void *handle, const char *name);
1624
1625      ZOOM_options_callback
1626              ZOOM_options_set_callback(ZOOM_options opt,
1627                                        ZOOM_options_callback c,
1628                                        void *handle);
1629    </synopsis>
1630   </sect1>
1631
1632   <sect1 id="zoom.queryconversions"><title>Query conversions</title>
1633    <synopsis>
1634     int ZOOM_query_cql2rpn(ZOOM_query s, const char *cql_str,
1635                            ZOOM_connection conn);
1636
1637     int ZOOM_query_ccl2rpn(ZOOM_query s, const char *ccl_str,
1638                            const char *config,
1639                            int *ccl_error, const char **error_string,
1640                            int *error_pos);
1641    </synopsis>
1642    <para>
1643     <function>ZOOM_query_cql2rpn</function> translates the CQL string,
1644     client-side, into RPN which may be passed to the server.
1645     This is useful for server's that don't themselves
1646     support CQL, for which <function>ZOOM_query_cql</function> is useless.
1647     `conn' is used  only as a place to stash diagnostics if compilation
1648     fails; if this information is not needed, a null pointer may be used.
1649     The CQL conversion is driven by option <literal>cqlfile</literal> from
1650     connection conn. This specifies a conversion file (eg pqf.properties)
1651     which <emphasis>must</emphasis> be present.
1652    </para>
1653    <para>
1654     <function>ZOOM_query_ccl2rpn</function> translates the CCL string,
1655     client-side, into RPN which may be passed to the server.
1656     The conversion is driven by the specification given by
1657     <literal>config</literal>. Upon completion 0 is returned on success; -1
1658     is returned on on failure. Om failure <literal>error_string</literal> and
1659     <literal>error_pos</literal> holds error message and position of
1660     first error in original CCL string.
1661    </para>
1662   </sect1>
1663   <sect1 id="zoom.events"><title>Events</title>
1664    <para>
1665     If you're developing non-blocking applications, you have to deal
1666     with events.
1667    </para>
1668    <synopsis>
1669     int ZOOM_event(int no, ZOOM_connection *cs);
1670    </synopsis>
1671    <para>
1672     The <function>ZOOM_event</function> executes pending events for
1673     a number of connections. Supply the number of connections in
1674     <literal>no</literal> and an array of connections in
1675     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1676     A pending event could be a sending a search, receiving a response,
1677     etc.
1678     When an event has occurred for one of the connections, this function
1679     returns a positive integer <literal>n</literal> denoting that an event
1680     occurred for connection <literal>cs[n-1]</literal>.
1681     When no events are pending for the connections, a value of zero is
1682     returned.
1683     To ensure that all outstanding requests are performed call this function
1684     repeatedly until zero is returned.
1685    </para>
1686    <para>
1687     If <function>ZOOM_event</function> returns and returns non-zero, the
1688     last event that occurred can be expected.
1689    </para>
1690    <synopsis>
1691     int ZOOM_connection_last_event(ZOOM_connection cs);
1692    </synopsis>
1693    <para>
1694     <function>ZOOM_connection_last_event</function> returns an event type
1695     (integer) for the last event.
1696    </para>
1697
1698    <table frame="top" id="zoom.event.ids">
1699     <title>ZOOM Event IDs</title>
1700     <tgroup cols="2">
1701      <colspec colwidth="4*" colname="name"></colspec>
1702      <colspec colwidth="7*" colname="description"></colspec>
1703      <thead>
1704       <row>
1705        <entry>Event</entry>
1706        <entry>Description</entry>
1707       </row>
1708      </thead>
1709      <tbody>
1710       <row>
1711        <entry>ZOOM_EVENT_NONE</entry>
1712        <entry>No event has occurred</entry>
1713       </row>
1714       <row>
1715        <entry>ZOOM_EVENT_CONNECT</entry>
1716        <entry>TCP/IP connect has initiated</entry>
1717       </row>
1718       <row>
1719        <entry>ZOOM_EVENT_SEND_DATA</entry>
1720        <entry>Data has been transmitted (sending)</entry>
1721       </row>
1722       <row>
1723        <entry>ZOOM_EVENT_RECV_DATA</entry>
1724        <entry>Data has been received)</entry>
1725       </row>
1726       <row>
1727        <entry>ZOOM_EVENT_TIMEOUT</entry>
1728        <entry>Timeout</entry>
1729       </row>
1730       <row>
1731        <entry>ZOOM_EVENT_UNKNOWN</entry>
1732        <entry>Unknown event</entry>
1733       </row>
1734       <row>
1735        <entry>ZOOM_EVENT_SEND_APDU</entry>
1736        <entry>An APDU has been transmitted (sending)</entry>
1737       </row>
1738       <row>
1739        <entry>ZOOM_EVENT_RECV_APDU</entry>
1740        <entry>An APDU has been received</entry>
1741       </row>
1742       <row>
1743        <entry>ZOOM_EVENT_RECV_RECORD</entry>
1744        <entry>A result-set record has been received</entry>
1745       </row>
1746       <row>
1747        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1748        <entry>A search result been received</entry>
1749       </row>
1750      </tbody>
1751     </tgroup>
1752    </table>
1753   </sect1>
1754  </chapter>
1755
1756  <!-- Keep this comment at the end of the file
1757  Local variables:
1758  mode: sgml
1759  sgml-omittag:t
1760  sgml-shorttag:t
1761  sgml-minimize-attributes:nil
1762  sgml-always-quote-attributes:t
1763  sgml-indent-step:1
1764  sgml-indent-data:t
1765  sgml-parent-document: "yaz.xml"
1766  sgml-local-catalogs: nil
1767  sgml-namecase-general:t
1768  End:
1769  -->
1770