node-zoom

<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.78.1"><link rel="home" 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.�Windows"><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"><div class="titlepage"><div><div><h1 class="title"><a name="zoom"></a>Chapter�3.�ZOOM</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><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/Solr Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.query.html">2. Queries</a></span></dt><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.sort">3.1. Z39.50 Result-set Sort</a></span></dt><dt><span class="sect2"><a href="zoom.resultsets.html#zoom.z3950.resultset.behavior">3.2. Z39.50 Protocol behavior</a></span></dt><dt><span class="sect2"><a href="zoom.resultsets.html#zoom.sru.resultset.behavior">3.3. 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/Solr Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.facets.html">5. Facets</a></span></dt><dt><span class="sect1"><a href="zoom.scan.html">6. Scan</a></span></dt><dt><span class="sect1"><a href="zoom.extendedservices.html">7. Extended Services</a></span></dt><dd><dl><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.item.order">7.1. Item Order</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.record.update">7.2. Record Update</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.database.create">7.3. Database Create</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.database.drop">7.4. Database Drop</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.commit">7.5. Commit Operation</a></span></dt><dt><span class="sect2"><a href="zoom.extendedservices.html#zoom.extended.services.behavior">7.6. Protocol behavior</a></span></dt></dl></dd><dt><span class="sect1"><a href="zoom.options.html">8. Options</a></span></dt><dt><span class="sect1"><a href="zoom.queryconversions.html">9. Query conversions</a></span></dt><dt><span class="sect1"><a href="zoom.events.html">10. Events</a></span></dt></dl></div><p> <acronym class="acronym">ZOOM</acronym> is an acronym for 'Z39.50 Object-Orientation Model' and is an initiative started by Mike Taylor (Mike is from the UK, which explains the peculiar name of the model). The goal of <acronym class="acronym">ZOOM</acronym> is to provide a common Z39.50 client API not bound to a particular programming language or toolkit. </p><p> From YAZ version 2.1.12, <a class="ulink" href="http://www.loc.gov/standards/sru/" target="_top">SRU</a> is supported. You can make SRU ZOOM connections by specifying scheme <code class="literal">http://</code> for the hostname for a connection. The dialect of SRU used is specified by the value of the connection's <code class="literal">sru</code> option, which may be SRU over HTTP GET (<code class="literal">get</code>), SRU over HTTP POST (<code class="literal">post</code>), (SRU over SOAP) (<code class="literal">soap</code>) or <code class="literal">solr</code> (<a class="ulink" href="http://lucene.apache.org/solr/" target="_top">Solr</a> Web Service). Using the facility for embedding options in target strings, a connection can be forced to use SRU rather the SRW (the default) by prefixing the target string with <code class="literal">sru=get,</code>, like this: <code class="literal">sru=get,http://sru.miketaylor.org.uk:80/sru.pl</code> </p><p> <a class="ulink" href="http://lucene.apache.org/solr/" target="_top">Solr</a> protocol support was added to YAZ in version 4.1.0, as a dialect of a SRU protocol, since both are HTTP based protocols. </p><p> The lack of a simple Z39.50 client API for YAZ has become more and more apparent over time. So when the first <acronym class="acronym">ZOOM</acronym> specification became available, an implementation for YAZ was quickly developed. For the first time, it is now as easy (or easier!) to develop clients than servers with YAZ. This chapter describes the <acronym class="acronym">ZOOM</acronym> C binding. Before going further, please reconsider whether C is the right programming language for the job. There are other language bindings available for YAZ, and still more are in active development. See the <a class="ulink" href="http://zoom.z3950.org/" target="_top">ZOOM web-site</a> for more information. </p><p> In order to fully understand this chapter you should read and try the example programs <code class="literal">zoomtst1.c</code>, <code class="literal">zoomtst2.c</code>, .. in the <code class="literal">zoom</code> directory. </p><p> The C language misses features found in object oriented languages such as C++, Java, etc. For example, you'll have to manually, destroy all objects you create, even though you may think of them as temporary. Most objects has a <code class="literal">_create</code> - and a <code class="literal">_destroy</code> variant. All objects are in fact pointers to internal stuff, but you don't see that because of typedefs. All destroy methods should gracefully ignore a <code class="literal">NULL</code> pointer. </p><p> In each of the sections below you'll find a sub section called protocol behavior, that describes how the API maps to the Z39.50 protocol. </p><div class="sect1"><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. </p><pre class="synopsis"> #include <yaz/zoom.h> ZOOM_connection ZOOM_connection_new(const char *host, int portnum); ZOOM_connection ZOOM_connection_create(ZOOM_options options); void ZOOM_connection_connect(ZOOM_connection c, const char *host, int portnum); void ZOOM_connection_destroy(ZOOM_connection c); </pre><p> Connection objects are created with either function <code class="function">ZOOM_connection_new</code> or <code class="function">ZOOM_connection_create</code>. The former creates and automatically attempts to establish a network connection with the target. The latter doesn't establish a connection immediately, thus allowing you to specify options before establishing network connection using the function <code class="function">ZOOM_connection_connect</code>. If the port number, <code class="literal">portnum</code>, is zero, the <code class="literal">host</code> is consulted for a port specification. If no port is given, 210 is used. A colon denotes the beginning of a port number in the host string. If the host string includes a slash, the following part specifies a database for the connection. </p><p> You can prefix the host with a scheme followed by colon. The default scheme is <code class="literal">tcp</code> (Z39.50 protocol). The scheme <code class="literal">http</code> selects SRU/get over HTTP by default, but can overridded to use SRU/post, SRW and the Solr protocol. </p><p> You can prefix the scheme-qualified host-string with one or more comma-separated <code class="literal"><em class="parameter"><code>key</code></em>=<em class="parameter"><code>value</code></em></code> sequences, each of which represents an option to be set into the connection structure <span class="emphasis"><em>before</em></span> the protocol-level connection is forged and the initialization handshake takes place. This facility can be used to provide authentication credentials, as in host-strings such as: <code class="literal">user=admin,password=halfAm4n,tcp:localhost:8017/db</code> </p><p> Connection objects should be destroyed using the function <code class="function">ZOOM_connection_destroy</code>. </p><pre class="synopsis"> void ZOOM_connection_option_set(ZOOM_connection c, const char *key, const char *val); void ZOOM_connection_option_setl(ZOOM_connection c, const char *key, const char *val, int len); const char *ZOOM_connection_option_get(ZOOM_connection c, const char *key); const char *ZOOM_connection_option_getl(ZOOM_connection c, const char *key, int *lenp); </pre><p> The functions <code class="function">ZOOM_connection_option_set</code> and <code class="function">ZOOM_connection_option_setl</code> allows you to set an option given by <em class="parameter"><code>key</code></em> to the value <em class="parameter"><code>value</code></em> for the connection. For <code class="function">ZOOM_connection_option_set</code>, the value is assumed to be a 0-terminated string. Function <code class="function">ZOOM_connection_option_setl</code> specifies a value of a certain size (len). </p><p> Functions <code class="function">ZOOM_connection_option_get</code> and <code class="function">ZOOM_connection_option_getl</code> returns the value for an option given by <em class="parameter"><code>key</code></em>. </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 class="name"><col class="description"><col class="default"></colgroup><thead><tr><th>Option</th><th>Description</th><th>Default</th></tr></thead><tbody><tr><td> implementationName</td><td>Name of Your client </td><td>none</td></tr><tr><td> user</td><td>Authentication user name </td><td>none</td></tr><tr><td> group</td><td>Authentication group name </td><td>none</td></tr><tr><td> password</td><td>Authentication password. </td><td>none</td></tr><tr><td> authenticationMode</td><td>How authentication is encoded. </td><td>basic</td></tr><tr><td> host</td><td>Target host. This setting is "read-only". It's automatically set internally when connecting to a target. </td><td>none</td></tr><tr><td> proxy</td><td>Proxy host. If set, the logical host is encoded in the otherInfo area of the Z39.50 Init PDU with OID 1.2.840.10003.10.1000.81.1. </td><td>none</td></tr><tr><td> clientIP</td><td>Client IP. If set, is encoded in the otherInfo area of a Z39.50 PDU with OID 1.2.840.10003.10.1000.81.3. Holds the original IP addreses of a client. Is used of ZOOM is used in a gateway of some sort. </td><td>none</td></tr><tr><td> async</td><td>If true (1) the connection operates in asynchronous operation which means that all calls are non-blocking except <a class="link" href="zoom.events.html" title="10.�Events"><code class="function">ZOOM_event</code></a>. </td><td>0</td></tr><tr><td> maximumRecordSize</td><td> Maximum size of single record. </td><td>1 MB</td></tr><tr><td> preferredMessageSize</td><td> Maximum size of multiple records. </td><td>1 MB</td></tr><tr><td> lang</td><td> Language for negotiation. </td><td>none</td></tr><tr><td> charset</td><td> Character set for negotiation. </td><td>none</td></tr><tr><td> serverImplementationId</td><td> Implementation ID of server. (The old targetImplementationId option is also supported for the benefit of old applications.) </td><td>none</td></tr><tr><td> targetImplementationName</td><td> Implementation Name of server. (The old targetImplementationName option is also supported for the benefit of old applications.) </td><td>none</td></tr><tr><td> serverImplementationVersion</td><td> Implementation Version of server. (the old targetImplementationVersion option is also supported for the benefit of old applications.) </td><td>none</td></tr><tr><td> databaseName</td><td>One or more database names separated by character plus (<code class="literal">+</code>), which to be used by subsequent search requests on this Connection. </td><td>Default</td></tr><tr><td> piggyback</td><td>True (1) if piggyback should be used in searches; false (0) if not. </td><td>1</td></tr><tr><td> smallSetUpperBound</td><td>If hits is less than or equal to this value, then target will return all records using small element set name </td><td>0</td></tr><tr><td> largeSetLowerBound</td><td>If hits is greater than this value, the target will return no records. </td><td>1</td></tr><tr><td> mediumSetPresentNumber</td><td>This value represents the number of records to be returned as part of a search when when hits is less than or equal to large set lower bound and if hits is greater than small set upper bound. </td><td>0</td></tr><tr><td> smallSetElementSetName</td><td> The element set name to be used for small result sets. </td><td>none</td></tr><tr><td> mediumSetElementSetName</td><td> The element set name to be for medium-sized result sets. </td><td>none</td></tr><tr><td> init_opt_search, init_opt_present, init_opt_delSet, etc.</td><td> After a successful Init, these options may be interrogated to discover whether the server claims to support the specified operations. </td><td>none</td></tr><tr><td>sru</td><td> SRU/Solr transport type. Must be either <code class="literal">soap</code>, <code class="literal">get</code>, <code class="literal">post</code>, or <code class="literal">solr</code>. </td><td>soap</td></tr><tr><td> sru_version</td><td> SRU/SRW version. Should be <code class="literal">1.1</code>, or <code class="literal">1.2</code>. This is , prior to connect, the version to offer (highest version). And following connect (in fact first operation), holds the negotiated version with the server (same or lower version). </td><td>1.2</td></tr><tr><td><a name="zoom.facets.option"></a> facets</td><td> Requested or recommend facets may be given before a search is sent. The value of this setting is described in <a class="xref" href="facets.html" title="8.�Facets">Section�8, “Facets”</a> For inspection of the facets returned, refer to the functions described in <a class="xref" href="zoom.facets.html" title="5.�Facets">Section�5, “Facets”</a>. </td><td>none</td></tr><tr><td> apdulog</td><td> If set to a true value such as "1", a log of low-level protocol packets is emitted on standard error stream. This can be very useful for debugging. </td><td>0</td></tr><tr><td> saveAPDU</td><td> If set to a true value such as "1", a log of low-level protocol packets is saved. The log can be retrieved by reading option APDU. Setting saveAPDU always has the side effect of resetting the currently saved log. This setting is <span class="emphasis"><em>write-only</em></span>. If read, NULL will be returned. It is only recognized in <code class="function">ZOOM_connection_option_set</code>. </td><td>0</td></tr><tr><td> APDU</td><td> Returns the log of protocol packets. Will be empty if logging is not enabled (see saveAPDU above). This setting is <span class="emphasis"><em>read-only</em></span>. It is only recognized if used in call to <code class="function">ZOOM_connection_option_get</code> or <code class="function">ZOOM_connection_option_getl</code>. </td><td>�</td></tr><tr><td> memcached</td><td> If given and non-empty, <a class="ulink" href="http://libmemcached.org/" target="_top">libMemcached</a> will be configured for the connection. This option is inspected by ZOOM when a connection is established. If the <code class="literal">memcached</code> option is given and YAZ is compiled without libMemcached support, an internal diagnostic (10018) will be thrown. libMemcached support is available for YAZ 5.0.13 or later. If this option is supplied for an earlier version of YAZ, it is <span class="emphasis"><em>ignored</em></span>. The value of this option is a list options - each is of the form <code class="literal">--name=value</code>. Option <code class="literal">--server=</code>host[:port] specifies a memcached server. It may be repeated for multiple memcached servers. Option <code class="literal">--expire=</code>seconds sets expiry time in seconds for how long result sets are to be cached. </td><td>none</td></tr><tr><td> redis</td><td> If given and non-empty, a <a class="ulink" href="http://redis.io/" target="_top">redis</a> context will be created for the connection. This option is inspected by ZOOM when a connection is established. If the <code class="literal">redis</code> option is given and YAZ is compiled without redis support, an internal diagnostic (10018) will be thrown. redis support is available for YAZ 5.2.0 or later. If this option is supplied for an earlier version of YAZ, it is <span class="emphasis"><em>ignored</em></span>. The value of this option is a set options, similar to that of the memcached setting. At this stage only --server=host[:port] and --expire=seconds is supported. </td><td>none</td></tr></tbody></table></div></div><br class="table-break"><p> If either option <code class="literal">lang</code> or <code class="literal">charset</code> is set, then <a class="ulink" href="http://www.loc.gov/z3950/agency/defns/charneg-3.html" target="_top"> Character Set and Language Negotiation</a> is in effect. </p><pre class="synopsis"> int ZOOM_connection_error(ZOOM_connection c, const char **cp, const char **addinfo); int ZOOM_connection_error_x(ZOOM_connection c, const char **cp, const char **addinfo, const char **dset); </pre><p> Function <code class="function">ZOOM_connection_error</code> checks for errors for the last operation(s) performed. The function returns zero if no errors occurred; non-zero otherwise indicating the error. Pointers <em class="parameter"><code>cp</code></em> and <em class="parameter"><code>addinfo</code></em> holds messages for the error and additional-info if passed as non-<code class="literal">NULL</code>. Function <code class="function">ZOOM_connection_error_x</code> is an extended version of <code class="function">ZOOM_connection_error</code> that is capable of returning name of diagnostic set in <em class="parameter"><code>dset</code></em>. </p><div class="sect2"><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> The calls <code class="function">ZOOM_connection_new</code> and <code class="function">ZOOM_connection_connect</code> establishes a TCP/IP connection and sends an Initialize Request to the target if possible. In addition, the calls waits for an Initialize Response from the target and the result is inspected (OK or rejected). </p><p> If <code class="literal">proxy</code> is set then the client will establish a TCP/IP connection with the peer as specified by the <code class="literal">proxy</code> host and the hostname as part of the connect calls will be set as part of the Initialize Request. The proxy server will then "forward" the PDU's transparently to the target behind the proxy. </p><p> For the authentication parameters, if option <code class="literal">user</code> is set and both options <code class="literal">group</code> and <code class="literal">pass</code> are unset, then Open style authentication is used (Version 2/3) in which case the username is usually followed by a slash, then by a password. If either <code class="literal">group</code> or <code class="literal">pass</code> is set then idPass authentication (Version 3 only) is used. If none of the options are set, no authentication parameters are set as part of the Initialize Request (obviously). </p><p> When option <code class="literal">async</code> is 1, it really means that all network operations are postponed (and queued) until the function <code class="literal">ZOOM_event</code> is invoked. When doing so it doesn't make sense to check for errors after <code class="literal">ZOOM_connection_new</code> is called since that operation "connecting - and init" is still incomplete and the API cannot tell the outcome (yet). </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="zoom.sru.init.behavior"></a>1.2.�SRU/Solr Protocol behavior</h3></div></div></div><p> The HTTP based protocols (SRU, SRW, Solr) doesn't feature an Inititialize Request, so the connection phase merely establishes a TCP/IP connection with the HTTP server. </p><p>Most of the ZOOM connection options do not affect SRU/Solr and they are ignored. However, future versions of YAZ might honor <code class="literal">implementationName</code> and put that as part of User-Agent header for HTTP requests. </p><p> The <code class="literal">charset</code> is used in the Content-Type header of HTTP requests. </p><p> Setting <code class="literal">authentcationMode</code> specifies how authentication parameters are encoded for HTTP. The default is "<code class="literal">basic</code>" where <code class="literal">user</code> and <code class="literal">password</code> are encoded by using HTTP basic authentication. </p><p> If <code class="literal">authentcationMode</code> is "<code class="literal">url</code>", then user and password are encoded in the URL by parameters <code class="literal">x-username</code> and <code class="literal">x-password</code> as given by the SRU standard. </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.�Windows�</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>