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