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);
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)
21 <!-- $Id: zoom.xml,v 1.44 2005-11-16 16:04:19 mike Exp $ -->
22 <chapter id="zoom"><title>ZOOM</title>
24 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
25 an initiative started by Mike Taylor (Mike is from the UK, which
26 explains the peculiar name of the model). The goal of &zoom; is to
27 provide a common Z39.50 client API not bound to a particular
28 programming language or toolkit.
33 A recent addition to &yaz; is SRW support. You can now make
34 SRW ZOOM connections by specifying scheme <literal>http://</literal>
35 for the hostname for a connection.
40 The lack of a simple Z39.50 client API for &yaz; has become more
41 and more apparent over time. So when the first &zoom; specification
43 an implementation for &yaz; was quickly developed. For the first time, it is
44 now as easy (or easier!) to develop clients than servers with &yaz;. This
45 chapter describes the &zoom; C binding. Before going further, please
46 reconsider whether C is the right programming language for the job.
47 There are other language bindings available for &yaz;, and still
49 are in active development. See the
50 <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
55 In order to fully understand this chapter you should read and
56 try the example programs <literal>zoomtst1.c</literal>,
57 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
62 The C language misses features found in object oriented languages
63 such as C++, Java, etc. For example, you'll have to manually,
64 destroy all objects you create, even though you may think of them as
65 temporary. Most objects has a <literal>_create</literal> - and a
66 <literal>_destroy</literal> variant.
67 All objects are in fact pointers to internal stuff, but you don't see
68 that because of typedefs. All destroy methods should gracefully ignore a
69 <literal>NULL</literal> pointer.
72 In each of the sections below you'll find a sub section called
73 protocol behavior, that describes how the API maps to the Z39.50
76 <sect1 id="zoom.connections"><title>Connections</title>
78 <para>The Connection object is a session with a target.
81 #include <yaz/zoom.h>
83 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
85 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
87 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
89 void ZOOM_connection_destroy (ZOOM_connection c);
92 Connection objects are created with either function
93 <function>ZOOM_connection_new</function> or
94 <function>ZOOM_connection_create</function>.
95 The former creates and automatically attempts to establish a network
96 connection with the target. The latter doesn't establish
97 a connection immediately, thus allowing you to specify options
98 before establishing network connection using the function
99 <function>ZOOM_connection_connect</function>.
100 If the port number, <literal>portnum</literal>, is zero, the
101 <literal>host</literal> is consulted for a port specification.
102 If no port is given, 210 is used. A colon denotes the beginning of
103 a port number in the host string. If the host string includes a
104 slash, the following part specifies a database for the connection.
107 You can prefix the host with a scheme followed by colon. The
108 default scheme is <literal>tcp</literal> (Z39.50 protocol).
109 The scheme <literal>http</literal> selects SRW over HTTP.
112 Connection objects should be destroyed using the function
113 <function>ZOOM_connection_destroy</function>.
116 void ZOOM_connection_option_set(ZOOM_connection c,
117 const char *key, const char *val);
119 void ZOOM_connection_option_setl(ZOOM_connection c,
121 const char *val, int len);
123 const char *ZOOM_connection_option_get(ZOOM_connection c,
125 const char *ZOOM_connection_option_getl(ZOOM_connection c,
130 The functions <function>ZOOM_connection_option_set</function> and
131 <function>ZOOM_connection_option_setl</function> allows you to
132 set an option given by <parameter>key</parameter> to the value
133 <parameter>value</parameter> for the connection.
134 For <function>ZOOM_connection_option_set</function>, the
135 value is assumed to be a 0-terminated string. Function
136 <function>ZOOM_connection_option_setl</function> specifies a
137 value of a certain size (len).
140 Functions <function>ZOOM_connection_option_get</function> and
141 <function>ZOOM_connection_option_getl</function> returns
142 the value for an option given by <parameter>key</parameter>.
144 <table frame="top"><title>ZOOM Connection Options</title>
146 <colspec colwidth="4*" colname="name"></colspec>
147 <colspec colwidth="7*" colname="description"></colspec>
148 <colspec colwidth="3*" colname="default"></colspec>
151 <entry>Option</entry>
152 <entry>Description</entry>
153 <entry>Default</entry>
158 implementationName</entry><entry>Name of Your client
159 </entry><entry>none</entry></row>
161 user</entry><entry>Authentication user name
162 </entry><entry>none</entry></row>
164 group</entry><entry>Authentication group name
165 </entry><entry>none</entry></row>
167 password</entry><entry>Authentication password.
168 </entry><entry>none</entry></row>
170 host</entry><entry>Target host. This setting is "read-only".
171 It's automatically set internally when connecting to a target.
172 </entry><entry>none</entry></row>
174 proxy</entry><entry>Proxy host
175 </entry><entry>none</entry></row>
177 async</entry><entry>If true (1) the connection operates in
178 asynchronous operation which means that all calls are non-blocking
180 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
181 </entry><entry>0</entry></row>
183 maximumRecordSize</entry><entry> Maximum size of single record.
184 </entry><entry>1 MB</entry></row>
186 preferredMessageSize</entry><entry> Maximum size of multiple records.
187 </entry><entry>1 MB</entry></row>
189 lang</entry><entry> Language for negotiation.
190 </entry><entry>none</entry></row>
192 charset</entry><entry> Character set for negotiation.
193 </entry><entry>none</entry></row>
195 serverImplementationId</entry><entry>
196 Implementation ID of server. (The old targetImplementationId
197 option is also supported for the benefit of old applications.)
198 </entry><entry>none</entry></row>
200 targetImplementationName</entry><entry>
201 Implementation Name of server. (The old
202 targetImplementationName option is also supported for the
203 benefit of old applications.)
204 </entry><entry>none</entry></row>
206 serverImplementationVersion</entry><entry>
207 Implementation Version of server. (the old
208 targetImplementationVersion option is also supported for the
209 benefit of old applications.)
210 </entry><entry>none</entry></row>
212 databaseName</entry><entry>One or more database names
213 separated by character plus (<literal>+</literal>), which to
214 be used by subsequent search requests on this Connection.
215 </entry><entry>Default</entry></row>
217 piggyback</entry><entry>True (1) if piggyback should be
218 used in searches; false (0) if not.
219 </entry><entry>1</entry></row>
221 smallSetUpperBound</entry><entry>If hits is less than or equal to this
222 value, then target will return all records using small element set name
223 </entry><entry>0</entry></row>
225 largeSetLowerBound</entry><entry>If hits is greater than this
226 value, the target will return no records.
227 </entry><entry>1</entry></row>
229 mediumSetPresentNumber</entry><entry>This value represents
230 the number of records to be returned as part of a search when when
231 hits is less than or equal to large set lower bound and if hits
232 is greater than small set upper bound.
233 </entry><entry>0</entry></row>
235 smallSetElementSetName</entry><entry>
236 The element set name to be used for small result sets.
237 </entry><entry>none</entry></row>
239 mediumSetElementSetName</entry><entry>
240 The element set name to be for medium-sized result sets.
241 </entry><entry>none</entry></row>
246 If either option <literal>lang</literal> or <literal>charset</literal>
248 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
249 Character Set and Language Negotiation</ulink> is in effect.
252 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
253 const char **addinfo);
254 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
255 const char **addinfo, const char **dset);
258 Function <function>ZOOM_connection_error</function> checks for
259 errors for the last operation(s) performed. The function returns
260 zero if no errors occurred; non-zero otherwise indicating the error.
261 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
262 holds messages for the error and additional-info if passed as
263 non-<literal>NULL</literal>. Function
264 <function>ZOOM_connection_error_x</function> is an extended version
265 of <function>ZOOM_connection_error</function> that is capable of
266 returning name of diagnostic set in <parameter>dset</parameter>.
268 <sect2><title>Z39.50 Protocol behavior</title>
270 The calls <function>ZOOM_connection_new</function> and
271 <function>ZOOM_connection_connect</function> establishes a TCP/IP
272 connection and sends an Initialize Request to the target if
273 possible. In addition, the calls waits for an Initialize Response
274 from the target and the result is inspected (OK or rejected).
277 If <literal>proxy</literal> is set then the client will establish
278 a TCP/IP connection with the peer as specified by the
279 <literal>proxy</literal> host and the hostname as part of the
280 connect calls will be set as part of the Initialize Request.
281 The proxy server will then "forward" the PDU's transparently
282 to the target behind the proxy.
285 For the authentication parameters, if option <literal>user</literal>
286 is set and both options <literal>group</literal> and
287 <literal>pass</literal> are unset, then Open style
288 authentication is used (Version 2/3) in which case the username
289 is usually followed by a slash, then by a password.
290 If either <literal>group</literal>
291 or <literal>pass</literal> is set then idPass authentication
292 (Version 3 only) is used. If none of the options are set, no
293 authentication parameters are set as part of the Initialize Request
297 When option <literal>async</literal> is 1, it really means that
298 all network operations are postponed (and queued) until the
299 function <literal>ZOOM_event</literal> is invoked. When doing so
300 it doesn't make sense to check for errors after
301 <literal>ZOOM_connection_new</literal> is called since that
302 operation "connecting - and init" is still incomplete and the
303 API cannot tell the outcome (yet).
306 <sect2><title>SRW Protocol behavior</title>
308 The SRW protocol doesn't feature an Inititialize Request, so
309 the connection phase merely establishes a TCP/IP connection
310 with the SOAP service.
312 <para>Most of the ZOOM connection options do not
313 affect SRW and they are ignored. However, future versions
314 of &yaz; might honor <literal>implementationName</literal> and
315 put that as part of User-Agent header for HTTP requests.
318 The <literal>charset</literal> is used in the Content-Type header
323 <sect1 id="zoom.query"><title>Queries</title>
325 Query objects represents queries.
328 ZOOM_query ZOOM_query_create(void);
330 void ZOOM_query_destroy(ZOOM_query q);
332 int ZOOM_query_prefix(ZOOM_query q, const char *str);
334 int ZOOM_query_cql(ZOOM_query s, const char *str);
336 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
339 Create query objects using <function>ZOOM_query_create</function>
340 and destroy them by calling <function>ZOOM_query_destroy</function>.
341 RPN-queries can be specified in <link linkend="PQF">PQF</link>
342 notation by using the
343 function <function>ZOOM_query_prefix</function>.
344 The <function>ZOOM_query_cql</function> specifies a CQL
345 query to be sent to the server/target.
346 More query types will be added in future versions of &yaz;, such as
347 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
348 etc. In addition to a search, a sort criteria may be set. Function
349 <function>ZOOM_query_sortby</function> specifies a
350 sort criteria using the same string notation for sort as offered by
351 the <link linkend="sortspec">YAZ client</link>.
353 <sect2><title>Protocol behavior</title>
355 The query object is just an interface for the member Query
356 in the SearchRequest. The sortby-function is an interface to the
357 sortSequence member of the SortRequest.
361 <sect1 id="zoom.resultsets"><title>Result sets</title>
363 The result set object is a container for records returned from
367 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
370 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
373 void ZOOM_resultset_destroy(ZOOM_resultset r);
376 Function <function>ZOOM_connection_search</function> creates
377 a result set given a connection and query.
378 Destroy a result set by calling
379 <function>ZOOM_resultset_destroy</function>.
380 Simple clients may using PQF only may use function
381 <function>ZOOM_connection_search_pqf</function> in which case
382 creating query objects is not necessary.
385 void ZOOM_resultset_option_set (ZOOM_resultset r,
389 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
392 size_t ZOOM_resultset_size (ZOOM_resultset r);
395 Functions <function>ZOOM_resultset_options_set</function> and
396 <function>ZOOM_resultset_get</function> sets and gets an option
397 for a result set similar to <function>ZOOM_connection_option_get</function>
398 and <function>ZOOM_connection_option_set</function>.
401 The number of hits also called result-count is returned by
402 function <function>ZOOM_resultset_size</function>.
404 <table frame="top"><title>ZOOM Result set Options</title>
406 <colspec colwidth="4*" colname="name"></colspec>
407 <colspec colwidth="7*" colname="description"></colspec>
408 <colspec colwidth="2*" colname="default"></colspec>
411 <entry>Option</entry>
412 <entry>Description</entry>
413 <entry>Default</entry>
418 start</entry><entry>Offset of first record to be
419 retrieved from target. First record has offset 0 unlike the
420 protocol specifications where first record has position 1.
421 </entry><entry>0</entry></row>
423 count</entry><entry>Number of records to be retrieved.
424 </entry><entry>0</entry></row>
426 presentChunk</entry><entry>The number of records to be
427 requested from the server in each chunk (present requst). The
428 value 0 means to request all the records in a single chunk.
429 (The old <literal>step</literal>
430 option is also supported for the benefit of old applications.)
431 </entry><entry>0</entry></row>
433 elementSetName</entry><entry>Element-Set name of records.
434 Most targets should honor element set name <literal>B</literal>
435 and <literal>F</literal> for brief and full respectively.
436 </entry><entry>none</entry></row>
438 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
439 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
440 </entry><entry>none</entry></row>
442 schema</entry><entry>Schema for retrieval, such as
443 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
444 </entry><entry>none</entry></row>
446 setname</entry><entry>Name of Result Set (Result Set ID).
447 If this option isn't set, the ZOOM module will automatically
448 allocate a result set name.
449 </entry><entry>default</entry></row>
454 For servers that support Search Info report, the following
455 options may be read using <function>ZOOM_resultset_get</function>.
456 This detailed information is read after a successful search has
460 This information is a list of of items, where each item is
461 information about a term or subquery. All items in the list
463 <literal>SearchResult.</literal><replaceable>no</replaceable>
464 where no presents the item number (0=first, 1=second).
465 Read <literal>searchresult.size</literal> to determine the
468 <table frame="top"><title>Search Info Report options</title>
470 <colspec colwidth="4*" colname="name"></colspec>
471 <colspec colwidth="7*" colname="description"></colspec>
474 <entry>Option</entry>
475 <entry>Description</entry>
480 <entry>searchresult.size</entry>
482 number of search result entries. This option is-nonexistant
483 if no entries are returned by the server.
487 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
488 <entry>sub query ID</entry>
491 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
492 <entry>result count for item (number of hits)</entry>
495 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
496 <entry>subquery term</entry>
500 searchresult.<replaceable>no</replaceable>.interpretation.term
502 <entry>interpretation term</entry>
506 searchresult.<replaceable>no</replaceable>.recommendation.term
508 <entry>recommendation term</entry>
514 <title>Z39.50 Protocol behavior</title>
516 The creation of a result set involves at least a SearchRequest
517 - SearchResponse protocol handshake. Following that, if a sort
518 criteria was specified as part of the query, a SortRequest -
519 SortResponse handshake takes place. Note that it is necessary to
520 perform sorting before any retrieval takes place, so no records will
521 be returned from the target as part of the SearchResponse because these
522 would be unsorted. Hence, piggyback is disabled when sort criteria
523 are set. Following Search - and a possible sort - Retrieval takes
524 place - as one or more Present Requests/Response pairs being
528 The API allows for two different modes for retrieval. A high level
529 mode which is somewhat more powerful and a low level one.
530 The low level is enabled when searching on a Connection object
531 for which the settings
532 <literal>smallSetUpperBound</literal>,
533 <literal>mediumSetPresentNumber</literal> and
534 <literal>largeSetLowerBound</literal> are set. The low level mode
535 thus allows you to precisely set how records are returned as part
536 of a search response as offered by the Z39.50 protocol.
537 Since the client may be retrieving records as part of the
538 search response, this mode doesn't work well if sorting is used.
541 The high-level mode allows you to fetch a range of records from
542 the result set with a given start offset. When you use this mode
543 the client will automatically use piggyback if that is possible
544 with the target and perform one or more present requests as needed.
545 Even if the target returns fewer records as part of a present response
546 because of a record size limit, etc. the client will repeat sending
547 present requests. As an example, if option <literal>start</literal>
548 is 0 (default) and <literal>count</literal> is 4, and
549 <literal>piggyback</literal> is 1 (default) and no sorting criteria
550 is specified, then the client will attempt to retrieve the 4
551 records as part the search response (using piggyback). On the other
552 hand, if either <literal>start</literal> is positive or if
553 a sorting criteria is set, or if <literal>piggyback</literal>
554 is 0, then the client will not perform piggyback but send Present
558 If either of the options <literal>mediumSetElementSetName</literal> and
559 <literal>smallSetElementSetName</literal> are unset, the value
560 of option <literal>elementSetName</literal> is used for piggyback
561 searches. This means that for the high-level mode you only have
562 to specify one elementSetName option rather than three.
566 <title>SRW Protocol behavior</title>
568 Current version of &yaz; does not take advantage of a result set id
569 returned by the SRW server. Future versions might do, however.
570 Since, the ZOOM driver does not save result set IDs any
571 present (retrieval) is transformed to a SRW SearchRetrieveRequest
572 with same query but, possibly, different offsets.
575 Option <literal>schema</literal> specifies SRW schema
576 for retrieval. However, options <literal>elementSetName</literal> and
577 <literal>preferredRecordSyntax</literal> are ignored.
580 Options <literal>start</literal> and <literal>count</literal>
581 are supported by SRW.
582 The remaining options
583 <literal>piggyback</literal>,
584 <literal>smallSetUpperBound</literal>,
585 <literal>largeSetLowerBound</literal>,
586 <literal>mediumSetPresentNumber</literal>,
587 <literal>mediumSetElementSetName</literal>,
588 <literal>smallSetElementSetName</literal> are
592 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
593 If PQF is used, however, the PQF query is transferred anyway
594 using non-standard element <literal>pQuery</literal> in
595 SRW SearchRetrieveRequest.
598 Unfortunately, SRW does not define a database setting. Hence,
599 <literal>databaseName</literal> is unsupported and ignored.
600 However, the path part in host parameter for functions
601 <function>ZOOM_connecton_new</function> and
602 <function>ZOOM_connection_connect</function> acts as a
603 database (at least for the &yaz; SRW server).
607 <sect1 id="zoom.records"><title>Records</title>
609 A record object is a retrieval record on the client side -
610 created from result sets.
613 void ZOOM_resultset_records (ZOOM_resultset r,
615 size_t start, size_t count);
616 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
618 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
621 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
623 void ZOOM_record_destroy (ZOOM_record rec);
626 References to temporary records are returned by functions
627 <function>ZOOM_resultset_records</function> or
628 <function>ZOOM_resultset_record</function>.
631 If a persistent reference to a record is desired
632 <function>ZOOM_record_clone</function> should be used.
633 It returns a record reference that should be destroyed
634 by a call to <function>ZOOM_record_destroy</function>.
637 A single record is returned by function
638 <function>ZOOM_resultset_record</function> that takes a
639 position as argument. First record has position zero.
640 If no record could be obtained <literal>NULL</literal> is returned.
643 Function <function>ZOOM_resultset_records</function> retrieves
644 a number of records from a result set. Parameter <literal>start</literal>
645 and <literal>count</literal> specifies the range of records to
646 be returned. Upon completion array
647 <literal>recs[0], ..recs[count-1]</literal>
648 holds record objects for the records. The array of records
649 <literal>recs</literal> should be allocated prior the call
650 <function>ZOOM_resultset_records</function>. Note that for those
651 records that couldn't be retrieved from the target
652 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
654 <para id="zoom.record.get">
655 In order to extract information about a single record,
656 <function>ZOOM_record_get</function> is provided. The
657 function returns a pointer to certain record information. The
658 nature (type) of the pointer depends on the parameter,
659 <parameter>type</parameter>.
662 The <parameter>type</parameter> is a string of the format:
665 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
668 where <replaceable>form</replaceable> specifies the format of the
669 returned record, <replaceable>from</replaceable>
670 specifies the character set of the record in its original form
671 (as returned by the server), <replaceable>to</replaceable> specifies
672 the output (returned)
673 character set encoding.
674 If charset is not given, then no character set conversion takes place.
675 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
678 In addition, for certain types, the length
679 <literal>len</literal> passed will be set to the size in bytes of
680 the returned information.
683 The following are the supported values for <replaceable>form</replaceable>.
685 <varlistentry><term><literal>database</literal></term>
686 <listitem><para>Database of record is returned
687 as a C null-terminated string. Return type
688 <literal>const char *</literal>.
691 <varlistentry><term><literal>syntax</literal></term>
692 <listitem><para>The transfer syntax of the record is returned
693 as a C null-terminated string containing the symbolic name of
694 the record syntax, e.g. <literal>Usmarc</literal>. Return type
696 <literal>const char *</literal>.
699 <varlistentry><term><literal>render</literal></term>
700 <listitem><para>The record is returned in a display friendly
701 format. Upon completion buffer is returned
702 (type <literal>const char *</literal>) and length is stored in
703 <literal>*len</literal>.
706 <varlistentry><term><literal>raw</literal></term>
707 <listitem><para>The record is returned in the internal
708 YAZ specific format. For GRS-1, Explain, and others, the
709 raw data is returned as type
710 <literal>Z_External *</literal> which is just the type for
711 the member <literal>retrievalRecord</literal> in
712 type <literal>NamePlusRecord</literal>.
713 For SUTRS and octet aligned record (including all MARCs) the
714 octet buffer is returned and the length of the buffer.
717 <varlistentry><term><literal>xml</literal></term>
718 <listitem><para>The record is returned in XML if possible.
719 SRW/SRU and Z39.50 records with transfer syntax XML are
720 returned verbatim. MARC records are returned in
721 <ulink url="http://www.loc.gov/standards/marcxml/">
724 (converted from ISO2709 to MARCXML by YAZ).
725 GRS-1 and OPAC records are not supported for this form.
726 Upon completion, the XML buffer is returned
727 (type <literal>const char *</literal>) and length is stored in
728 <literal>*len</literal>.
731 <varlistentry><term><literal>opac</literal></term>
732 <listitem><para>OPAC for record is returned in XML.
739 <ulink url="http://www.loc.gov/marc/">
743 <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
746 character set encoding.
747 An application that wishes to display in Latin-1 would use
749 render; charset=marc8,iso-8859-1
752 <sect2><title>Z39.50 Protocol behavior</title>
754 The functions <function>ZOOM_resultset_record</function> and
755 <function>ZOOM_resultset_records</function> inspects the client-side
756 record cache. Records not found in cache are fetched using
758 The functions may block (and perform network I/O) - even though option
759 <literal>async</literal> is 1, because they return records objects.
760 (and there's no way to return records objects without retrieving them!).
763 There is a trick, however, in the usage of function
764 <function>ZOOM_resultset_records</function> that allows for
765 delayed retrieval (and makes it non-blocking). By using
766 a null pointer for <parameter>recs</parameter> you're indicating
767 you're not interested in getting records objects
768 <emphasis>now</emphasis>.
771 <sect2><title>SRW Protocol behavior</title>
773 The ZOOM driver for SRW treats records returned by a SRW server
774 as if they where Z39.50 records with transfer syntax XML and
775 no element set name or database name.
779 <sect1 id="zoom.scan"><title>Scan</title>
781 This section describes an interface for Scan. Scan is not an
782 official part of the ZOOM model yet. The result of a scan operation
783 is the <literal>ZOOM_scanset</literal> which is a set of terms
784 returned by a target.
788 The Scan interface is Z39.50 only. SRW version 1.0 does not
793 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
794 const char *startpqf);
796 size_t ZOOM_scanset_size(ZOOM_scanset scan);
798 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
799 int *occ, size_t *len);
801 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
802 int *occ, size_t *len);
804 void ZOOM_scanset_destroy (ZOOM_scanset scan);
806 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
809 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
813 The scan set is created by function
814 <function>ZOOM_connection_scan</function> which performs a scan
815 operation on the connection using the specified
816 <parameter>startpqf</parameter>.
817 If the operation was successful, the size of the scan set can be
818 retrieved by a call to <function>ZOOM_scanset_size</function>.
819 Like result sets, the items are numbered 0,..size-1.
820 To obtain information about a particular scan term, call function
821 <function>ZOOM_scanset_term</function>. This function takes
822 a scan set offset <literal>pos</literal> and returns a pointer
823 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
825 If present, the <literal>occ</literal> and <literal>len</literal>
826 are set to the number of occurrences and the length
827 of the actual term respectively.
828 <function>ZOOM_scanset_display_term</function> is similar to
829 <function>ZOOM_scanset_term</function> except that it returns
830 the <emphasis>display term</emphasis> rather than the raw term.
831 In a few cases, the term is different from display term. Always
832 use the display term for display and the raw term for subsequent
833 scan operations (to get more terms, next scan result, etc).
836 A scan set may be freed by a call to function
837 <function>ZOOM_scanset_destroy</function>.
838 Functions <function>ZOOM_scanset_option_get</function> and
839 <function>ZOOM_scanset_option_set</function> retrieves and sets
840 an option respectively.
844 The <parameter>startpqf</parameter> is a subset of PQF, namely
845 the Attributes+Term part. Multiple <literal>@attr</literal> can
846 be used. For example to scan in title (complete) phrases:
848 @attr 1=4 @attr 6=2 "science o"
852 <table frame="top"><title>ZOOM Scan Set Options</title>
854 <colspec colwidth="4*" colname="name"></colspec>
855 <colspec colwidth="7*" colname="description"></colspec>
856 <colspec colwidth="2*" colname="default"></colspec>
859 <entry>Option</entry>
860 <entry>Description</entry>
861 <entry>Default</entry>
866 number</entry><entry>Number of Scan Terms requested in next scan.
867 After scan it holds the actual number of terms returned.
868 </entry><entry>10</entry></row>
870 position</entry><entry>Preferred Position of term in response
871 in next scan; actual position after completion of scan.
872 </entry><entry>1</entry></row>
874 stepSize</entry><entry>Step Size
875 </entry><entry>0</entry></row>
877 scanStatus</entry><entry>An integer indicating the Scan Status
879 </entry><entry>0</entry></row>
885 <sect1 id="zoom.ext"><title>Extended Services</title>
887 ZOOM offers an interface to a subset of the Z39.50 extended services
888 as well as a few privately defined ones:
893 Z39.50 Item Order (ILL).
894 See <xref linkend="zoom.ext.itemorder"/>.
899 Record Update. This allows a client to insert, modify or delete
901 See <xref linkend="zoom.ext.update"/>.
906 Database Create. This a non-standard feature. Allows a client
907 to create a database.
908 See <xref linkend="zoom.ext.dbcreate"/>.
913 Database Drop. This a non-standard feature. Allows a client
914 to delete/drop a database.
915 See <xref linkend="zoom.ext.dbdrop"/>.
920 Commit operation. This a non-standard feature. Allows a client
921 to commit operations.
922 See <xref linkend="zoom.ext.commit"/>.
925 <!-- all the ILL PDU options should go here too -->
928 To create an extended service operation a <literal>ZOOM_package</literal>
929 must be created. The operation is a five step operation. The
930 package is created, package is configured by means of options,
931 the package is send, result is inspected (by means of options),
932 the package is destroyed.
935 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
936 ZOOM_options options);
938 const char *ZOOM_package_option_get(ZOOM_package p,
940 void ZOOM_package_option_set(ZOOM_package p, const char *key,
942 void ZOOM_package_send(ZOOM_package p, const char *type);
944 void ZOOM_package_destroy(ZOOM_package p);
947 The <function>ZOOM_connection_package</function> creates a
948 package for the connection given using the options specified.
951 Functions <function>ZOOM_package_option_get</function> and
952 <function>ZOOM_package_option_set</function> gets and sets
956 <function>ZOOM_package_send</function> sends
957 the package the via connection specified in
958 <function>ZOOM_connection_package</function>.
959 The <parameter>type</parameter> specifies the actual extended service
960 package type to be sent.
963 <table frame="top"><title>Extended Service Common Options</title>
965 <colspec colwidth="4*" colname="name"></colspec>
966 <colspec colwidth="7*" colname="description"></colspec>
967 <colspec colwidth="3*" colname="default"></colspec>
970 <entry>Option</entry>
971 <entry>Description</entry>
972 <entry>Default</entry>
977 <entry>package-name</entry>
978 <entry>Extended Service Request package name. Must be specified
979 as part of a request</entry>
983 <entry>user-id</entry>
984 <entry>User ID of Extended Service Package. Is a request option</entry>
988 <entry>function</entry>
990 Function of package - one of <literal>create</literal>,
991 <literal>delete</literal>, <literal>modify</literal>. Is
994 <entry><literal>create</literal></entry>
997 <entry>targetReference</entry>
999 Target Reference. This is part of the response as returned
1000 by the server. Read it after a succesful operation.
1002 <entry><literal>none</literal></entry>
1008 <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
1010 For Item Order, type must be set to <literal>itemorder</literal> in
1011 <function>ZOOM_package_send</function>.
1014 <table frame="top"><title>Item Order Options</title>
1016 <colspec colwidth="4*" colname="name"></colspec>
1017 <colspec colwidth="7*" colname="description"></colspec>
1018 <colspec colwidth="3*" colname="default"></colspec>
1021 <entry>Option</entry>
1022 <entry>Description</entry>
1023 <entry>Default</entry>
1028 <entry>contact-name</entry>
1029 <entry>ILL contact name</entry>
1033 <entry>contact-phone</entry>
1034 <entry>ILL contact phone</entry>
1038 <entry>contact-email</entry>
1039 <entry>ILL contact email</entry>
1043 <entry>itemorder-item</entry>
1044 <entry>Position for item (record) requested. An integer</entry>
1053 <sect2 id="zoom.ext.update"><title>Record Update</title>
1055 For Record Update, type must be set to <literal>update</literal> in
1056 <function>ZOOM_package_send</function>.
1059 <table frame="top"><title>Record Update Options</title>
1061 <colspec colwidth="4*" colname="name"></colspec>
1062 <colspec colwidth="7*" colname="description"></colspec>
1063 <colspec colwidth="3*" colname="default"></colspec>
1066 <entry>Option</entry>
1067 <entry>Description</entry>
1068 <entry>Default</entry>
1073 <entry>action</entry>
1075 The update action. One of
1076 <literal>specialUpdate</literal>,
1077 <literal>recordInsert</literal>,
1078 <literal>recordReplace</literal>,
1079 <literal>recordDelete</literal>,
1080 <literal>elementUpdate</literal>.
1082 <entry><literal>specialUpdate</literal></entry>
1085 <entry>recordIdOpaque</entry>
1086 <entry>Opaque Record ID</entry>
1090 <entry>recordIdNumber</entry>
1091 <entry>Record ID number</entry>
1095 <entry>record</entry>
1096 <entry>The record itself</entry>
1100 <entry>syntax</entry>
1101 <entry>The record syntax (transfer syntax). Is a string that
1102 is a known record syntax.
1104 <entry>no syntax</entry>
1107 <entry>databaseName</entry>
1108 <entry>Database from connection object</entry>
1109 <entry>Default</entry>
1117 <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
1119 For Database Create, type must be set to <literal>create</literal> in
1120 <function>ZOOM_package_send</function>.
1123 <table frame="top"><title>Database Create Options</title>
1125 <colspec colwidth="4*" colname="name"></colspec>
1126 <colspec colwidth="7*" colname="description"></colspec>
1127 <colspec colwidth="3*" colname="default"></colspec>
1130 <entry>Option</entry>
1131 <entry>Description</entry>
1132 <entry>Default</entry>
1137 <entry>databaseName</entry>
1138 <entry>Database from connection object</entry>
1139 <entry>Default</entry>
1146 <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
1148 For Database Drop, type must be set to <literal>drop</literal> in
1149 <function>ZOOM_package_send</function>.
1152 <table frame="top"><title>Database Create Options</title>
1154 <colspec colwidth="4*" colname="name"></colspec>
1155 <colspec colwidth="7*" colname="description"></colspec>
1156 <colspec colwidth="3*" colname="default"></colspec>
1159 <entry>Option</entry>
1160 <entry>Description</entry>
1161 <entry>Default</entry>
1166 <entry>databaseName</entry>
1167 <entry>Database from connection object</entry>
1168 <entry>Default</entry>
1175 <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
1177 For Commit, type must be set to <literal>commit</literal> in
1178 <function>ZOOM_package_send</function>.
1182 <sect2><title>Protocol behavior</title>
1184 All the extended services are Z39.50-only.
1188 The database create, drop and commit services are privately defined
1190 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1197 <sect1 id="zoom.options"><title>Options</title>
1199 Most &zoom; objects provide a way to specify options to change behavior.
1200 From an implementation point of view a set of options is just like
1201 an associative array / hash.
1204 ZOOM_options ZOOM_options_create (void);
1206 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1208 void ZOOM_options_destroy (ZOOM_options opt);
1211 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1213 void ZOOM_options_set (ZOOM_options opt, const char *name,
1217 typedef const char *(*ZOOM_options_callback)
1218 (void *handle, const char *name);
1220 ZOOM_options_callback
1221 ZOOM_options_set_callback (ZOOM_options opt,
1222 ZOOM_options_callback c,
1226 <sect1 id="zoom.events"><title>Events</title>
1228 If you're developing non-blocking applications, you have to deal
1232 int ZOOM_event (int no, ZOOM_connection *cs);
1235 The <function>ZOOM_event</function> executes pending events for
1236 a number of connections. Supply the number of connections in
1237 <literal>no</literal> and an array of connections in
1238 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1239 A pending event could be a sending a search, receiving a response,
1241 When an event has occurred for one of the connections, this function
1242 returns a positive integer <literal>n</literal> denoting that an event
1243 occurred for connection <literal>cs[n-1]</literal>.
1244 When no events are pending for the connections, a value of zero is
1246 To ensure that all outstanding requests are performed call this function
1247 repeatedly until zero is returned.
1250 If <function>ZOOM_event</function> returns and returns non-zero, the
1251 last event that occurred can be expected.
1254 int ZOOM_connection_last_event(ZOOM_connection cs);
1257 <function>ZOOM_connection_last_event</function> returns an event type
1258 (integer) for the last event.
1261 <table frame="top"><title>ZOOM Event IDs</title>
1263 <colspec colwidth="4*" colname="name"></colspec>
1264 <colspec colwidth="7*" colname="description"></colspec>
1267 <entry>Event</entry>
1268 <entry>Description</entry>
1273 <entry>ZOOM_EVENT_NONE</entry>
1274 <entry>No event has occurred</entry>
1277 <entry>ZOOM_EVENT_CONNECT</entry>
1278 <entry>TCP/IP connect has initiated</entry>
1281 <entry>ZOOM_EVENT_SEND_DATA</entry>
1282 <entry>Data has been transmitted (sending)</entry>
1285 <entry>ZOOM_EVENT_RECV_DATA</entry>
1286 <entry>Data has been received)</entry>
1289 <entry>ZOOM_EVENT_TIMEOUT</entry>
1290 <entry>Timeout</entry>
1293 <entry>ZOOM_EVENT_UNKNOWN</entry>
1294 <entry>Unknown event</entry>
1297 <entry>ZOOM_EVENT_SEND_APDU</entry>
1298 <entry>An APDU has been transmitted (sending)</entry>
1301 <entry>ZOOM_EVENT_RECV_APDU</entry>
1302 <entry>An APDU has been received</entry>
1305 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1306 <entry>A result-set record has been received</entry>
1309 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1310 <entry>A search result been received</entry>
1318 <!-- Keep this comment at the end of the file
1323 sgml-minimize-attributes:nil
1324 sgml-always-quote-attributes:t
1327 sgml-parent-document: "yaz.xml"
1328 sgml-local-catalogs: nil
1329 sgml-namecase-general:t