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