doc/zoom.xml

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