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