1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
|
<html><head><meta charset="ISO-8859-1"><title>Chapter3.ZOOM</title><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><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">Chapter3.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>Chapter3.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. ZOOM 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="https://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="https://solr.apache.org" 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="https://solr.apache.org" 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 as it is to develop
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="https://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 have 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/SOAP over HTTP by default,
but can be changed with option <a class="link" href="zoom.html#sru-option">sru</a>.
</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>Table3.1.ZOOM Connection Options</b></p><div class="table-contents"><table class="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 addresses
of a client. Is used if ZOOM is used in a gateway of some sort.
</td><td>none</td></tr><tr><td>
timeout</td><td>Idle timeout which specifies how long
ZOOM will wait for network I/O before giving up. Thus, the actual
waiting time might be longer than this value if the target makes
a chunked response and the time between each chunk arrive is
less this value. For the connect+init, this is the time
ZOOM will wait until receiving first byte from Init response.
</td><td>30</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>rpnCharset</td><td> Client-side character conversion for RPN queries and scan terms.
The input terms are converted from UTF-8 to the character set of rpnCharset.
</td><td>none (no conversion)</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 is 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
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 used 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><a name="sru-option"></a>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><code class="literal">soap</code> if scheme is already
<code class="literal">http</code>; ignored otherwise</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.extraArgs.option"></a>
extraArgs</td><td>
Extra arguments for SRU/Solr URLs. The value must be
URL encoded already.
</td><td></td></tr><tr><td><a name="zoom.facets.option"></a>
facets</td><td>
Requested or recommended 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">Section8, “Facets”</a>
For inspection of the facets returned, refer to the functions
described in <a class="xref" href="zoom.facets.html" title="5.ZOOM Facets">Section5, “ZOOM 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="https://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="https://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 of options, similar to that
of the memcached setting. At this stage only --server=host[:port]
and --expire=seconds are 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="https://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 wait 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 PDUs 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) do not 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>
|
