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_diag_str(error)
   9 ZOOM_resultset_record_immediate(s, pos)
  10 ZOOM_resultset_cache_reset(r)
  11 ZOOM_resultset_sort(r, sort_type, sort_spec)
  12 ZOOM_resultset_sort1(r, sort_type, sort_spec)
  13 ZOOM_options_set_callback(opt, function, handle)
  14 ZOOM_options_create_with_parent2(parent1, parent2)
  15 ZOOM_options_getl(opt, name, len)
  16 ZOOM_options_setl(opt, name, value, len)
  17 ZOOM_options_get_bool(opt, name, defa)
  18 ZOOM_options_get_int(opt, name, defa)
  19 ZOOM_options_set_int(opt, name, value)
  20 ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm)
  21 ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
  22 -->
  23 <!-- $Id: zoom.xml,v 1.52 2006-10-05 08:26:58 adam Exp $ -->
  24  <chapter id="zoom"><title>ZOOM</title>
  25   <para>
  26     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
  27    an initiative started by Mike Taylor (Mike is from the UK, which
  28    explains the peculiar name of the model). The goal of &zoom; is to
  29    provide a common Z39.50 client API not bound to a particular
  30    programming language or toolkit.
  31   </para>
  32
  33   <note>
  34    <para>
  35     A recent addition to &yaz; is SRU support. You can now make
  36     SRU ZOOM connections by specifying scheme <literal>http://</literal>
  37     for the hostname for a connection.
  38    </para>
  39   </note>
  40
  41   <para>
  42    The lack of a simple Z39.50 client API for &yaz; has become more
  43    and more apparent over time. So when the first &zoom; specification
  44    became available,
  45    an implementation for &yaz; was quickly developed. For the first time, it is
  46    now as easy (or easier!) to develop clients than servers with &yaz;. This
  47    chapter describes the &zoom; C binding. Before going further, please
  48    reconsider whether C is the right programming language for the job.
  49    There are other language bindings available for &yaz;, and still
  50    more
  51    are in active development. See the
  52    <ulink url="&url.zoom;">ZOOM web-site</ulink> for
  53    more information.
  54   </para>
  55
  56   <para>
  57    In order to fully understand this chapter you should read and
  58    try the example programs <literal>zoomtst1.c</literal>,
  59    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
  60    directory.
  61   </para>
  62
  63   <para>
  64    The C language misses features found in object oriented languages
  65    such as C++, Java, etc. For example, you'll have to manually,
  66    destroy all objects you create, even though you may think of them as
  67    temporary. Most objects has a <literal>_create</literal> - and a
  68    <literal>_destroy</literal> variant.
  69    All objects are in fact pointers to internal stuff, but you don't see
  70    that because of typedefs. All destroy methods should gracefully ignore a
  71    <literal>NULL</literal> pointer.
  72   </para>
  73   <para>
  74    In each of the sections below you'll find a sub section called
  75    protocol behavior, that describes how the API maps to the Z39.50
  76    protocol.
  77   </para>
  78   <sect1 id="zoom-connections"><title>Connections</title>
  79
  80    <para>The Connection object is a session with a target.
  81    </para>
  82    <synopsis>
  83     #include &lt;yaz/zoom.h>
  84
  85     ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
  86
  87     ZOOM_connection ZOOM_connection_create (ZOOM_options options);
  88
  89     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
  90                                  int portnum);
  91     void ZOOM_connection_destroy (ZOOM_connection c);
  92    </synopsis>
  93    <para>
  94     Connection objects are created with either function
  95     <function>ZOOM_connection_new</function> or
  96     <function>ZOOM_connection_create</function>.
  97     The former creates and automatically attempts to establish a network
  98     connection with the target. The latter doesn't establish
  99     a connection immediately, thus allowing you to specify options
 100     before establishing network connection using the function
 101     <function>ZOOM_connection_connect</function>.
 102     If the port number, <literal>portnum</literal>, is zero, the
 103     <literal>host</literal> is consulted for a port specification.
 104     If no port is given, 210 is used. A colon denotes the beginning of
 105     a port number in the host string. If the host string includes a
 106     slash, the following part specifies a database for the connection.
 107    </para>
 108    <para>
 109     You can prefix the host with a scheme followed by colon. The
 110     default scheme is <literal>tcp</literal> (Z39.50 protocol).
 111     The scheme <literal>http</literal> selects SRU over HTTP.
 112    </para>
 113    <para>
 114     You can prefix the scheme-qualified host-string with one or more
 115     comma-separated
 116     <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
 117     sequences, each of which represents an option to be set into the
 118     connection structure <emphasis>before</emphasis> the
 119     protocol-level connection is forged and the initialisation
 120     handshake takes place.  This facility can be used to provide
 121     authentication credentials, as in host-strings such as:
 122     <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
 123    </para>
 124    <para>
 125     Connection objects should be destroyed using the function
 126     <function>ZOOM_connection_destroy</function>.
 127    </para>
 128    <synopsis>
 129     void ZOOM_connection_option_set(ZOOM_connection c,
 130                                     const char *key, const char *val);
 131
 132     void ZOOM_connection_option_setl(ZOOM_connection c,
 133                                      const char *key,
 134                                      const char *val, int len);
 135
 136     const char *ZOOM_connection_option_get(ZOOM_connection c,
 137                                            const char *key);
 138     const char *ZOOM_connection_option_getl(ZOOM_connection c,
 139                                             const char *key,
 140                                             int *lenp);
 141    </synopsis>
 142    <para>
 143     The functions <function>ZOOM_connection_option_set</function> and
 144     <function>ZOOM_connection_option_setl</function> allows you to
 145     set an option given by <parameter>key</parameter> to the value
 146     <parameter>value</parameter> for the connection.
 147     For <function>ZOOM_connection_option_set</function>, the
 148     value is assumed to be a 0-terminated string. Function
 149     <function>ZOOM_connection_option_setl</function> specifies a
 150     value of a certain size (len).
 151    </para>
 152    <para>
 153     Functions <function>ZOOM_connection_option_get</function> and
 154     <function>ZOOM_connection_option_getl</function> returns
 155     the value for an option given by <parameter>key</parameter>.
 156    </para>
 157    <table id="zoom-connection-options" frame="top">
 158     <title>ZOOM Connection Options</title>
 159     <tgroup cols="3">
 160      <colspec colwidth="4*" colname="name"></colspec>
 161      <colspec colwidth="7*" colname="description"></colspec>
 162      <colspec colwidth="3*" colname="default"></colspec>
 163      <thead>
 164       <row>
 165        <entry>Option</entry>
 166        <entry>Description</entry>
 167        <entry>Default</entry>
 168       </row>
 169      </thead>
 170      <tbody>
 171       <row><entry>
 172         implementationName</entry><entry>Name of Your client
 173        </entry><entry>none</entry></row>
 174       <row><entry>
 175         user</entry><entry>Authentication user name
 176        </entry><entry>none</entry></row>
 177       <row><entry>
 178         group</entry><entry>Authentication group name
 179        </entry><entry>none</entry></row>
 180       <row><entry>
 181         password</entry><entry>Authentication password.
 182        </entry><entry>none</entry></row>
 183       <row><entry>
 184         host</entry><entry>Target host. This setting is "read-only".
 185         It's automatically set internally when connecting to a target.
 186        </entry><entry>none</entry></row>
 187       <row><entry>
 188         proxy</entry><entry>Proxy host
 189        </entry><entry>none</entry></row>
 190       <row><entry>
 191         async</entry><entry>If true (1) the connection operates in
 192         asynchronous operation which means that all calls are non-blocking
 193         except
 194         <link linkend="zoom.events"><function>ZOOM_event</function></link>.
 195        </entry><entry>0</entry></row>
 196       <row><entry>
 197         maximumRecordSize</entry><entry> Maximum size of single record.
 198        </entry><entry>1 MB</entry></row>
 199       <row><entry>
 200         preferredMessageSize</entry><entry> Maximum size of multiple records.
 201        </entry><entry>1 MB</entry></row>
 202       <row><entry>
 203         lang</entry><entry> Language for negotiation.
 204        </entry><entry>none</entry></row>
 205       <row><entry>
 206         charset</entry><entry> Character set for negotiation.
 207        </entry><entry>none</entry></row>
 208       <row><entry>
 209         serverImplementationId</entry><entry>
 210         Implementation ID of server.  (The old targetImplementationId
 211         option is also supported for the benefit of old applications.)
 212        </entry><entry>none</entry></row>
 213       <row><entry>
 214         targetImplementationName</entry><entry>
 215         Implementation Name of server.  (The old
 216         targetImplementationName option is also supported for the
 217         benefit of old applications.)
 218        </entry><entry>none</entry></row>
 219       <row><entry>
 220         serverImplementationVersion</entry><entry>
 221         Implementation Version of server.  (the old
 222         targetImplementationVersion option is also supported for the
 223         benefit of old applications.)
 224        </entry><entry>none</entry></row>
 225       <row><entry>
 226         databaseName</entry><entry>One or more database names
 227         separated by character plus (<literal>+</literal>), which to
 228         be used by subsequent search requests on this Connection.
 229        </entry><entry>Default</entry></row>
 230       <row><entry>
 231         piggyback</entry><entry>True (1) if piggyback should be
 232         used in searches; false (0) if not.
 233        </entry><entry>1</entry></row>
 234       <row><entry>
 235         smallSetUpperBound</entry><entry>If hits is less than or equal to this
 236         value, then target will return all records using small element set name
 237        </entry><entry>0</entry></row>
 238       <row><entry>
 239         largeSetLowerBound</entry><entry>If hits is greater than this
 240         value, the target will return no records.
 241        </entry><entry>1</entry></row>
 242       <row><entry>
 243         mediumSetPresentNumber</entry><entry>This value represents
 244         the number of records to be returned as part of a search when when
 245         hits is less than or equal to large set lower bound and if hits
 246         is greater than small set upper bound.
 247        </entry><entry>0</entry></row>
 248       <row><entry>
 249         smallSetElementSetName</entry><entry>
 250         The element set name to be used for small result sets.
 251        </entry><entry>none</entry></row>
 252       <row><entry>
 253         mediumSetElementSetName</entry><entry>
 254         The element set name to be for medium-sized result sets.
 255        </entry><entry>none</entry></row>
 256      </tbody>
 257     </tgroup>
 258    </table>
 259    <para>
 260     If either option <literal>lang</literal> or <literal>charset</literal>
 261     is set, then
 262     <ulink url="&url.z39.50.charneg;">
 263      Character Set and Language Negotiation</ulink> is in effect.
 264    </para>
 265    <synopsis>
 266      int ZOOM_connection_error (ZOOM_connection c, const char **cp,
 267                                 const char **addinfo);
 268      int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
 269                                   const char **addinfo, const char **dset);
 270    </synopsis>
 271    <para>
 272     Function <function>ZOOM_connection_error</function> checks for
 273     errors for the last operation(s) performed. The function returns
 274     zero if no errors occurred; non-zero otherwise indicating the error.
 275     Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
 276     holds messages for the error and additional-info if passed as
 277     non-<literal>NULL</literal>. Function
 278     <function>ZOOM_connection_error_x</function> is an extended version
 279     of <function>ZOOM_connection_error</function> that is capable of
 280     returning name of diagnostic set in <parameter>dset</parameter>.
 281    </para>
 282    <sect2 id="zoom-connection-z39.50">
 283     <title>Z39.50 Protocol behavior</title>
 284     <para>
 285      The calls <function>ZOOM_connection_new</function> and
 286      <function>ZOOM_connection_connect</function> establishes a TCP/IP
 287       connection and sends an Initialize Request to the target if
 288       possible. In addition, the calls waits for an Initialize Response
 289       from the target and the result is inspected (OK or rejected).
 290     </para>
 291     <para>
 292      If <literal>proxy</literal> is set then the client will establish
 293      a TCP/IP connection with the peer as specified by the
 294      <literal>proxy</literal> host and the hostname as part of the
 295      connect calls will be set as part of the Initialize Request.
 296      The proxy server will then "forward" the PDU's transparently
 297      to the target behind the proxy.
 298     </para>
 299     <para>
 300      For the authentication parameters, if option <literal>user</literal>
 301      is set and both options <literal>group</literal> and
 302      <literal>pass</literal> are unset, then Open style
 303      authentication is used (Version 2/3) in which case the username
 304      is usually followed by a slash, then by a password.
 305      If either <literal>group</literal>
 306      or <literal>pass</literal> is set then idPass authentication
 307      (Version 3 only) is used. If none of the options are set, no
 308      authentication parameters are set as part of the Initialize Request
 309      (obviously).
 310     </para>
 311     <para>
 312      When option <literal>async</literal> is 1, it really means that
 313      all network operations are postponed (and queued) until the
 314      function <literal>ZOOM_event</literal> is invoked. When doing so
 315      it doesn't make sense to check for errors after
 316      <literal>ZOOM_connection_new</literal> is called since that
 317      operation "connecting - and init" is still incomplete and the
 318      API cannot tell the outcome (yet).
 319     </para>
 320     </sect2>
 321    <sect2 id="zoom.sru.init.behavior">
 322     <title>SRU Protocol behavior</title>
 323     <para>
 324      The SRU protocol doesn't feature an Inititialize Request, so
 325      the connection phase merely establishes a TCP/IP connection
 326      with the SOAP service.
 327     </para>
 328     <para>Most of the ZOOM connection options do not
 329      affect SRU and they are ignored. However, future versions
 330      of &yaz; might honor <literal>implementationName</literal> and
 331      put that as part of User-Agent header for HTTP requests.
 332      </para>
 333     <para>
 334      The <literal>charset</literal> is used in the Content-Type header
 335      of HTTP requests.
 336     </para>
 337    </sect2>
 338   </sect1>
 339   <sect1 id="zoom.query"><title>Queries</title>
 340    <para>
 341     Query objects represents queries.
 342    </para>
 343    <synopsis>
 344      ZOOM_query ZOOM_query_create(void);
 345
 346      void ZOOM_query_destroy(ZOOM_query q);
 347
 348      int ZOOM_query_prefix(ZOOM_query q, const char *str);
 349
 350      int ZOOM_query_cql(ZOOM_query s, const char *str);
 351
 352      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
 353    </synopsis>
 354    <para>
 355     Create query objects using <function>ZOOM_query_create</function>
 356     and destroy them by calling <function>ZOOM_query_destroy</function>.
 357     RPN-queries can be specified in <link linkend="PQF">PQF</link>
 358     notation by using the
 359     function <function>ZOOM_query_prefix</function>.
 360     The <function>ZOOM_query_cql</function> specifies a CQL
 361     query to be sent to the server/target.
 362     More query types will be added in future versions of &yaz;, such as
 363     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
 364     etc. In addition to a search, a sort criteria may be set. Function
 365     <function>ZOOM_query_sortby</function> specifies a
 366     sort criteria using the same string notation for sort as offered by
 367     the <link linkend="sortspec">YAZ client</link>.
 368    </para>
 369    <sect2 id="zoom.sort.behavior"><title>Protocol behavior</title>
 370     <para>
 371      The query object is just an interface for the member Query
 372      in the SearchRequest. The sortby-function is an interface to the
 373      sortSequence member of the SortRequest.
 374     </para>
 375    </sect2>
 376   </sect1>
 377   <sect1 id="zoom.resultsets"><title>Result sets</title>
 378    <para>
 379     The result set object is a container for records returned from
 380     a target.
 381    </para>
 382    <synopsis>
 383      ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
 384                                            ZOOM_query q);
 385
 386      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
 387                                                const char *q);
 388
 389      void ZOOM_resultset_destroy(ZOOM_resultset r);
 390    </synopsis>
 391    <para>
 392     Function <function>ZOOM_connection_search</function> creates
 393      a result set given a connection and query.
 394     Destroy a result set by calling
 395     <function>ZOOM_resultset_destroy</function>.
 396     Simple clients may using PQF only may use function
 397     <function>ZOOM_connection_search_pqf</function> in which case
 398     creating query objects is not necessary.
 399    </para>
 400    <synopsis>
 401      void ZOOM_resultset_option_set (ZOOM_resultset r,
 402                                       const char *key,
 403                                       const char *val);
 404
 405      const char *ZOOM_resultset_option_get (ZOOM_resultset r,
 406                                              const char *key);
 407
 408      size_t ZOOM_resultset_size (ZOOM_resultset r);
 409    </synopsis>
 410    <para>
 411     Functions <function>ZOOM_resultset_options_set</function> and
 412     <function>ZOOM_resultset_get</function> sets and gets an option
 413     for a result set similar to <function>ZOOM_connection_option_get</function>
 414     and <function>ZOOM_connection_option_set</function>.
 415    </para>
 416    <para>
 417     The number of hits also called result-count is returned by
 418     function <function>ZOOM_resultset_size</function>.
 419    </para>
 420    <table id="zoom.resultset.options"
 421     frame="top"><title>ZOOM Result set Options</title>
 422     <tgroup cols="3">
 423      <colspec colwidth="4*" colname="name"></colspec>
 424      <colspec colwidth="7*" colname="description"></colspec>
 425      <colspec colwidth="2*" colname="default"></colspec>
 426      <thead>
 427       <row>
 428        <entry>Option</entry>
 429        <entry>Description</entry>
 430        <entry>Default</entry>
 431       </row>
 432      </thead>
 433      <tbody>
 434       <row><entry>
 435         start</entry><entry>Offset of first record to be
 436         retrieved from target. First record has offset 0 unlike the
 437         protocol specifications where first record has position 1.
 438        </entry><entry>0</entry></row>
 439       <row><entry>
 440         count</entry><entry>Number of records to be retrieved.
 441        </entry><entry>0</entry></row>
 442       <row><entry>
 443         presentChunk</entry><entry>The number of records to be
 444         requested from the server in each chunk (present requst).  The
 445         value 0 means to request all the records in a single chunk.
 446         (The old <literal>step</literal>
 447         option is also supported for the benefit of old applications.)
 448        </entry><entry>0</entry></row>
 449       <row><entry>
 450         elementSetName</entry><entry>Element-Set name of records.
 451         Most targets should honor element set name <literal>B</literal>
 452         and <literal>F</literal> for brief and full respectively.
 453        </entry><entry>none</entry></row>
 454       <row><entry>
 455         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
 456         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
 457        </entry><entry>none</entry></row>
 458       <row><entry>
 459         schema</entry><entry>Schema for retrieval, such as
 460         <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
 461        </entry><entry>none</entry></row>
 462       <row><entry>
 463         setname</entry><entry>Name of Result Set (Result Set ID).
 464         If this option isn't set, the ZOOM module will automatically
 465         allocate a result set name.
 466        </entry><entry>default</entry></row>
 467      </tbody>
 468     </tgroup>
 469    </table>
 470    <para>
 471     For servers that support Search Info report, the following
 472     options may be read using <function>ZOOM_resultset_get</function>.
 473     This detailed information is read after a successful search has
 474     completed.
 475    </para>
 476    <para>
 477     This information is a list of of items, where each item is
 478     information about a term or subquery. All items in the list
 479     are prefixed by
 480     <literal>SearchResult.</literal><replaceable>no</replaceable>
 481     where no presents the item number (0=first, 1=second).
 482     Read <literal>searchresult.size</literal> to determine the
 483     number of items.
 484    </para>
 485    <table id="zoom.search.info.report.options"
 486     frame="top"><title>Search Info Report Options</title>
 487     <tgroup cols="2">
 488      <colspec colwidth="4*" colname="name"></colspec>
 489      <colspec colwidth="7*" colname="description"></colspec>
 490      <thead>
 491       <row>
 492        <entry>Option</entry>
 493        <entry>Description</entry>
 494       </row>
 495      </thead>
 496      <tbody>
 497       <row>
 498        <entry>searchresult.size</entry>
 499        <entry>
 500         number of search result entries. This option is-nonexistant
 501         if no entries are returned by the server.
 502        </entry>
 503       </row>
 504       <row>
 505        <entry>searchresult.<replaceable>no</replaceable>.id</entry>
 506        <entry>sub query ID</entry>
 507       </row>
 508       <row>
 509        <entry>searchresult.<replaceable>no</replaceable>.count</entry>
 510        <entry>result count for item (number of hits)</entry>
 511       </row>
 512       <row>
 513        <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
 514        <entry>subquery term</entry>
 515       </row>
 516       <row>
 517        <entry>
 518         searchresult.<replaceable>no</replaceable>.interpretation.term
 519        </entry>
 520        <entry>interpretation term</entry>
 521       </row>
 522       <row>
 523        <entry>
 524         searchresult.<replaceable>no</replaceable>.recommendation.term
 525        </entry>
 526        <entry>recommendation term</entry>
 527       </row>
 528      </tbody>
 529     </tgroup>
 530    </table>
 531    <sect2 id="zoom.z3950.resultset.behavior">
 532     <title>Z39.50 Protocol behavior</title>
 533     <para>
 534      The creation of a result set involves at least a SearchRequest
 535      - SearchResponse protocol handshake. Following that, if a sort
 536      criteria was specified as part of the query, a SortRequest -
 537      SortResponse handshake takes place. Note that it is necessary to
 538      perform sorting before any retrieval takes place, so no records will
 539      be returned from the target as part of the SearchResponse because these
 540      would be unsorted. Hence, piggyback is disabled when sort criteria
 541      are set. Following Search - and a possible sort - Retrieval takes
 542      place - as one or more Present Requests/Response pairs being
 543      transferred.
 544      </para>
 545     <para>
 546      The API allows for two different modes for retrieval. A high level
 547      mode which is somewhat more powerful and a low level one.
 548      The low level is enabled when searching on a Connection object
 549      for which the settings
 550      <literal>smallSetUpperBound</literal>,
 551      <literal>mediumSetPresentNumber</literal> and
 552      <literal>largeSetLowerBound</literal> are set. The low level mode
 553      thus allows you to precisely set how records are returned as part
 554      of a search response as offered by the Z39.50 protocol.
 555      Since the client may be retrieving records as part of the
 556      search response, this mode doesn't work well if sorting is used.
 557      </para>
 558     <para>
 559      The high-level mode allows you to fetch a range of records from
 560      the result set with a given start offset. When you use this mode
 561      the client will automatically use piggyback if that is possible
 562      with the target and perform one or more present requests as needed.
 563      Even if the target returns fewer records as part of a present response
 564      because of a record size limit, etc. the client will repeat sending
 565      present requests. As an example, if option <literal>start</literal>
 566      is 0 (default) and <literal>count</literal> is 4, and
 567      <literal>piggyback</literal> is 1 (default) and no sorting criteria
 568      is specified, then the client will attempt to retrieve the 4
 569      records as part the search response (using piggyback). On the other
 570      hand, if either <literal>start</literal> is positive or if
 571      a sorting criteria is set, or if <literal>piggyback</literal>
 572      is 0, then the client will not perform piggyback but send Present
 573      Requests instead.
 574     </para>
 575     <para>
 576      If either of the options <literal>mediumSetElementSetName</literal> and
 577      <literal>smallSetElementSetName</literal> are unset, the value
 578      of option <literal>elementSetName</literal> is used for piggyback
 579      searches. This means that for the high-level mode you only have
 580      to specify one elementSetName option rather than three.
 581      </para>
 582    </sect2>
 583    <sect2 id="zoom.sru.resultset.behavior">
 584     <title>SRU Protocol behavior</title>
 585     <para>
 586      Current version of &yaz; does not take advantage of a result set id
 587      returned by the SRU server. Future versions might do, however.
 588      Since, the ZOOM driver does not save result set IDs any
 589      present (retrieval) is transformed to a SRU SearchRetrieveRequest
 590      with same query but, possibly, different offsets.
 591     </para>
 592     <para>
 593      Option <literal>schema</literal> specifies SRU schema
 594      for retrieval. However, options <literal>elementSetName</literal> and
 595      <literal>preferredRecordSyntax</literal> are ignored.
 596     </para>
 597     <para>
 598      Options <literal>start</literal> and <literal>count</literal>
 599      are supported by SRU.
 600      The remaining options
 601      <literal>piggyback</literal>,
 602      <literal>smallSetUpperBound</literal>,
 603      <literal>largeSetLowerBound</literal>,
 604      <literal>mediumSetPresentNumber</literal>,
 605      <literal>mediumSetElementSetName</literal>,
 606       <literal>smallSetElementSetName</literal> are
 607      unsupported.
 608     </para>
 609     <para>
 610      SRU supports CQL queries, <emphasis>not</emphasis> PQF.
 611      If PQF is used, however, the PQF query is transferred anyway
 612      using non-standard element <literal>pQuery</literal> in
 613      SRU SearchRetrieveRequest.
 614     </para>
 615     <para>
 616      Unfortunately, SRU does not define a database setting. Hence,
 617      <literal>databaseName</literal> is unsupported and ignored.
 618      However, the path part in host parameter for functions
 619      <function>ZOOM_connecton_new</function> and
 620      <function>ZOOM_connection_connect</function> acts as a
 621      database (at least for the &yaz; SRU server).
 622     </para>
 623    </sect2>
 624   </sect1>
 625   <sect1 id="zoom.records"><title>Records</title>
 626    <para>
 627     A record object is a retrieval record on the client side -
 628     created from result sets.
 629    </para>
 630    <synopsis>
 631      void ZOOM_resultset_records (ZOOM_resultset r,
 632                                   ZOOM_record *recs,
 633                                   size_t start, size_t count);
 634      ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
 635
 636      const char *ZOOM_record_get (ZOOM_record rec, const char *type,
 637                                   size_t *len);
 638
 639      ZOOM_record ZOOM_record_clone (ZOOM_record rec);
 640
 641      void ZOOM_record_destroy (ZOOM_record rec);
 642    </synopsis>
 643    <para>
 644     References to temporary records are returned by functions
 645     <function>ZOOM_resultset_records</function> or
 646     <function>ZOOM_resultset_record</function>.
 647     </para>
 648    <para>
 649     If a persistent reference to a record is desired
 650     <function>ZOOM_record_clone</function> should be used.
 651     It returns a record reference that should be destroyed
 652     by a call to <function>ZOOM_record_destroy</function>.
 653    </para>
 654    <para>
 655     A single record is returned by function
 656     <function>ZOOM_resultset_record</function> that takes a
 657     position as argument. First record has position zero.
 658     If no record could be obtained <literal>NULL</literal> is returned.
 659    </para>
 660    <para>
 661     Function <function>ZOOM_resultset_records</function> retrieves
 662     a number of records from a result set. Parameter <literal>start</literal>
 663     and <literal>count</literal> specifies the range of records to
 664     be returned. Upon completion array
 665     <literal>recs[0], ..recs[count-1]</literal>
 666     holds record objects for the records. The array of records
 667      <literal>recs</literal> should be allocated prior the call
 668     <function>ZOOM_resultset_records</function>. Note that for those
 669     records that couldn't be retrieved from the target
 670     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
 671    </para>
 672    <para id="zoom.record.get">
 673     In order to extract information about a single record,
 674     <function>ZOOM_record_get</function> is provided. The
 675     function returns a pointer to certain record information. The
 676     nature (type) of the pointer depends on the parameter,
 677     <parameter>type</parameter>.
 678    </para>
 679    <para>
 680     The <parameter>type</parameter> is a string of the format:
 681    </para>
 682    <para>
 683     <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
 684    </para>
 685    <para>
 686     where <replaceable>form</replaceable> specifies the format of the
 687     returned record, <replaceable>from</replaceable>
 688     specifies the character set of the record in its original form
 689     (as returned by the server), <replaceable>to</replaceable> specifies
 690     the output (returned)
 691     character set encoding.
 692     If charset is not given, then no character set conversion takes place.
 693     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
 694    </para>
 695    <para>
 696     In addition, for certain types, the length
 697     <literal>len</literal> passed will be set to the size in bytes of
 698     the returned information.
 699     </para>
 700    <para>
 701     The following are the supported values for <replaceable>form</replaceable>.
 702     <variablelist>
 703      <varlistentry><term><literal>database</literal></term>
 704       <listitem><para>Database of record is returned
 705         as a C null-terminated string. Return type
 706         <literal>const char *</literal>.
 707        </para></listitem>
 708      </varlistentry>
 709      <varlistentry><term><literal>syntax</literal></term>
 710       <listitem><para>The transfer syntax of the record is returned
 711         as a C null-terminated string containing the symbolic name of
 712         the record syntax, e.g. <literal>Usmarc</literal>. Return type
 713         is
 714         <literal>const char *</literal>.
 715        </para></listitem>
 716      </varlistentry>
 717      <varlistentry><term><literal>render</literal></term>
 718       <listitem><para>The record is returned in a display friendly
 719         format. Upon completion buffer is returned
 720         (type <literal>const char *</literal>) and length is stored in
 721         <literal>*len</literal>.
 722        </para></listitem>
 723      </varlistentry>
 724      <varlistentry><term><literal>raw</literal></term>
 725       <listitem><para>The record is returned in the internal
 726         YAZ specific format. For GRS-1, Explain, and others, the
 727         raw data is returned as type
 728         <literal>Z_External *</literal> which is just the type for
 729         the member <literal>retrievalRecord</literal> in
 730         type <literal>NamePlusRecord</literal>.
 731         For SUTRS and octet aligned record (including all MARCs) the
 732         octet buffer is returned and the length of the buffer.
 733        </para></listitem>
 734      </varlistentry>
 735      <varlistentry><term><literal>xml</literal></term>
 736       <listitem><para>The record is returned in XML if possible.
 737         SRU and Z39.50 records with transfer syntax XML are
 738         returned verbatim. MARC records are returned in
 739         <ulink url="&url.marcxml;">
 740          MARCXML
 741          </ulink>
 742         (converted from ISO2709 to MARCXML by YAZ).
 743         GRS-1 and OPAC records are not supported for this form.
 744         Upon completion, the XML buffer is returned
 745         (type <literal>const char *</literal>) and length is stored in
 746         <literal>*len</literal>.
 747        </para></listitem>
 748      </varlistentry>
 749      <varlistentry><term><literal>opac</literal></term>
 750       <listitem><para>OPAC for record is returned in XML.
 751        </para></listitem>
 752      </varlistentry>
 753     </variablelist>
 754    </para>
 755    <para>
 756     Most
 757     <ulink url="&url.marc21;">MARC21</ulink>
 758     records uses the
 759     <ulink url="&url.marc8;">MARC-8</ulink>
 760     character set encoding.
 761     An application that wishes to display in Latin-1 would use
 762     <screen>
 763      render; charset=marc8,iso-8859-1
 764     </screen>
 765    </para>
 766    <sect2 id="zoom.z3950.record.behavior">
 767     <title>Z39.50 Protocol behavior</title>
 768     <para>
 769      The functions <function>ZOOM_resultset_record</function> and
 770      <function>ZOOM_resultset_records</function> inspects the client-side
 771      record cache. Records not found in cache are fetched using
 772      Present.
 773      The functions may block (and perform network I/O)  - even though option
 774      <literal>async</literal> is 1, because they return records objects.
 775      (and there's no way to return records objects without retrieving them!).
 776      </para>
 777     <para>
 778      There is a trick, however, in the usage of function
 779      <function>ZOOM_resultset_records</function> that allows for
 780      delayed retrieval (and makes it non-blocking). By using
 781      a null pointer for <parameter>recs</parameter> you're indicating
 782      you're not interested in getting records objects
 783      <emphasis>now</emphasis>.
 784     </para>
 785    </sect2>
 786    <sect2 id="zoom.sru.record.behavior">
 787     <title>SRU Protocol behavior</title>
 788     <para>
 789      The ZOOM driver for SRU treats records returned by a SRU server
 790      as if they where Z39.50 records with transfer syntax XML and
 791      no element set name or database name.
 792     </para>
 793    </sect2>
 794   </sect1>
 795   <sect1 id="zoom.scan"><title>Scan</title>
 796    <para>
 797     This section describes an interface for Scan. Scan is not an
 798     official part of the ZOOM model yet. The result of a scan operation
 799     is the <literal>ZOOM_scanset</literal> which is a set of terms
 800     returned by a target.
 801    </para>
 802
 803    <para>
 804     The Scan interface is Z39.50 only. SRW version 1.0 does not
 805     support this.
 806    </para>
 807
 808    <synopsis>
 809     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
 810                                       const char *startpqf);
 811
 812     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 813
 814     const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
 815                                    int *occ, size_t *len);
 816
 817     const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
 818                                            int *occ, size_t *len);
 819
 820     void ZOOM_scanset_destroy (ZOOM_scanset scan);
 821
 822     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
 823                                          const char *key);
 824
 825     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
 826                                  const char *val);
 827     </synopsis>
 828    <para>
 829     The scan set is created by function
 830     <function>ZOOM_connection_scan</function> which performs a scan
 831     operation on the connection using the specified
 832     <parameter>startpqf</parameter>.
 833     If the operation was successful, the size of the scan set can be
 834     retrieved by a call to <function>ZOOM_scanset_size</function>.
 835     Like result sets, the items are numbered 0,..size-1.
 836     To obtain information about a particular scan term, call function
 837     <function>ZOOM_scanset_term</function>. This function takes
 838     a scan set offset <literal>pos</literal> and returns a pointer
 839     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
 840     non-present.
 841     If present, the <literal>occ</literal> and <literal>len</literal>
 842     are set to the number of occurrences and the length
 843     of the actual term respectively.
 844     <function>ZOOM_scanset_display_term</function> is similar to
 845     <function>ZOOM_scanset_term</function> except that it returns
 846     the <emphasis>display term</emphasis> rather than the raw term.
 847     In a few cases, the term is different from display term. Always
 848     use the display term for display and the raw term for subsequent
 849     scan operations (to get more terms, next scan result, etc).
 850    </para>
 851    <para>
 852     A scan set may be freed by a call to function
 853     <function>ZOOM_scanset_destroy</function>.
 854     Functions <function>ZOOM_scanset_option_get</function> and
 855     <function>ZOOM_scanset_option_set</function> retrieves and sets
 856     an option respectively.
 857    </para>
 858
 859    <para>
 860     The <parameter>startpqf</parameter> is a subset of PQF, namely
 861     the Attributes+Term part. Multiple <literal>@attr</literal> can
 862     be used. For example to scan in title (complete) phrases:
 863     <literallayout>
 864      @attr 1=4 @attr 6=2 "science o"
 865     </literallayout>
 866    </para>
 867
 868    <table frame="top" id="zoom.scanset.options">
 869     <title>ZOOM Scan Set Options</title>
 870     <tgroup cols="3">
 871      <colspec colwidth="4*" colname="name"></colspec>
 872      <colspec colwidth="7*" colname="description"></colspec>
 873      <colspec colwidth="2*" colname="default"></colspec>
 874      <thead>
 875       <row>
 876        <entry>Option</entry>
 877        <entry>Description</entry>
 878        <entry>Default</entry>
 879       </row>
 880      </thead>
 881      <tbody>
 882       <row><entry>
 883         number</entry><entry>Number of Scan Terms requested in next scan.
 884         After scan it holds the actual number of terms returned.
 885        </entry><entry>10</entry></row>
 886       <row><entry>
 887         position</entry><entry>Preferred Position of term in response
 888         in next scan; actual position after completion of scan.
 889        </entry><entry>1</entry></row>
 890       <row><entry>
 891         stepSize</entry><entry>Step Size
 892        </entry><entry>0</entry></row>
 893       <row><entry>
 894         scanStatus</entry><entry>An integer indicating the Scan Status
 895         of last scan.
 896        </entry><entry>0</entry></row>
 897      </tbody>
 898     </tgroup>
 899    </table>
 900   </sect1>
 901
 902   <sect1 id="zoom.extendedservices"><title>Extended Services</title>
 903    <para>
 904     ZOOM offers an interface to a subset of the Z39.50 extended services
 905     as well as a few privately defined ones:
 906    </para>
 907    <itemizedlist>
 908     <listitem>
 909      <para>
 910       Z39.50 Item Order (ILL).
 911       See <xref linkend="zoom.item.order"/>.
 912      </para>
 913     </listitem>
 914     <listitem>
 915      <para>
 916       Record Update. This allows a client to insert, modify or delete
 917       records.
 918       See <xref linkend="zoom.record.update"/>.
 919      </para>
 920     </listitem>
 921     <listitem>
 922      <para>
 923       Database Create. This a non-standard feature. Allows a client
 924       to create a database.
 925       See <xref linkend="zoom.database.create"/>.
 926      </para>
 927     </listitem>
 928     <listitem>
 929      <para>
 930       Database Drop. This a non-standard feature. Allows a client
 931       to delete/drop a database.
 932       See <xref linkend="zoom.database.drop"/>.
 933      </para>
 934      </listitem>
 935     <listitem>
 936      <para>
 937       Commit operation. This a non-standard feature. Allows a client
 938       to commit operations.
 939       See <xref linkend="zoom.commit"/>.
 940      </para>
 941     </listitem>
 942     <!-- all the ILL PDU options should go here too -->
 943    </itemizedlist>
 944    <para>
 945     To create an extended service operation a <literal>ZOOM_package</literal>
 946     must be created. The operation is a five step operation. The
 947     package is created, package is configured by means of options,
 948     the package is send, result is inspected (by means of options),
 949     the package is destroyed.
 950    </para>
 951    <synopsis>
 952     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
 953                                          ZOOM_options options);
 954
 955     const char *ZOOM_package_option_get(ZOOM_package p,
 956                                         const char *key);
 957     void ZOOM_package_option_set(ZOOM_package p, const char *key,
 958                                  const char *val);
 959     void ZOOM_package_send(ZOOM_package p, const char *type);
 960
 961     void ZOOM_package_destroy(ZOOM_package p);
 962    </synopsis>
 963    <para>
 964     The <function>ZOOM_connection_package</function> creates a
 965     package for the connection given using the options specified.
 966    </para>
 967    <para>
 968     Functions <function>ZOOM_package_option_get</function> and
 969     <function>ZOOM_package_option_set</function> gets and sets
 970     options.
 971    </para>
 972    <para>
 973     <function>ZOOM_package_send</function> sends
 974     the package the via connection specified in
 975     <function>ZOOM_connection_package</function>.
 976     The <parameter>type</parameter> specifies the actual extended service
 977     package type to be sent.
 978    </para>
 979
 980    <table frame="top" id="zoom.extendedservices.options">
 981     <title>Extended Service Common Options</title>
 982     <tgroup cols="3">
 983      <colspec colwidth="4*" colname="name"></colspec>
 984      <colspec colwidth="7*" colname="description"></colspec>
 985      <colspec colwidth="3*" colname="default"></colspec>
 986      <thead>
 987       <row>
 988        <entry>Option</entry>
 989        <entry>Description</entry>
 990        <entry>Default</entry>
 991       </row>
 992      </thead>
 993      <tbody>
 994       <row>
 995        <entry>package-name</entry>
 996        <entry>Extended Service Request package name. Must be specified
 997        as part of a request</entry>
 998        <entry>none</entry>
 999       </row>
1000       <row>
1001        <entry>user-id</entry>
1002        <entry>User ID of Extended Service Package. Is a request option</entry>
1003        <entry>none</entry>
1004       </row>
1005       <row>
1006        <entry>function</entry>
1007        <entry>
1008         Function of package - one of <literal>create</literal>,
1009         <literal>delete</literal>, <literal>modify</literal>. Is
1010         a request option.
1011        </entry>
1012        <entry><literal>create</literal></entry>
1013       </row>
1014       <row>
1015        <entry>targetReference</entry>
1016        <entry>
1017         Target Reference. This is part of the response as returned
1018         by the server. Read it after a succesful operation.
1019        </entry>
1020        <entry><literal>none</literal></entry>
1021       </row>
1022      </tbody>
1023     </tgroup>
1024    </table>
1025
1026    <sect2 id="zoom.item.order"><title>Item Order</title>
1027     <para>
1028      For Item Order, type must be set to <literal>itemorder</literal> in
1029      <function>ZOOM_package_send</function>.
1030     </para>
1031
1032     <table frame="top" id="zoom.item.order.options">
1033      <title>Item Order Options</title>
1034      <tgroup cols="3">
1035       <colspec colwidth="4*" colname="name"></colspec>
1036       <colspec colwidth="7*" colname="description"></colspec>
1037       <colspec colwidth="3*" colname="default"></colspec>
1038       <thead>
1039        <row>
1040         <entry>Option</entry>
1041         <entry>Description</entry>
1042         <entry>Default</entry>
1043        </row>
1044       </thead>
1045       <tbody>
1046        <row>
1047         <entry>contact-name</entry>
1048         <entry>ILL contact name</entry>
1049         <entry>none</entry>
1050        </row>
1051        <row>
1052         <entry>contact-phone</entry>
1053         <entry>ILL contact phone</entry>
1054         <entry>none</entry>
1055        </row>
1056        <row>
1057         <entry>contact-email</entry>
1058         <entry>ILL contact email</entry>
1059         <entry>none</entry>
1060        </row>
1061        <row>
1062         <entry>itemorder-item</entry>
1063         <entry>Position for item (record) requested. An integer</entry>
1064         <entry>1</entry>
1065        </row>
1066       </tbody>
1067      </tgroup>
1068     </table>
1069
1070    </sect2>
1071
1072    <sect2 id="zoom.record.update"><title>Record Update</title>
1073     <para>
1074      For Record Update, type must be set to <literal>update</literal> in
1075      <function>ZOOM_package_send</function>.
1076     </para>
1077
1078     <table frame="top" id="zoom.record.update.options">
1079      <title>Record Update Options</title>
1080      <tgroup cols="3">
1081       <colspec colwidth="4*" colname="name"></colspec>
1082       <colspec colwidth="7*" colname="description"></colspec>
1083       <colspec colwidth="3*" colname="default"></colspec>
1084       <thead>
1085        <row>
1086         <entry>Option</entry>
1087         <entry>Description</entry>
1088         <entry>Default</entry>
1089        </row>
1090       </thead>
1091       <tbody>
1092        <row>
1093         <entry>action</entry>
1094         <entry>
1095          The update action. One of
1096          <literal>specialUpdate</literal>,
1097          <literal>recordInsert</literal>,
1098          <literal>recordReplace</literal>,
1099          <literal>recordDelete</literal>,
1100          <literal>elementUpdate</literal>.
1101         </entry>
1102         <entry><literal>specialUpdate</literal></entry>
1103        </row>
1104        <row>
1105         <entry>recordIdOpaque</entry>
1106         <entry>Opaque Record ID</entry>
1107         <entry>none</entry>
1108        </row>
1109        <row>
1110         <entry>recordIdNumber</entry>
1111         <entry>Record ID number</entry>
1112         <entry>none</entry>
1113        </row>
1114        <row>
1115         <entry>record</entry>
1116         <entry>The record itself</entry>
1117         <entry>none</entry>
1118        </row>
1119        <row>
1120         <entry>syntax</entry>
1121         <entry>The record syntax (transfer syntax). Is a string that
1122          is a known record syntax.
1123         </entry>
1124         <entry>no syntax</entry>
1125        </row>
1126        <row>
1127         <entry>databaseName</entry>
1128         <entry>Database from connection object</entry>
1129         <entry>Default</entry>
1130        </row>
1131       </tbody>
1132      </tgroup>
1133     </table>
1134
1135    </sect2>
1136
1137    <sect2 id="zoom.database.create"><title>Database Create</title>
1138     <para>
1139      For Database Create, type must be set to <literal>create</literal> in
1140      <function>ZOOM_package_send</function>.
1141     </para>
1142
1143     <table frame="top" id="zoom.database.create.options">
1144      <title>Database Create Options</title>
1145      <tgroup cols="3">
1146       <colspec colwidth="4*" colname="name"></colspec>
1147       <colspec colwidth="7*" colname="description"></colspec>
1148       <colspec colwidth="3*" colname="default"></colspec>
1149       <thead>
1150        <row>
1151         <entry>Option</entry>
1152         <entry>Description</entry>
1153         <entry>Default</entry>
1154        </row>
1155       </thead>
1156       <tbody>
1157        <row>
1158         <entry>databaseName</entry>
1159         <entry>Database from connection object</entry>
1160         <entry>Default</entry>
1161        </row>
1162       </tbody>
1163      </tgroup>
1164     </table>
1165    </sect2>
1166
1167    <sect2 id="zoom.database.drop"><title>Database Drop</title>
1168     <para>
1169      For Database Drop, type must be set to <literal>drop</literal> in
1170      <function>ZOOM_package_send</function>.
1171     </para>
1172
1173     <table frame="top" id="zoom.database.drop.options">
1174      <title>Database Drop Options</title>
1175      <tgroup cols="3">
1176       <colspec colwidth="4*" colname="name"></colspec>
1177       <colspec colwidth="7*" colname="description"></colspec>
1178       <colspec colwidth="3*" colname="default"></colspec>
1179       <thead>
1180        <row>
1181         <entry>Option</entry>
1182         <entry>Description</entry>
1183         <entry>Default</entry>
1184        </row>
1185       </thead>
1186       <tbody>
1187        <row>
1188         <entry>databaseName</entry>
1189         <entry>Database from connection object</entry>
1190         <entry>Default</entry>
1191        </row>
1192       </tbody>
1193      </tgroup>
1194     </table>
1195    </sect2>
1196
1197    <sect2 id="zoom.commit"><title>Commit Operation</title>
1198     <para>
1199      For Commit, type must be set to <literal>commit</literal> in
1200      <function>ZOOM_package_send</function>.
1201     </para>
1202    </sect2>
1203
1204    <sect2 id="zoom.extended.services.behavior">
1205     <title>Protocol behavior</title>
1206     <para>
1207      All the extended services are Z39.50-only.
1208     </para>
1209     <note>
1210      <para>
1211       The database create, drop and commit services are privately defined
1212       operations.
1213       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1214       definitions.
1215      </para>
1216     </note>
1217    </sect2>
1218   </sect1>
1219
1220   <sect1 id="zoom.options"><title>Options</title>
1221    <para>
1222     Most &zoom; objects provide a way to specify options to change behavior.
1223     From an implementation point of view a set of options is just like
1224     an associative array / hash.
1225    </para>
1226    <synopsis>
1227      ZOOM_options ZOOM_options_create (void);
1228
1229      ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1230
1231      void ZOOM_options_destroy (ZOOM_options opt);
1232    </synopsis>
1233    <synopsis>
1234      const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1235
1236      void ZOOM_options_set (ZOOM_options opt, const char *name,
1237                             const char *v);
1238    </synopsis>
1239    <synopsis>
1240      typedef const char *(*ZOOM_options_callback)
1241                                      (void *handle, const char *name);
1242
1243      ZOOM_options_callback
1244              ZOOM_options_set_callback (ZOOM_options opt,
1245                                         ZOOM_options_callback c,
1246                                         void *handle);
1247    </synopsis>
1248   </sect1>
1249   <sect1 id="zoom.events"><title>Events</title>
1250    <para>
1251     If you're developing non-blocking applications, you have to deal
1252     with events.
1253    </para>
1254    <synopsis>
1255     int ZOOM_event (int no, ZOOM_connection *cs);
1256    </synopsis>
1257    <para>
1258     The <function>ZOOM_event</function> executes pending events for
1259     a number of connections. Supply the number of connections in
1260     <literal>no</literal> and an array of connections in
1261     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1262     A pending event could be a sending a search, receiving a response,
1263     etc.
1264     When an event has occurred for one of the connections, this function
1265     returns a positive integer <literal>n</literal> denoting that an event
1266     occurred for connection <literal>cs[n-1]</literal>.
1267     When no events are pending for the connections, a value of zero is
1268     returned.
1269     To ensure that all outstanding requests are performed call this function
1270     repeatedly until zero is returned.
1271    </para>
1272    <para>
1273     If <function>ZOOM_event</function> returns and returns non-zero, the
1274     last event that occurred can be expected.
1275    </para>
1276    <synopsis>
1277     int ZOOM_connection_last_event(ZOOM_connection cs);
1278    </synopsis>
1279    <para>
1280     <function>ZOOM_connection_last_event</function> returns an event type
1281     (integer) for the last event.
1282    </para>
1283
1284    <table frame="top" id="zoom.event.ids">
1285     <title>ZOOM Event IDs</title>
1286     <tgroup cols="2">
1287      <colspec colwidth="4*" colname="name"></colspec>
1288      <colspec colwidth="7*" colname="description"></colspec>
1289      <thead>
1290       <row>
1291        <entry>Event</entry>
1292        <entry>Description</entry>
1293       </row>
1294      </thead>
1295      <tbody>
1296       <row>
1297        <entry>ZOOM_EVENT_NONE</entry>
1298        <entry>No event has occurred</entry>
1299       </row>
1300       <row>
1301        <entry>ZOOM_EVENT_CONNECT</entry>
1302        <entry>TCP/IP connect has initiated</entry>
1303       </row>
1304       <row>
1305        <entry>ZOOM_EVENT_SEND_DATA</entry>
1306        <entry>Data has been transmitted (sending)</entry>
1307       </row>
1308       <row>
1309        <entry>ZOOM_EVENT_RECV_DATA</entry>
1310        <entry>Data has been received)</entry>
1311       </row>
1312       <row>
1313        <entry>ZOOM_EVENT_TIMEOUT</entry>
1314        <entry>Timeout</entry>
1315       </row>
1316       <row>
1317        <entry>ZOOM_EVENT_UNKNOWN</entry>
1318        <entry>Unknown event</entry>
1319       </row>
1320       <row>
1321        <entry>ZOOM_EVENT_SEND_APDU</entry>
1322        <entry>An APDU has been transmitted (sending)</entry>
1323       </row>
1324       <row>
1325        <entry>ZOOM_EVENT_RECV_APDU</entry>
1326        <entry>An APDU has been received</entry>
1327       </row>
1328       <row>
1329        <entry>ZOOM_EVENT_RECV_RECORD</entry>
1330        <entry>A result-set record has been received</entry>
1331       </row>
1332       <row>
1333        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1334        <entry>A search result been received</entry>
1335       </row>
1336      </tbody>
1337     </tgroup>
1338    </table>
1339   </sect1>
1340  </chapter>
1341
1342  <!-- Keep this comment at the end of the file
1343  Local variables:
1344  mode: sgml
1345  sgml-omittag:t
1346  sgml-shorttag:t
1347  sgml-minimize-attributes:nil
1348  sgml-always-quote-attributes:t
1349  sgml-indent-step:1
1350  sgml-indent-data:t
1351  sgml-parent-document: "yaz.xml"
1352  sgml-local-catalogs: nil
1353  sgml-namecase-general:t
1354  End:
1355  -->
1356