doc/zoom.xml

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