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