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