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