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.51 2006-09-06 09:26:36 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><title>SRU Protocol behavior</title>
 322     <para>
 323      The SRU protocol doesn't feature an Inititialize Request, so
 324      the connection phase merely establishes a TCP/IP connection
 325      with the SOAP service.
 326     </para>
 327     <para>Most of the ZOOM connection options do not
 328      affect SRU and they are ignored. However, future versions
 329      of &yaz; might honor <literal>implementationName</literal> and
 330      put that as part of User-Agent header for HTTP requests.
 331      </para>
 332     <para>
 333      The <literal>charset</literal> is used in the Content-Type header
 334      of HTTP requests.
 335     </para>
 336    </sect2>
 337   </sect1>
 338   <sect1 id="zoom.query"><title>Queries</title>
 339    <para>
 340     Query objects represents queries.
 341    </para>
 342    <synopsis>
 343      ZOOM_query ZOOM_query_create(void);
 344
 345      void ZOOM_query_destroy(ZOOM_query q);
 346
 347      int ZOOM_query_prefix(ZOOM_query q, const char *str);
 348
 349      int ZOOM_query_cql(ZOOM_query s, const char *str);
 350
 351      int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
 352    </synopsis>
 353    <para>
 354     Create query objects using <function>ZOOM_query_create</function>
 355     and destroy them by calling <function>ZOOM_query_destroy</function>.
 356     RPN-queries can be specified in <link linkend="PQF">PQF</link>
 357     notation by using the
 358     function <function>ZOOM_query_prefix</function>.
 359     The <function>ZOOM_query_cql</function> specifies a CQL
 360     query to be sent to the server/target.
 361     More query types will be added in future versions of &yaz;, such as
 362     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
 363     etc. In addition to a search, a sort criteria may be set. Function
 364     <function>ZOOM_query_sortby</function> specifies a
 365     sort criteria using the same string notation for sort as offered by
 366     the <link linkend="sortspec">YAZ client</link>.
 367    </para>
 368    <sect2><title>Protocol behavior</title>
 369     <para>
 370      The query object is just an interface for the member Query
 371      in the SearchRequest. The sortby-function is an interface to the
 372      sortSequence member of the SortRequest.
 373     </para>
 374    </sect2>
 375   </sect1>
 376   <sect1 id="zoom.resultsets"><title>Result sets</title>
 377    <para>
 378     The result set object is a container for records returned from
 379     a target.
 380    </para>
 381    <synopsis>
 382      ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
 383                                            ZOOM_query q);
 384
 385      ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
 386                                                const char *q);
 387
 388      void ZOOM_resultset_destroy(ZOOM_resultset r);
 389    </synopsis>
 390    <para>
 391     Function <function>ZOOM_connection_search</function> creates
 392      a result set given a connection and query.
 393     Destroy a result set by calling
 394     <function>ZOOM_resultset_destroy</function>.
 395     Simple clients may using PQF only may use function
 396     <function>ZOOM_connection_search_pqf</function> in which case
 397     creating query objects is not necessary.
 398    </para>
 399    <synopsis>
 400      void ZOOM_resultset_option_set (ZOOM_resultset r,
 401                                       const char *key,
 402                                       const char *val);
 403
 404      const char *ZOOM_resultset_option_get (ZOOM_resultset r,
 405                                              const char *key);
 406
 407      size_t ZOOM_resultset_size (ZOOM_resultset r);
 408    </synopsis>
 409    <para>
 410     Functions <function>ZOOM_resultset_options_set</function> and
 411     <function>ZOOM_resultset_get</function> sets and gets an option
 412     for a result set similar to <function>ZOOM_connection_option_get</function>
 413     and <function>ZOOM_connection_option_set</function>.
 414    </para>
 415    <para>
 416     The number of hits also called result-count is returned by
 417     function <function>ZOOM_resultset_size</function>.
 418    </para>
 419    <table frame="top"><title>ZOOM Result set Options</title>
 420     <tgroup cols="3">
 421      <colspec colwidth="4*" colname="name"></colspec>
 422      <colspec colwidth="7*" colname="description"></colspec>
 423      <colspec colwidth="2*" colname="default"></colspec>
 424      <thead>
 425       <row>
 426        <entry>Option</entry>
 427        <entry>Description</entry>
 428        <entry>Default</entry>
 429       </row>
 430      </thead>
 431      <tbody>
 432       <row><entry>
 433         start</entry><entry>Offset of first record to be
 434         retrieved from target. First record has offset 0 unlike the
 435         protocol specifications where first record has position 1.
 436        </entry><entry>0</entry></row>
 437       <row><entry>
 438         count</entry><entry>Number of records to be retrieved.
 439        </entry><entry>0</entry></row>
 440       <row><entry>
 441         presentChunk</entry><entry>The number of records to be
 442         requested from the server in each chunk (present requst).  The
 443         value 0 means to request all the records in a single chunk.
 444         (The old <literal>step</literal>
 445         option is also supported for the benefit of old applications.)
 446        </entry><entry>0</entry></row>
 447       <row><entry>
 448         elementSetName</entry><entry>Element-Set name of records.
 449         Most targets should honor element set name <literal>B</literal>
 450         and <literal>F</literal> for brief and full respectively.
 451        </entry><entry>none</entry></row>
 452       <row><entry>
 453         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
 454         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
 455        </entry><entry>none</entry></row>
 456       <row><entry>
 457         schema</entry><entry>Schema for retrieval, such as
 458         <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
 459        </entry><entry>none</entry></row>
 460       <row><entry>
 461         setname</entry><entry>Name of Result Set (Result Set ID).
 462         If this option isn't set, the ZOOM module will automatically
 463         allocate a result set name.
 464        </entry><entry>default</entry></row>
 465      </tbody>
 466     </tgroup>
 467    </table>
 468    <para>
 469     For servers that support Search Info report, the following
 470     options may be read using <function>ZOOM_resultset_get</function>.
 471     This detailed information is read after a successful search has
 472     completed.
 473    </para>
 474    <para>
 475     This information is a list of of items, where each item is
 476     information about a term or subquery. All items in the list
 477     are prefixed by
 478     <literal>SearchResult.</literal><replaceable>no</replaceable>
 479     where no presents the item number (0=first, 1=second).
 480     Read <literal>searchresult.size</literal> to determine the
 481     number of items.
 482    </para>
 483    <table frame="top"><title>Search Info Report options</title>
 484     <tgroup cols="2">
 485      <colspec colwidth="4*" colname="name"></colspec>
 486      <colspec colwidth="7*" colname="description"></colspec>
 487      <thead>
 488       <row>
 489        <entry>Option</entry>
 490        <entry>Description</entry>
 491       </row>
 492      </thead>
 493      <tbody>
 494       <row>
 495        <entry>searchresult.size</entry>
 496        <entry>
 497         number of search result entries. This option is-nonexistant
 498         if no entries are returned by the server.
 499        </entry>
 500       </row>
 501       <row>
 502        <entry>searchresult.<replaceable>no</replaceable>.id</entry>
 503        <entry>sub query ID</entry>
 504       </row>
 505       <row>
 506        <entry>searchresult.<replaceable>no</replaceable>.count</entry>
 507        <entry>result count for item (number of hits)</entry>
 508       </row>
 509       <row>
 510        <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
 511        <entry>subquery term</entry>
 512       </row>
 513       <row>
 514        <entry>
 515         searchresult.<replaceable>no</replaceable>.interpretation.term
 516        </entry>
 517        <entry>interpretation term</entry>
 518       </row>
 519       <row>
 520        <entry>
 521         searchresult.<replaceable>no</replaceable>.recommendation.term
 522        </entry>
 523        <entry>recommendation term</entry>
 524       </row>
 525      </tbody>
 526     </tgroup>
 527    </table>
 528    <sect2>
 529     <title>Z39.50 Protocol behavior</title>
 530     <para>
 531      The creation of a result set involves at least a SearchRequest
 532      - SearchResponse protocol handshake. Following that, if a sort
 533      criteria was specified as part of the query, a SortRequest -
 534      SortResponse handshake takes place. Note that it is necessary to
 535      perform sorting before any retrieval takes place, so no records will
 536      be returned from the target as part of the SearchResponse because these
 537      would be unsorted. Hence, piggyback is disabled when sort criteria
 538      are set. Following Search - and a possible sort - Retrieval takes
 539      place - as one or more Present Requests/Response pairs being
 540      transferred.
 541      </para>
 542     <para>
 543      The API allows for two different modes for retrieval. A high level
 544      mode which is somewhat more powerful and a low level one.
 545      The low level is enabled when searching on a Connection object
 546      for which the settings
 547      <literal>smallSetUpperBound</literal>,
 548      <literal>mediumSetPresentNumber</literal> and
 549      <literal>largeSetLowerBound</literal> are set. The low level mode
 550      thus allows you to precisely set how records are returned as part
 551      of a search response as offered by the Z39.50 protocol.
 552      Since the client may be retrieving records as part of the
 553      search response, this mode doesn't work well if sorting is used.
 554      </para>
 555     <para>
 556      The high-level mode allows you to fetch a range of records from
 557      the result set with a given start offset. When you use this mode
 558      the client will automatically use piggyback if that is possible
 559      with the target and perform one or more present requests as needed.
 560      Even if the target returns fewer records as part of a present response
 561      because of a record size limit, etc. the client will repeat sending
 562      present requests. As an example, if option <literal>start</literal>
 563      is 0 (default) and <literal>count</literal> is 4, and
 564      <literal>piggyback</literal> is 1 (default) and no sorting criteria
 565      is specified, then the client will attempt to retrieve the 4
 566      records as part the search response (using piggyback). On the other
 567      hand, if either <literal>start</literal> is positive or if
 568      a sorting criteria is set, or if <literal>piggyback</literal>
 569      is 0, then the client will not perform piggyback but send Present
 570      Requests instead.
 571     </para>
 572     <para>
 573      If either of the options <literal>mediumSetElementSetName</literal> and
 574      <literal>smallSetElementSetName</literal> are unset, the value
 575      of option <literal>elementSetName</literal> is used for piggyback
 576      searches. This means that for the high-level mode you only have
 577      to specify one elementSetName option rather than three.
 578      </para>
 579    </sect2>
 580    <sect2>
 581     <title>SRU Protocol behavior</title>
 582     <para>
 583      Current version of &yaz; does not take advantage of a result set id
 584      returned by the SRU server. Future versions might do, however.
 585      Since, the ZOOM driver does not save result set IDs any
 586      present (retrieval) is transformed to a SRU SearchRetrieveRequest
 587      with same query but, possibly, different offsets.
 588     </para>
 589     <para>
 590      Option <literal>schema</literal> specifies SRU schema
 591      for retrieval. However, options <literal>elementSetName</literal> and
 592      <literal>preferredRecordSyntax</literal> are ignored.
 593     </para>
 594     <para>
 595      Options <literal>start</literal> and <literal>count</literal>
 596      are supported by SRU.
 597      The remaining options
 598      <literal>piggyback</literal>,
 599      <literal>smallSetUpperBound</literal>,
 600      <literal>largeSetLowerBound</literal>,
 601      <literal>mediumSetPresentNumber</literal>,
 602      <literal>mediumSetElementSetName</literal>,
 603       <literal>smallSetElementSetName</literal> are
 604      unsupported.
 605     </para>
 606     <para>
 607      SRU supports CQL queries, <emphasis>not</emphasis> PQF.
 608      If PQF is used, however, the PQF query is transferred anyway
 609      using non-standard element <literal>pQuery</literal> in
 610      SRU SearchRetrieveRequest.
 611     </para>
 612     <para>
 613      Unfortunately, SRU does not define a database setting. Hence,
 614      <literal>databaseName</literal> is unsupported and ignored.
 615      However, the path part in host parameter for functions
 616      <function>ZOOM_connecton_new</function> and
 617      <function>ZOOM_connection_connect</function> acts as a
 618      database (at least for the &yaz; SRU server).
 619     </para>
 620    </sect2>
 621   </sect1>
 622   <sect1 id="zoom.records"><title>Records</title>
 623    <para>
 624     A record object is a retrieval record on the client side -
 625     created from result sets.
 626    </para>
 627    <synopsis>
 628      void ZOOM_resultset_records (ZOOM_resultset r,
 629                                   ZOOM_record *recs,
 630                                   size_t start, size_t count);
 631      ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
 632
 633      const char *ZOOM_record_get (ZOOM_record rec, const char *type,
 634                                   size_t *len);
 635
 636      ZOOM_record ZOOM_record_clone (ZOOM_record rec);
 637
 638      void ZOOM_record_destroy (ZOOM_record rec);
 639    </synopsis>
 640    <para>
 641     References to temporary records are returned by functions
 642     <function>ZOOM_resultset_records</function> or
 643     <function>ZOOM_resultset_record</function>.
 644     </para>
 645    <para>
 646     If a persistent reference to a record is desired
 647     <function>ZOOM_record_clone</function> should be used.
 648     It returns a record reference that should be destroyed
 649     by a call to <function>ZOOM_record_destroy</function>.
 650    </para>
 651    <para>
 652     A single record is returned by function
 653     <function>ZOOM_resultset_record</function> that takes a
 654     position as argument. First record has position zero.
 655     If no record could be obtained <literal>NULL</literal> is returned.
 656    </para>
 657    <para>
 658     Function <function>ZOOM_resultset_records</function> retrieves
 659     a number of records from a result set. Parameter <literal>start</literal>
 660     and <literal>count</literal> specifies the range of records to
 661     be returned. Upon completion array
 662     <literal>recs[0], ..recs[count-1]</literal>
 663     holds record objects for the records. The array of records
 664      <literal>recs</literal> should be allocated prior the call
 665     <function>ZOOM_resultset_records</function>. Note that for those
 666     records that couldn't be retrieved from the target
 667     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
 668    </para>
 669    <para id="zoom.record.get">
 670     In order to extract information about a single record,
 671     <function>ZOOM_record_get</function> is provided. The
 672     function returns a pointer to certain record information. The
 673     nature (type) of the pointer depends on the parameter,
 674     <parameter>type</parameter>.
 675    </para>
 676    <para>
 677     The <parameter>type</parameter> is a string of the format:
 678    </para>
 679    <para>
 680     <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
 681    </para>
 682    <para>
 683     where <replaceable>form</replaceable> specifies the format of the
 684     returned record, <replaceable>from</replaceable>
 685     specifies the character set of the record in its original form
 686     (as returned by the server), <replaceable>to</replaceable> specifies
 687     the output (returned)
 688     character set encoding.
 689     If charset is not given, then no character set conversion takes place.
 690     If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
 691    </para>
 692    <para>
 693     In addition, for certain types, the length
 694     <literal>len</literal> passed will be set to the size in bytes of
 695     the returned information.
 696     </para>
 697    <para>
 698     The following are the supported values for <replaceable>form</replaceable>.
 699     <variablelist>
 700      <varlistentry><term><literal>database</literal></term>
 701       <listitem><para>Database of record is returned
 702         as a C null-terminated string. Return type
 703         <literal>const char *</literal>.
 704        </para></listitem>
 705      </varlistentry>
 706      <varlistentry><term><literal>syntax</literal></term>
 707       <listitem><para>The transfer syntax of the record is returned
 708         as a C null-terminated string containing the symbolic name of
 709         the record syntax, e.g. <literal>Usmarc</literal>. Return type
 710         is
 711         <literal>const char *</literal>.
 712        </para></listitem>
 713      </varlistentry>
 714      <varlistentry><term><literal>render</literal></term>
 715       <listitem><para>The record is returned in a display friendly
 716         format. Upon completion buffer is returned
 717         (type <literal>const char *</literal>) and length is stored in
 718         <literal>*len</literal>.
 719        </para></listitem>
 720      </varlistentry>
 721      <varlistentry><term><literal>raw</literal></term>
 722       <listitem><para>The record is returned in the internal
 723         YAZ specific format. For GRS-1, Explain, and others, the
 724         raw data is returned as type
 725         <literal>Z_External *</literal> which is just the type for
 726         the member <literal>retrievalRecord</literal> in
 727         type <literal>NamePlusRecord</literal>.
 728         For SUTRS and octet aligned record (including all MARCs) the
 729         octet buffer is returned and the length of the buffer.
 730        </para></listitem>
 731      </varlistentry>
 732      <varlistentry><term><literal>xml</literal></term>
 733       <listitem><para>The record is returned in XML if possible.
 734         SRU and Z39.50 records with transfer syntax XML are
 735         returned verbatim. MARC records are returned in
 736         <ulink url="&url.marcxml;">
 737          MARCXML
 738          </ulink>
 739         (converted from ISO2709 to MARCXML by YAZ).
 740         GRS-1 and OPAC records are not supported for this form.
 741         Upon completion, the XML buffer is returned
 742         (type <literal>const char *</literal>) and length is stored in
 743         <literal>*len</literal>.
 744        </para></listitem>
 745      </varlistentry>
 746      <varlistentry><term><literal>opac</literal></term>
 747       <listitem><para>OPAC for record is returned in XML.
 748        </para></listitem>
 749      </varlistentry>
 750     </variablelist>
 751    </para>
 752    <para>
 753     Most
 754     <ulink url="&url.marc21;">MARC21</ulink>
 755     records uses the
 756     <ulink url="&url.marc8;">MARC-8</ulink>
 757     character set encoding.
 758     An application that wishes to display in Latin-1 would use
 759     <screen>
 760      render; charset=marc8,iso-8859-1
 761     </screen>
 762    </para>
 763    <sect2><title>Z39.50 Protocol behavior</title>
 764     <para>
 765      The functions <function>ZOOM_resultset_record</function> and
 766      <function>ZOOM_resultset_records</function> inspects the client-side
 767      record cache. Records not found in cache are fetched using
 768      Present.
 769      The functions may block (and perform network I/O)  - even though option
 770      <literal>async</literal> is 1, because they return records objects.
 771      (and there's no way to return records objects without retrieving them!).
 772      </para>
 773     <para>
 774      There is a trick, however, in the usage of function
 775      <function>ZOOM_resultset_records</function> that allows for
 776      delayed retrieval (and makes it non-blocking). By using
 777      a null pointer for <parameter>recs</parameter> you're indicating
 778      you're not interested in getting records objects
 779      <emphasis>now</emphasis>.
 780     </para>
 781    </sect2>
 782    <sect2><title>SRU Protocol behavior</title>
 783     <para>
 784      The ZOOM driver for SRU treats records returned by a SRU server
 785      as if they where Z39.50 records with transfer syntax XML and
 786      no element set name or database name.
 787     </para>
 788    </sect2>
 789   </sect1>
 790   <sect1 id="zoom.scan"><title>Scan</title>
 791    <para>
 792     This section describes an interface for Scan. Scan is not an
 793     official part of the ZOOM model yet. The result of a scan operation
 794     is the <literal>ZOOM_scanset</literal> which is a set of terms
 795     returned by a target.
 796    </para>
 797
 798    <para>
 799     The Scan interface is Z39.50 only. SRW version 1.0 does not
 800     support this.
 801    </para>
 802
 803    <synopsis>
 804     ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
 805                                       const char *startpqf);
 806
 807     size_t ZOOM_scanset_size(ZOOM_scanset scan);
 808
 809     const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
 810                                    int *occ, size_t *len);
 811
 812     const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
 813                                            int *occ, size_t *len);
 814
 815     void ZOOM_scanset_destroy (ZOOM_scanset scan);
 816
 817     const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
 818                                          const char *key);
 819
 820     void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
 821                                  const char *val);
 822     </synopsis>
 823    <para>
 824     The scan set is created by function
 825     <function>ZOOM_connection_scan</function> which performs a scan
 826     operation on the connection using the specified
 827     <parameter>startpqf</parameter>.
 828     If the operation was successful, the size of the scan set can be
 829     retrieved by a call to <function>ZOOM_scanset_size</function>.
 830     Like result sets, the items are numbered 0,..size-1.
 831     To obtain information about a particular scan term, call function
 832     <function>ZOOM_scanset_term</function>. This function takes
 833     a scan set offset <literal>pos</literal> and returns a pointer
 834     to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
 835     non-present.
 836     If present, the <literal>occ</literal> and <literal>len</literal>
 837     are set to the number of occurrences and the length
 838     of the actual term respectively.
 839     <function>ZOOM_scanset_display_term</function> is similar to
 840     <function>ZOOM_scanset_term</function> except that it returns
 841     the <emphasis>display term</emphasis> rather than the raw term.
 842     In a few cases, the term is different from display term. Always
 843     use the display term for display and the raw term for subsequent
 844     scan operations (to get more terms, next scan result, etc).
 845    </para>
 846    <para>
 847     A scan set may be freed by a call to function
 848     <function>ZOOM_scanset_destroy</function>.
 849     Functions <function>ZOOM_scanset_option_get</function> and
 850     <function>ZOOM_scanset_option_set</function> retrieves and sets
 851     an option respectively.
 852    </para>
 853
 854    <para>
 855     The <parameter>startpqf</parameter> is a subset of PQF, namely
 856     the Attributes+Term part. Multiple <literal>@attr</literal> can
 857     be used. For example to scan in title (complete) phrases:
 858     <literallayout>
 859      @attr 1=4 @attr 6=2 "science o"
 860     </literallayout>
 861    </para>
 862
 863    <table frame="top"><title>ZOOM Scan Set Options</title>
 864     <tgroup cols="3">
 865      <colspec colwidth="4*" colname="name"></colspec>
 866      <colspec colwidth="7*" colname="description"></colspec>
 867      <colspec colwidth="2*" colname="default"></colspec>
 868      <thead>
 869       <row>
 870        <entry>Option</entry>
 871        <entry>Description</entry>
 872        <entry>Default</entry>
 873       </row>
 874      </thead>
 875      <tbody>
 876       <row><entry>
 877         number</entry><entry>Number of Scan Terms requested in next scan.
 878         After scan it holds the actual number of terms returned.
 879        </entry><entry>10</entry></row>
 880       <row><entry>
 881         position</entry><entry>Preferred Position of term in response
 882         in next scan; actual position after completion of scan.
 883        </entry><entry>1</entry></row>
 884       <row><entry>
 885         stepSize</entry><entry>Step Size
 886        </entry><entry>0</entry></row>
 887       <row><entry>
 888         scanStatus</entry><entry>An integer indicating the Scan Status
 889         of last scan.
 890        </entry><entry>0</entry></row>
 891      </tbody>
 892     </tgroup>
 893    </table>
 894   </sect1>
 895
 896   <sect1 id="zoom.ext"><title>Extended Services</title>
 897    <para>
 898     ZOOM offers an interface to a subset of the Z39.50 extended services
 899     as well as a few privately defined ones:
 900    </para>
 901    <itemizedlist>
 902     <listitem>
 903      <para>
 904       Z39.50 Item Order (ILL).
 905       See <xref linkend="zoom.ext.itemorder"/>.
 906      </para>
 907     </listitem>
 908     <listitem>
 909      <para>
 910       Record Update. This allows a client to insert, modify or delete
 911       records.
 912       See <xref linkend="zoom.ext.update"/>.
 913      </para>
 914     </listitem>
 915     <listitem>
 916      <para>
 917       Database Create. This a non-standard feature. Allows a client
 918       to create a database.
 919       See <xref linkend="zoom.ext.dbcreate"/>.
 920      </para>
 921     </listitem>
 922     <listitem>
 923      <para>
 924       Database Drop. This a non-standard feature. Allows a client
 925       to delete/drop a database.
 926       See <xref linkend="zoom.ext.dbdrop"/>.
 927      </para>
 928      </listitem>
 929     <listitem>
 930      <para>
 931       Commit operation. This a non-standard feature. Allows a client
 932       to commit operations.
 933       See <xref linkend="zoom.ext.commit"/>.
 934      </para>
 935     </listitem>
 936     <!-- all the ILL PDU options should go here too -->
 937    </itemizedlist>
 938    <para>
 939     To create an extended service operation a <literal>ZOOM_package</literal>
 940     must be created. The operation is a five step operation. The
 941     package is created, package is configured by means of options,
 942     the package is send, result is inspected (by means of options),
 943     the package is destroyed.
 944    </para>
 945    <synopsis>
 946     ZOOM_package ZOOM_connection_package(ZOOM_connection c,
 947                                          ZOOM_options options);
 948
 949     const char *ZOOM_package_option_get(ZOOM_package p,
 950                                         const char *key);
 951     void ZOOM_package_option_set(ZOOM_package p, const char *key,
 952                                  const char *val);
 953     void ZOOM_package_send(ZOOM_package p, const char *type);
 954
 955     void ZOOM_package_destroy(ZOOM_package p);
 956    </synopsis>
 957    <para>
 958     The <function>ZOOM_connection_package</function> creates a
 959     package for the connection given using the options specified.
 960    </para>
 961    <para>
 962     Functions <function>ZOOM_package_option_get</function> and
 963     <function>ZOOM_package_option_set</function> gets and sets
 964     options.
 965    </para>
 966    <para>
 967     <function>ZOOM_package_send</function> sends
 968     the package the via connection specified in
 969     <function>ZOOM_connection_package</function>.
 970     The <parameter>type</parameter> specifies the actual extended service
 971     package type to be sent.
 972    </para>
 973
 974    <table frame="top"><title>Extended Service Common Options</title>
 975     <tgroup cols="3">
 976      <colspec colwidth="4*" colname="name"></colspec>
 977      <colspec colwidth="7*" colname="description"></colspec>
 978      <colspec colwidth="3*" colname="default"></colspec>
 979      <thead>
 980       <row>
 981        <entry>Option</entry>
 982        <entry>Description</entry>
 983        <entry>Default</entry>
 984       </row>
 985      </thead>
 986      <tbody>
 987       <row>
 988        <entry>package-name</entry>
 989        <entry>Extended Service Request package name. Must be specified
 990        as part of a request</entry>
 991        <entry>none</entry>
 992       </row>
 993       <row>
 994        <entry>user-id</entry>
 995        <entry>User ID of Extended Service Package. Is a request option</entry>
 996        <entry>none</entry>
 997       </row>
 998       <row>
 999        <entry>function</entry>
1000        <entry>
1001         Function of package - one of <literal>create</literal>,
1002         <literal>delete</literal>, <literal>modify</literal>. Is
1003         a request option.
1004        </entry>
1005        <entry><literal>create</literal></entry>
1006       </row>
1007       <row>
1008        <entry>targetReference</entry>
1009        <entry>
1010         Target Reference. This is part of the response as returned
1011         by the server. Read it after a succesful operation.
1012        </entry>
1013        <entry><literal>none</literal></entry>
1014       </row>
1015      </tbody>
1016     </tgroup>
1017    </table>
1018
1019    <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
1020     <para>
1021      For Item Order, type must be set to <literal>itemorder</literal> in
1022      <function>ZOOM_package_send</function>.
1023     </para>
1024
1025     <table frame="top"><title>Item Order Options</title>
1026      <tgroup cols="3">
1027       <colspec colwidth="4*" colname="name"></colspec>
1028       <colspec colwidth="7*" colname="description"></colspec>
1029       <colspec colwidth="3*" colname="default"></colspec>
1030       <thead>
1031        <row>
1032         <entry>Option</entry>
1033         <entry>Description</entry>
1034         <entry>Default</entry>
1035        </row>
1036       </thead>
1037       <tbody>
1038        <row>
1039         <entry>contact-name</entry>
1040         <entry>ILL contact name</entry>
1041         <entry>none</entry>
1042        </row>
1043        <row>
1044         <entry>contact-phone</entry>
1045         <entry>ILL contact phone</entry>
1046         <entry>none</entry>
1047        </row>
1048        <row>
1049         <entry>contact-email</entry>
1050         <entry>ILL contact email</entry>
1051         <entry>none</entry>
1052        </row>
1053        <row>
1054         <entry>itemorder-item</entry>
1055         <entry>Position for item (record) requested. An integer</entry>
1056         <entry>1</entry>
1057        </row>
1058       </tbody>
1059      </tgroup>
1060     </table>
1061
1062    </sect2>
1063
1064    <sect2 id="zoom.ext.update"><title>Record Update</title>
1065     <para>
1066      For Record Update, type must be set to <literal>update</literal> in
1067      <function>ZOOM_package_send</function>.
1068     </para>
1069
1070     <table frame="top"><title>Record Update Options</title>
1071      <tgroup cols="3">
1072       <colspec colwidth="4*" colname="name"></colspec>
1073       <colspec colwidth="7*" colname="description"></colspec>
1074       <colspec colwidth="3*" colname="default"></colspec>
1075       <thead>
1076        <row>
1077         <entry>Option</entry>
1078         <entry>Description</entry>
1079         <entry>Default</entry>
1080        </row>
1081       </thead>
1082       <tbody>
1083        <row>
1084         <entry>action</entry>
1085         <entry>
1086          The update action. One of
1087          <literal>specialUpdate</literal>,
1088          <literal>recordInsert</literal>,
1089          <literal>recordReplace</literal>,
1090          <literal>recordDelete</literal>,
1091          <literal>elementUpdate</literal>.
1092         </entry>
1093         <entry><literal>specialUpdate</literal></entry>
1094        </row>
1095        <row>
1096         <entry>recordIdOpaque</entry>
1097         <entry>Opaque Record ID</entry>
1098         <entry>none</entry>
1099        </row>
1100        <row>
1101         <entry>recordIdNumber</entry>
1102         <entry>Record ID number</entry>
1103         <entry>none</entry>
1104        </row>
1105        <row>
1106         <entry>record</entry>
1107         <entry>The record itself</entry>
1108         <entry>none</entry>
1109        </row>
1110        <row>
1111         <entry>syntax</entry>
1112         <entry>The record syntax (transfer syntax). Is a string that
1113          is a known record syntax.
1114         </entry>
1115         <entry>no syntax</entry>
1116        </row>
1117        <row>
1118         <entry>databaseName</entry>
1119         <entry>Database from connection object</entry>
1120         <entry>Default</entry>
1121        </row>
1122       </tbody>
1123      </tgroup>
1124     </table>
1125
1126    </sect2>
1127
1128    <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
1129     <para>
1130      For Database Create, type must be set to <literal>create</literal> in
1131      <function>ZOOM_package_send</function>.
1132     </para>
1133
1134     <table frame="top"><title>Database Create Options</title>
1135      <tgroup cols="3">
1136       <colspec colwidth="4*" colname="name"></colspec>
1137       <colspec colwidth="7*" colname="description"></colspec>
1138       <colspec colwidth="3*" colname="default"></colspec>
1139       <thead>
1140        <row>
1141         <entry>Option</entry>
1142         <entry>Description</entry>
1143         <entry>Default</entry>
1144        </row>
1145       </thead>
1146       <tbody>
1147        <row>
1148         <entry>databaseName</entry>
1149         <entry>Database from connection object</entry>
1150         <entry>Default</entry>
1151        </row>
1152       </tbody>
1153      </tgroup>
1154     </table>
1155    </sect2>
1156
1157    <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
1158     <para>
1159      For Database Drop, type must be set to <literal>drop</literal> in
1160      <function>ZOOM_package_send</function>.
1161     </para>
1162
1163     <table frame="top"><title>Database Create Options</title>
1164      <tgroup cols="3">
1165       <colspec colwidth="4*" colname="name"></colspec>
1166       <colspec colwidth="7*" colname="description"></colspec>
1167       <colspec colwidth="3*" colname="default"></colspec>
1168       <thead>
1169        <row>
1170         <entry>Option</entry>
1171         <entry>Description</entry>
1172         <entry>Default</entry>
1173        </row>
1174       </thead>
1175       <tbody>
1176        <row>
1177         <entry>databaseName</entry>
1178         <entry>Database from connection object</entry>
1179         <entry>Default</entry>
1180        </row>
1181       </tbody>
1182      </tgroup>
1183     </table>
1184    </sect2>
1185
1186    <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
1187     <para>
1188      For Commit, type must be set to <literal>commit</literal> in
1189      <function>ZOOM_package_send</function>.
1190     </para>
1191    </sect2>
1192
1193    <sect2><title>Protocol behavior</title>
1194     <para>
1195      All the extended services are Z39.50-only.
1196     </para>
1197     <note>
1198      <para>
1199       The database create, drop and commit services are privately defined
1200       operations.
1201       Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1202       definitions.
1203      </para>
1204     </note>
1205    </sect2>
1206   </sect1>
1207
1208   <sect1 id="zoom.options"><title>Options</title>
1209    <para>
1210     Most &zoom; objects provide a way to specify options to change behavior.
1211     From an implementation point of view a set of options is just like
1212     an associative array / hash.
1213    </para>
1214    <synopsis>
1215      ZOOM_options ZOOM_options_create (void);
1216
1217      ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1218
1219      void ZOOM_options_destroy (ZOOM_options opt);
1220    </synopsis>
1221    <synopsis>
1222      const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1223
1224      void ZOOM_options_set (ZOOM_options opt, const char *name,
1225                             const char *v);
1226    </synopsis>
1227    <synopsis>
1228      typedef const char *(*ZOOM_options_callback)
1229                                      (void *handle, const char *name);
1230
1231      ZOOM_options_callback
1232              ZOOM_options_set_callback (ZOOM_options opt,
1233                                         ZOOM_options_callback c,
1234                                         void *handle);
1235    </synopsis>
1236   </sect1>
1237   <sect1 id="zoom.events"><title>Events</title>
1238    <para>
1239     If you're developing non-blocking applications, you have to deal
1240     with events.
1241    </para>
1242    <synopsis>
1243     int ZOOM_event (int no, ZOOM_connection *cs);
1244    </synopsis>
1245    <para>
1246     The <function>ZOOM_event</function> executes pending events for
1247     a number of connections. Supply the number of connections in
1248     <literal>no</literal> and an array of connections in
1249     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1250     A pending event could be a sending a search, receiving a response,
1251     etc.
1252     When an event has occurred for one of the connections, this function
1253     returns a positive integer <literal>n</literal> denoting that an event
1254     occurred for connection <literal>cs[n-1]</literal>.
1255     When no events are pending for the connections, a value of zero is
1256     returned.
1257     To ensure that all outstanding requests are performed call this function
1258     repeatedly until zero is returned.
1259    </para>
1260    <para>
1261     If <function>ZOOM_event</function> returns and returns non-zero, the
1262     last event that occurred can be expected.
1263    </para>
1264    <synopsis>
1265     int ZOOM_connection_last_event(ZOOM_connection cs);
1266    </synopsis>
1267    <para>
1268     <function>ZOOM_connection_last_event</function> returns an event type
1269     (integer) for the last event.
1270    </para>
1271
1272    <table frame="top"><title>ZOOM Event IDs</title>
1273     <tgroup cols="2">
1274      <colspec colwidth="4*" colname="name"></colspec>
1275      <colspec colwidth="7*" colname="description"></colspec>
1276      <thead>
1277       <row>
1278        <entry>Event</entry>
1279        <entry>Description</entry>
1280       </row>
1281      </thead>
1282      <tbody>
1283       <row>
1284        <entry>ZOOM_EVENT_NONE</entry>
1285        <entry>No event has occurred</entry>
1286       </row>
1287       <row>
1288        <entry>ZOOM_EVENT_CONNECT</entry>
1289        <entry>TCP/IP connect has initiated</entry>
1290       </row>
1291       <row>
1292        <entry>ZOOM_EVENT_SEND_DATA</entry>
1293        <entry>Data has been transmitted (sending)</entry>
1294       </row>
1295       <row>
1296        <entry>ZOOM_EVENT_RECV_DATA</entry>
1297        <entry>Data has been received)</entry>
1298       </row>
1299       <row>
1300        <entry>ZOOM_EVENT_TIMEOUT</entry>
1301        <entry>Timeout</entry>
1302       </row>
1303       <row>
1304        <entry>ZOOM_EVENT_UNKNOWN</entry>
1305        <entry>Unknown event</entry>
1306       </row>
1307       <row>
1308        <entry>ZOOM_EVENT_SEND_APDU</entry>
1309        <entry>An APDU has been transmitted (sending)</entry>
1310       </row>
1311       <row>
1312        <entry>ZOOM_EVENT_RECV_APDU</entry>
1313        <entry>An APDU has been received</entry>
1314       </row>
1315       <row>
1316        <entry>ZOOM_EVENT_RECV_RECORD</entry>
1317        <entry>A result-set record has been received</entry>
1318       </row>
1319       <row>
1320        <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1321        <entry>A search result been received</entry>
1322       </row>
1323      </tbody>
1324     </tgroup>
1325    </table>
1326   </sect1>
1327  </chapter>
1328
1329  <!-- Keep this comment at the end of the file
1330  Local variables:
1331  mode: sgml
1332  sgml-omittag:t
1333  sgml-shorttag:t
1334  sgml-minimize-attributes:nil
1335  sgml-always-quote-attributes:t
1336  sgml-indent-step:1
1337  sgml-indent-data:t
1338  sgml-parent-document: "yaz.xml"
1339  sgml-local-catalogs: nil
1340  sgml-namecase-general:t
1341  End:
1342  -->
1343