doc/zoom.xml

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