dependencies/yaz_3.0.14/doc/zoom.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 3. ZOOM</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="index.html" title="YAZ User's Guide and Reference"><link rel="prev" href="installation.win32.html" title="3. WIN32"><link rel="next" href="zoom.query.html" title="2. Queries"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. ZOOM</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="installation.win32.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="zoom.query.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="zoom"></a>Chapter 3. ZOOM</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="zoom.html#zoom-connections">1. Connections</a></span></dt><dd><dl><dt><span class="sect2"><a href="zoom.html#zoom-connection-z39.50">1.1. Z39.50 Protocol behavior</a></span></dt><dt><span class="sect2"><a href="zoom.html#zoom.sru.init.behavior">1.2. SRU Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.query.html">2. Queries</a></span></dt><dd><dl><dt><span class="sect2"><a href="zoom.query.html#zoom.sort.behavior">2.1. Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.resultsets.html">3. Result sets</a></span></dt><dd><dl><dt><span class="sect2"><a href="zoom.resultsets.html#zoom.z3950.resultset.behavior">3.1. Z39.50 Protocol behavior</a></span></dt><dt><span class="sect2"><a href="zoom.resultsets.html#zoom.sru.resultset.behavior">3.2. SRU Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.records.html">4. Records</a></span></dt><dd><dl><dt><span class="sect2"><a href="zoom.records.html#zoom.z3950.record.behavior">4.1. Z39.50 Protocol behavior</a></span></dt><dt><span class="sect2"><a href="zoom.records.html#zoom.sru.record.behavior">4.2. SRU Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.scan.html">5. Scan</a></span></dt><dt><span class="sect1"><a href="zoom.extendedservices.html">6. Extended Services</a></span></dt><dd><dl><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.item.order">6.1. Item Order</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.record.update">6.2. Record Update</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.database.create">6.3. Database Create</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.database.drop">6.4. Database Drop</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.commit">6.5. Commit Operation</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.extended.services.behavior">6.6. Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.options.html">7. Options</a></span></dt><dt><span class="sect1"><a href="zoom.events.html">8. Events</a></span></dt></dl></div><p>
   2     <acronym class="acronym">ZOOM</acronym> is an acronym for 'Z39.50 Object-Orientation Model' and is
   3    an initiative started by Mike Taylor (Mike is from the UK, which
   4    explains the peculiar name of the model). The goal of <acronym class="acronym">ZOOM</acronym> is to
   5    provide a common Z39.50 client API not bound to a particular
   6    programming language or toolkit.
   7   </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
   8     A recent addition to YAZ is SRU support. You can now make
   9     SRU ZOOM connections by specifying scheme <code class="literal">http://</code>
  10     for the hostname for a connection.  The dialect of SRU used is
  11     specified by the value of the connection's <code class="literal">sru</code>
  12     option, which may be SRU over HTTP GET (<code class="literal">get</code>),
  13     SRU over HTTP POST (<code class="literal">post</code>) or SRW (SRU over
  14     SOAP) (<code class="literal">soap</code>).  Using the facility for embedding
  15     options in target strings, a connection can be forced to use SRU
  16     rather the SRW (the default) by prefixing the target string with
  17     <code class="literal">sru=get,</code>, like this:
  18     <code class="literal">sru=get,http://sru.miketaylor.org.uk:80/sru.pl</code>
  19    </p></div><p>
  20    The lack of a simple Z39.50 client API for YAZ has become more
  21    and more apparent over time. So when the first <acronym class="acronym">ZOOM</acronym> specification
  22    became available,
  23    an implementation for YAZ was quickly developed. For the first time, it is
  24    now as easy (or easier!) to develop clients than servers with YAZ. This
  25    chapter describes the <acronym class="acronym">ZOOM</acronym> C binding. Before going further, please
  26    reconsider whether C is the right programming language for the job.
  27    There are other language bindings available for YAZ, and still
  28    more
  29    are in active development. See the
  30    <a class="ulink" href="http://zoom.z3950.org/" target="_top">ZOOM web-site</a> for
  31    more information.
  32   </p><p>
  33    In order to fully understand this chapter you should read and
  34    try the example programs <code class="literal">zoomtst1.c</code>,
  35    <code class="literal">zoomtst2.c</code>, .. in the <code class="literal">zoom</code>
  36    directory.
  37   </p><p>
  38    The C language misses features found in object oriented languages
  39    such as C++, Java, etc. For example, you'll have to manually,
  40    destroy all objects you create, even though you may think of them as
  41    temporary. Most objects has a <code class="literal">_create</code> - and a
  42    <code class="literal">_destroy</code> variant.
  43    All objects are in fact pointers to internal stuff, but you don't see
  44    that because of typedefs. All destroy methods should gracefully ignore a
  45    <code class="literal">NULL</code> pointer.
  46   </p><p>
  47    In each of the sections below you'll find a sub section called
  48    protocol behavior, that describes how the API maps to the Z39.50
  49    protocol.
  50   </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="zoom-connections"></a>1. Connections</h2></div></div></div><p>The Connection object is a session with a target.
  51    </p><pre class="synopsis">
  52     #include &lt;yaz/zoom.h&gt;
  53
  54     ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
  55
  56     ZOOM_connection ZOOM_connection_create (ZOOM_options options);
  57
  58     void ZOOM_connection_connect(ZOOM_connection c, const char *host,
  59                                  int portnum);
  60     void ZOOM_connection_destroy (ZOOM_connection c);
  61    </pre><p>
  62     Connection objects are created with either function
  63     <code class="function">ZOOM_connection_new</code> or
  64     <code class="function">ZOOM_connection_create</code>.
  65     The former creates and automatically attempts to establish a network
  66     connection with the target. The latter doesn't establish
  67     a connection immediately, thus allowing you to specify options
  68     before establishing network connection using the function
  69     <code class="function">ZOOM_connection_connect</code>.
  70     If the port number, <code class="literal">portnum</code>, is zero, the
  71     <code class="literal">host</code> is consulted for a port specification.
  72     If no port is given, 210 is used. A colon denotes the beginning of
  73     a port number in the host string. If the host string includes a
  74     slash, the following part specifies a database for the connection.
  75    </p><p>
  76     You can prefix the host with a scheme followed by colon. The
  77     default scheme is <code class="literal">tcp</code> (Z39.50 protocol).
  78     The scheme <code class="literal">http</code> selects SRU over HTTP.
  79    </p><p>
  80     You can prefix the scheme-qualified host-string with one or more
  81     comma-separated
  82     <code class="literal"><em class="parameter"><code>key</code></em>=<em class="parameter"><code>value</code></em></code>
  83     sequences, each of which represents an option to be set into the
  84     connection structure <span class="emphasis"><em>before</em></span> the
  85     protocol-level connection is forged and the initialization
  86     handshake takes place.  This facility can be used to provide
  87     authentication credentials, as in host-strings such as:
  88     <code class="literal">user=admin,password=halfAm4n,tcp:localhost:8017/db</code>
  89    </p><p>
  90     Connection objects should be destroyed using the function
  91     <code class="function">ZOOM_connection_destroy</code>.
  92    </p><pre class="synopsis">
  93     void ZOOM_connection_option_set(ZOOM_connection c,
  94                                     const char *key, const char *val);
  95
  96     void ZOOM_connection_option_setl(ZOOM_connection c,
  97                                      const char *key,
  98                                      const char *val, int len);
  99
 100     const char *ZOOM_connection_option_get(ZOOM_connection c,
 101                                            const char *key);
 102     const char *ZOOM_connection_option_getl(ZOOM_connection c,
 103                                             const char *key,
 104                                             int *lenp);
 105    </pre><p>
 106     The functions <code class="function">ZOOM_connection_option_set</code> and
 107     <code class="function">ZOOM_connection_option_setl</code> allows you to
 108     set an option given by <em class="parameter"><code>key</code></em> to the value
 109     <em class="parameter"><code>value</code></em> for the connection.
 110     For <code class="function">ZOOM_connection_option_set</code>, the
 111     value is assumed to be a 0-terminated string. Function
 112     <code class="function">ZOOM_connection_option_setl</code> specifies a
 113     value of a certain size (len).
 114    </p><p>
 115     Functions <code class="function">ZOOM_connection_option_get</code> and
 116     <code class="function">ZOOM_connection_option_getl</code> returns
 117     the value for an option given by <em class="parameter"><code>key</code></em>.
 118    </p><div class="table"><a name="zoom-connection-options"></a><p class="title"><b>Table 3.1. ZOOM Connection Options</b></p><div class="table-contents"><table summary="ZOOM Connection Options" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td>
 119         implementationName</td><td>Name of Your client
 120        </td><td>none</td></tr><tr><td>
 121         user</td><td>Authentication user name
 122        </td><td>none</td></tr><tr><td>
 123         group</td><td>Authentication group name
 124        </td><td>none</td></tr><tr><td>
 125         password</td><td>Authentication password.
 126        </td><td>none</td></tr><tr><td>
 127         host</td><td>Target host. This setting is "read-only".
 128         It's automatically set internally when connecting to a target.
 129        </td><td>none</td></tr><tr><td>
 130         proxy</td><td>Proxy host
 131        </td><td>none</td></tr><tr><td>
 132         async</td><td>If true (1) the connection operates in
 133         asynchronous operation which means that all calls are non-blocking
 134         except
 135         <a class="link" href="zoom.events.html" title="8. Events"><code class="function">ZOOM_event</code></a>.
 136        </td><td>0</td></tr><tr><td>
 137         maximumRecordSize</td><td> Maximum size of single record.
 138        </td><td>1 MB</td></tr><tr><td>
 139         preferredMessageSize</td><td> Maximum size of multiple records.
 140        </td><td>1 MB</td></tr><tr><td>
 141         lang</td><td> Language for negotiation.
 142        </td><td>none</td></tr><tr><td>
 143         charset</td><td> Character set for negotiation.
 144        </td><td>none</td></tr><tr><td>
 145         serverImplementationId</td><td>
 146         Implementation ID of server.  (The old targetImplementationId
 147         option is also supported for the benefit of old applications.)
 148        </td><td>none</td></tr><tr><td>
 149         targetImplementationName</td><td>
 150         Implementation Name of server.  (The old
 151         targetImplementationName option is also supported for the
 152         benefit of old applications.)
 153        </td><td>none</td></tr><tr><td>
 154         serverImplementationVersion</td><td>
 155         Implementation Version of server.  (the old
 156         targetImplementationVersion option is also supported for the
 157         benefit of old applications.)
 158        </td><td>none</td></tr><tr><td>
 159         databaseName</td><td>One or more database names
 160         separated by character plus (<code class="literal">+</code>), which to
 161         be used by subsequent search requests on this Connection.
 162        </td><td>Default</td></tr><tr><td>
 163         piggyback</td><td>True (1) if piggyback should be
 164         used in searches; false (0) if not.
 165        </td><td>1</td></tr><tr><td>
 166         smallSetUpperBound</td><td>If hits is less than or equal to this
 167         value, then target will return all records using small element set name
 168        </td><td>0</td></tr><tr><td>
 169         largeSetLowerBound</td><td>If hits is greater than this
 170         value, the target will return no records.
 171        </td><td>1</td></tr><tr><td>
 172         mediumSetPresentNumber</td><td>This value represents
 173         the number of records to be returned as part of a search when when
 174         hits is less than or equal to large set lower bound and if hits
 175         is greater than small set upper bound.
 176        </td><td>0</td></tr><tr><td>
 177         smallSetElementSetName</td><td>
 178         The element set name to be used for small result sets.
 179        </td><td>none</td></tr><tr><td>
 180         mediumSetElementSetName</td><td>
 181         The element set name to be for medium-sized result sets.
 182        </td><td>none</td></tr><tr><td>
 183         init_opt_search, init_opt_present, init_opt_delSet, etc.</td><td>
 184         After a successful Init, these options may be interrogated to
 185         discover whether the server claims to support the specified
 186         operations.
 187        </td><td>none</td></tr><tr><td>
 188         sru_version</td><td>
 189         SRU/SRW version. Should be <code class="literal">1.1</code>, or
 190         <code class="literal">1.2</code>. This is , prior to connect, the version
 191         to offer (highest version). And following connect (in fact
 192         first operation), holds the negotiated version with the server
 193         (same or lower version).
 194        </td><td>1.2</td></tr></tbody></table></div></div><br class="table-break"><p>
 195     If either option <code class="literal">lang</code> or <code class="literal">charset</code>
 196     is set, then
 197     <a class="ulink" href="http://www.loc.gov/z3950/agency/defns/charneg-3.html" target="_top">
 198      Character Set and Language Negotiation</a> is in effect.
 199    </p><pre class="synopsis">
 200      int ZOOM_connection_error (ZOOM_connection c, const char **cp,
 201                                 const char **addinfo);
 202      int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
 203                                   const char **addinfo, const char **dset);
 204    </pre><p>
 205     Function <code class="function">ZOOM_connection_error</code> checks for
 206     errors for the last operation(s) performed. The function returns
 207     zero if no errors occurred; non-zero otherwise indicating the error.
 208     Pointers <em class="parameter"><code>cp</code></em> and <em class="parameter"><code>addinfo</code></em>
 209     holds messages for the error and additional-info if passed as
 210     non-<code class="literal">NULL</code>. Function
 211     <code class="function">ZOOM_connection_error_x</code> is an extended version
 212     of <code class="function">ZOOM_connection_error</code> that is capable of
 213     returning name of diagnostic set in <em class="parameter"><code>dset</code></em>.
 214    </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom-connection-z39.50"></a>1.1. Z39.50 Protocol behavior</h3></div></div></div><p>
 215      The calls <code class="function">ZOOM_connection_new</code> and
 216      <code class="function">ZOOM_connection_connect</code> establishes a TCP/IP
 217       connection and sends an Initialize Request to the target if
 218       possible. In addition, the calls waits for an Initialize Response
 219       from the target and the result is inspected (OK or rejected).
 220     </p><p>
 221      If <code class="literal">proxy</code> is set then the client will establish
 222      a TCP/IP connection with the peer as specified by the
 223      <code class="literal">proxy</code> host and the hostname as part of the
 224      connect calls will be set as part of the Initialize Request.
 225      The proxy server will then "forward" the PDU's transparently
 226      to the target behind the proxy.
 227     </p><p>
 228      For the authentication parameters, if option <code class="literal">user</code>
 229      is set and both options <code class="literal">group</code> and
 230      <code class="literal">pass</code> are unset, then Open style
 231      authentication is used (Version 2/3) in which case the username
 232      is usually followed by a slash, then by a password.
 233      If either <code class="literal">group</code>
 234      or <code class="literal">pass</code> is set then idPass authentication
 235      (Version 3 only) is used. If none of the options are set, no
 236      authentication parameters are set as part of the Initialize Request
 237      (obviously).
 238     </p><p>
 239      When option <code class="literal">async</code> is 1, it really means that
 240      all network operations are postponed (and queued) until the
 241      function <code class="literal">ZOOM_event</code> is invoked. When doing so
 242      it doesn't make sense to check for errors after
 243      <code class="literal">ZOOM_connection_new</code> is called since that
 244      operation "connecting - and init" is still incomplete and the
 245      API cannot tell the outcome (yet).
 246     </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.sru.init.behavior"></a>1.2. SRU Protocol behavior</h3></div></div></div><p>
 247      The SRU protocol doesn't feature an Inititialize Request, so
 248      the connection phase merely establishes a TCP/IP connection
 249      with the SOAP service.
 250     </p><p>Most of the ZOOM connection options do not
 251      affect SRU and they are ignored. However, future versions
 252      of YAZ might honor <code class="literal">implementationName</code> and
 253      put that as part of User-Agent header for HTTP requests.
 254      </p><p>
 255      The <code class="literal">charset</code> is used in the Content-Type header
 256      of HTTP requests.
 257     </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installation.win32.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="zoom.query.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. WIN32 </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2. Queries</td></tr></table></div></body></html>