3 ZOOM_connection_errcode(c)
4 ZOOM_connection_errmsg(c)
5 ZOOM_connection_addinfo(c)
7 ZOOM_resultset_record_immediate(s, pos)
8 ZOOM_resultset_cache_reset(r)
9 ZOOM_resultset_sort(r, sort_type, sort_spec)
10 ZOOM_resultset_sort1(r, sort_type, sort_spec)
11 ZOOM_options_set_callback(opt, function, handle)
12 ZOOM_options_create_with_parent2(parent1, parent2)
13 ZOOM_options_getl(opt, name, len)
14 ZOOM_options_setl(opt, name, value, len)
15 ZOOM_options_get_bool(opt, name, defa)
16 ZOOM_options_get_int(opt, name, defa)
17 ZOOM_options_set_int(opt, name, value)
19 <!-- $Id: zoom.xml,v 1.43 2005-11-08 21:53:01 adam Exp $ -->
20 <chapter id="zoom"><title>ZOOM</title>
22 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
23 an initiative started by Mike Taylor (Mike is from the UK, which
24 explains the peculiar name of the model). The goal of &zoom; is to
25 provide a common Z39.50 client API not bound to a particular
26 programming language or toolkit.
31 A recent addition to &yaz; is SRW support. You can now make
32 SRW ZOOM connections by specifying scheme <literal>http://</literal>
33 for the hostname for a connection.
38 The lack of a simple Z39.50 client API for &yaz; has become more
39 and more apparent over time. So when the first &zoom; specification
41 an implementation for &yaz; was quickly developed. For the first time, it is
42 now as easy (or easier!) to develop clients than servers with &yaz;. This
43 chapter describes the &zoom; C binding. Before going further, please
44 reconsider whether C is the right programming language for the job.
45 There are other language bindings available for &yaz;, and still
47 are in active development. See the
48 <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
53 In order to fully understand this chapter you should read and
54 try the example programs <literal>zoomtst1.c</literal>,
55 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
60 The C language misses features found in object oriented languages
61 such as C++, Java, etc. For example, you'll have to manually,
62 destroy all objects you create, even though you may think of them as
63 temporary. Most objects has a <literal>_create</literal> - and a
64 <literal>_destroy</literal> variant.
65 All objects are in fact pointers to internal stuff, but you don't see
66 that because of typedefs. All destroy methods should gracefully ignore a
67 <literal>NULL</literal> pointer.
70 In each of the sections below you'll find a sub section called
71 protocol behavior, that describes how the API maps to the Z39.50
74 <sect1 id="zoom.connections"><title>Connections</title>
76 <para>The Connection object is a session with a target.
79 #include <yaz/zoom.h>
81 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
83 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
85 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
87 void ZOOM_connection_destroy (ZOOM_connection c);
90 Connection objects are created with either function
91 <function>ZOOM_connection_new</function> or
92 <function>ZOOM_connection_create</function>.
93 The former creates and automatically attempts to establish a network
94 connection with the target. The latter doesn't establish
95 a connection immediately, thus allowing you to specify options
96 before establishing network connection using the function
97 <function>ZOOM_connection_connect</function>.
98 If the port number, <literal>portnum</literal>, is zero, the
99 <literal>host</literal> is consulted for a port specification.
100 If no port is given, 210 is used. A colon denotes the beginning of
101 a port number in the host string. If the host string includes a
102 slash, the following part specifies a database for the connection.
105 You can prefix the host with a scheme followed by colon. The
106 default scheme is <literal>tcp</literal> (Z39.50 protocol).
107 The scheme <literal>http</literal> selects SRW over HTTP.
110 Connection objects should be destroyed using the function
111 <function>ZOOM_connection_destroy</function>.
114 void ZOOM_connection_option_set(ZOOM_connection c,
115 const char *key, const char *val);
117 void ZOOM_connection_option_setl(ZOOM_connection c,
119 const char *val, int len);
121 const char *ZOOM_connection_option_get(ZOOM_connection c,
123 const char *ZOOM_connection_option_getl(ZOOM_connection c,
128 The functions <function>ZOOM_connection_option_set</function> and
129 <function>ZOOM_connection_option_setl</function> allows you to
130 set an option given by <parameter>key</parameter> to the value
131 <parameter>value</parameter> for the connection.
132 For <function>ZOOM_connection_option_set</function>, the
133 value is assumed to be a 0-terminated string. Function
134 <function>ZOOM_connection_option_setl</function> specifies a
135 value of a certain size (len).
138 Functions <function>ZOOM_connection_option_get</function> and
139 <function>ZOOM_connection_option_getl</function> returns
140 the value for an option given by <parameter>key</parameter>.
142 <table frame="top"><title>ZOOM Connection Options</title>
144 <colspec colwidth="4*" colname="name"></colspec>
145 <colspec colwidth="7*" colname="description"></colspec>
146 <colspec colwidth="3*" colname="default"></colspec>
149 <entry>Option</entry>
150 <entry>Description</entry>
151 <entry>Default</entry>
156 implementationName</entry><entry>Name of Your client
157 </entry><entry>none</entry></row>
159 user</entry><entry>Authentication user name
160 </entry><entry>none</entry></row>
162 group</entry><entry>Authentication group name
163 </entry><entry>none</entry></row>
165 password</entry><entry>Authentication password.
166 </entry><entry>none</entry></row>
168 host</entry><entry>Target host. This setting is "read-only".
169 It's automatically set internally when connecting to a target.
170 </entry><entry>none</entry></row>
172 proxy</entry><entry>Proxy host
173 </entry><entry>none</entry></row>
175 async</entry><entry>If true (1) the connection operates in
176 asynchronous operation which means that all calls are non-blocking
178 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
179 </entry><entry>0</entry></row>
181 maximumRecordSize</entry><entry> Maximum size of single record.
182 </entry><entry>1 MB</entry></row>
184 preferredMessageSize</entry><entry> Maximum size of multiple records.
185 </entry><entry>1 MB</entry></row>
187 lang</entry><entry> Language for negotiation.
188 </entry><entry>none</entry></row>
190 charset</entry><entry> Character set for negotiation.
191 </entry><entry>none</entry></row>
193 serverImplementationId</entry><entry>
194 Implementation ID of server. (The old targetImplementationId
195 option is also supported for the benefit of old applications.)
196 </entry><entry>none</entry></row>
198 targetImplementationName</entry><entry>
199 Implementation Name of server. (The old
200 targetImplementationName option is also supported for the
201 benefit of old applications.)
202 </entry><entry>none</entry></row>
204 serverImplementationVersion</entry><entry>
205 Implementation Version of server. (the old
206 targetImplementationVersion option is also supported for the
207 benefit of old applications.)
208 </entry><entry>none</entry></row>
210 databaseName</entry><entry>One or more database names
211 separated by character plus (<literal>+</literal>), which to
212 be used by subsequent search requests on this Connection.
213 </entry><entry>Default</entry></row>
215 piggyback</entry><entry>True (1) if piggyback should be
216 used in searches; false (0) if not.
217 </entry><entry>1</entry></row>
219 smallSetUpperBound</entry><entry>If hits is less than or equal to this
220 value, then target will return all records using small element set name
221 </entry><entry>0</entry></row>
223 largeSetLowerBound</entry><entry>If hits is greater than this
224 value, the target will return no records.
225 </entry><entry>1</entry></row>
227 mediumSetPresentNumber</entry><entry>This value represents
228 the number of records to be returned as part of a search when when
229 hits is less than or equal to large set lower bound and if hits
230 is greater than small set upper bound.
231 </entry><entry>0</entry></row>
233 smallSetElementSetName</entry><entry>
234 The element set name to be used for small result sets.
235 </entry><entry>none</entry></row>
237 mediumSetElementSetName</entry><entry>
238 The element set name to be for medium-sized result sets.
239 </entry><entry>none</entry></row>
244 If either option <literal>lang</literal> or <literal>charset</literal>
246 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
247 Character Set and Language Negotiation</ulink> is in effect.
250 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
251 const char **addinfo);
252 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
253 const char **addinfo, const char **dset);
256 Function <function>ZOOM_connection_error</function> checks for
257 errors for the last operation(s) performed. The function returns
258 zero if no errors occurred; non-zero otherwise indicating the error.
259 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
260 holds messages for the error and additional-info if passed as
261 non-<literal>NULL</literal>. Function
262 <function>ZOOM_connection_error_x</function> is an extended version
263 of <function>ZOOM_connection_error</function> that is capable of
264 returning name of diagnostic set in <parameter>dset</parameter>.
266 <sect2><title>Z39.50 Protocol behavior</title>
268 The calls <function>ZOOM_connection_new</function> and
269 <function>ZOOM_connection_connect</function> establishes a TCP/IP
270 connection and sends an Initialize Request to the target if
271 possible. In addition, the calls waits for an Initialize Response
272 from the target and the result is inspected (OK or rejected).
275 If <literal>proxy</literal> is set then the client will establish
276 a TCP/IP connection with the peer as specified by the
277 <literal>proxy</literal> host and the hostname as part of the
278 connect calls will be set as part of the Initialize Request.
279 The proxy server will then "forward" the PDU's transparently
280 to the target behind the proxy.
283 For the authentication parameters, if option <literal>user</literal>
284 is set and both options <literal>group</literal> and
285 <literal>pass</literal> are unset, then Open style
286 authentication is used (Version 2/3) in which case the username
287 is usually followed by a slash, then by a password.
288 If either <literal>group</literal>
289 or <literal>pass</literal> is set then idPass authentication
290 (Version 3 only) is used. If none of the options are set, no
291 authentication parameters are set as part of the Initialize Request
295 When option <literal>async</literal> is 1, it really means that
296 all network operations are postponed (and queued) until the
297 function <literal>ZOOM_event</literal> is invoked. When doing so
298 it doesn't make sense to check for errors after
299 <literal>ZOOM_connection_new</literal> is called since that
300 operation "connecting - and init" is still incomplete and the
301 API cannot tell the outcome (yet).
304 <sect2><title>SRW Protocol behavior</title>
306 The SRW protocol doesn't feature an Inititialize Request, so
307 the connection phase merely establishes a TCP/IP connection
308 with the SOAP service.
310 <para>Most of the ZOOM connection options do not
311 affect SRW and they are ignored. However, future versions
312 of &yaz; might honor <literal>implementationName</literal> and
313 put that as part of User-Agent header for HTTP requests.
316 The <literal>charset</literal> is used in the Content-Type header
321 <sect1 id="zoom.query"><title>Queries</title>
323 Query objects represents queries.
326 ZOOM_query ZOOM_query_create(void);
328 void ZOOM_query_destroy(ZOOM_query q);
330 int ZOOM_query_prefix(ZOOM_query q, const char *str);
332 int ZOOM_query_cql(ZOOM_query s, const char *str);
334 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
337 Create query objects using <function>ZOOM_query_create</function>
338 and destroy them by calling <function>ZOOM_query_destroy</function>.
339 RPN-queries can be specified in <link linkend="PQF">PQF</link>
340 notation by using the
341 function <function>ZOOM_query_prefix</function>.
342 The <function>ZOOM_query_cql</function> specifies a CQL
343 query to be sent to the server/target.
344 More query types will be added in future versions of &yaz;, such as
345 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
346 etc. In addition to a search, a sort criteria may be set. Function
347 <function>ZOOM_query_sortby</function> specifies a
348 sort criteria using the same string notation for sort as offered by
349 the <link linkend="sortspec">YAZ client</link>.
351 <sect2><title>Protocol behavior</title>
353 The query object is just an interface for the member Query
354 in the SearchRequest. The sortby-function is an interface to the
355 sortSequence member of the SortRequest.
359 <sect1 id="zoom.resultsets"><title>Result sets</title>
361 The result set object is a container for records returned from
365 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
368 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
371 void ZOOM_resultset_destroy(ZOOM_resultset r);
374 Function <function>ZOOM_connection_search</function> creates
375 a result set given a connection and query.
376 Destroy a result set by calling
377 <function>ZOOM_resultset_destroy</function>.
378 Simple clients may using PQF only may use function
379 <function>ZOOM_connection_search_pqf</function> in which case
380 creating query objects is not necessary.
383 void ZOOM_resultset_option_set (ZOOM_resultset r,
387 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
390 size_t ZOOM_resultset_size (ZOOM_resultset r);
393 Functions <function>ZOOM_resultset_options_set</function> and
394 <function>ZOOM_resultset_get</function> sets and gets an option
395 for a result set similar to <function>ZOOM_connection_option_get</function>
396 and <function>ZOOM_connection_option_set</function>.
399 The number of hits also called result-count is returned by
400 function <function>ZOOM_resultset_size</function>.
402 <table frame="top"><title>ZOOM Result set Options</title>
404 <colspec colwidth="4*" colname="name"></colspec>
405 <colspec colwidth="7*" colname="description"></colspec>
406 <colspec colwidth="2*" colname="default"></colspec>
409 <entry>Option</entry>
410 <entry>Description</entry>
411 <entry>Default</entry>
416 start</entry><entry>Offset of first record to be
417 retrieved from target. First record has offset 0 unlike the
418 protocol specifications where first record has position 1.
419 </entry><entry>0</entry></row>
421 count</entry><entry>Number of records to be retrieved.
422 </entry><entry>0</entry></row>
424 presentChunk</entry><entry>The number of records to be
425 requested from the server in each chunk (present requst). The
426 value 0 means to request all the records in a single chunk.
427 (The old <literal>step</literal>
428 option is also supported for the benefit of old applications.)
429 </entry><entry>0</entry></row>
431 elementSetName</entry><entry>Element-Set name of records.
432 Most targets should honor element set name <literal>B</literal>
433 and <literal>F</literal> for brief and full respectively.
434 </entry><entry>none</entry></row>
436 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
437 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
438 </entry><entry>none</entry></row>
440 schema</entry><entry>Schema for retrieval, such as
441 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
442 </entry><entry>none</entry></row>
444 setname</entry><entry>Name of Result Set (Result Set ID).
445 If this option isn't set, the ZOOM module will automatically
446 allocate a result set name.
447 </entry><entry>default</entry></row>
452 For servers that support Search Info report, the following
453 options may be read using <function>ZOOM_resultset_get</function>.
454 This detailed information is read after a successful search has
458 This information is a list of of items, where each item is
459 information about a term or subquery. All items in the list
461 <literal>SearchResult.</literal><replaceable>no</replaceable>
462 where no presents the item number (0=first, 1=second).
463 Read <literal>searchresult.size</literal> to determine the
466 <table frame="top"><title>Search Info Report options</title>
468 <colspec colwidth="4*" colname="name"></colspec>
469 <colspec colwidth="7*" colname="description"></colspec>
472 <entry>Option</entry>
473 <entry>Description</entry>
478 <entry>searchresult.size</entry>
480 number of search result entries. This option is-nonexistant
481 if no entries are returned by the server.
485 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
486 <entry>sub query ID</entry>
489 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
490 <entry>result count for item (number of hits)</entry>
493 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
494 <entry>subquery term</entry>
498 searchresult.<replaceable>no</replaceable>.interpretation.term
500 <entry>interpretation term</entry>
504 searchresult.<replaceable>no</replaceable>.recommendation.term
506 <entry>recommendation term</entry>
512 <title>Z39.50 Protocol behavior</title>
514 The creation of a result set involves at least a SearchRequest
515 - SearchResponse protocol handshake. Following that, if a sort
516 criteria was specified as part of the query, a SortRequest -
517 SortResponse handshake takes place. Note that it is necessary to
518 perform sorting before any retrieval takes place, so no records will
519 be returned from the target as part of the SearchResponse because these
520 would be unsorted. Hence, piggyback is disabled when sort criteria
521 are set. Following Search - and a possible sort - Retrieval takes
522 place - as one or more Present Requests/Response pairs being
526 The API allows for two different modes for retrieval. A high level
527 mode which is somewhat more powerful and a low level one.
528 The low level is enabled when searching on a Connection object
529 for which the settings
530 <literal>smallSetUpperBound</literal>,
531 <literal>mediumSetPresentNumber</literal> and
532 <literal>largeSetLowerBound</literal> are set. The low level mode
533 thus allows you to precisely set how records are returned as part
534 of a search response as offered by the Z39.50 protocol.
535 Since the client may be retrieving records as part of the
536 search response, this mode doesn't work well if sorting is used.
539 The high-level mode allows you to fetch a range of records from
540 the result set with a given start offset. When you use this mode
541 the client will automatically use piggyback if that is possible
542 with the target and perform one or more present requests as needed.
543 Even if the target returns fewer records as part of a present response
544 because of a record size limit, etc. the client will repeat sending
545 present requests. As an example, if option <literal>start</literal>
546 is 0 (default) and <literal>count</literal> is 4, and
547 <literal>piggyback</literal> is 1 (default) and no sorting criteria
548 is specified, then the client will attempt to retrieve the 4
549 records as part the search response (using piggyback). On the other
550 hand, if either <literal>start</literal> is positive or if
551 a sorting criteria is set, or if <literal>piggyback</literal>
552 is 0, then the client will not perform piggyback but send Present
556 If either of the options <literal>mediumSetElementSetName</literal> and
557 <literal>smallSetElementSetName</literal> are unset, the value
558 of option <literal>elementSetName</literal> is used for piggyback
559 searches. This means that for the high-level mode you only have
560 to specify one elementSetName option rather than three.
564 <title>SRW Protocol behavior</title>
566 Current version of &yaz; does not take advantage of a result set id
567 returned by the SRW server. Future versions might do, however.
568 Since, the ZOOM driver does not save result set IDs any
569 present (retrieval) is transformed to a SRW SearchRetrieveRequest
570 with same query but, possibly, different offsets.
573 Option <literal>schema</literal> specifies SRW schema
574 for retrieval. However, options <literal>elementSetName</literal> and
575 <literal>preferredRecordSyntax</literal> are ignored.
578 Options <literal>start</literal> and <literal>count</literal>
579 are supported by SRW.
580 The remaining options
581 <literal>piggyback</literal>,
582 <literal>smallSetUpperBound</literal>,
583 <literal>largeSetLowerBound</literal>,
584 <literal>mediumSetPresentNumber</literal>,
585 <literal>mediumSetElementSetName</literal>,
586 <literal>smallSetElementSetName</literal> are
590 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
591 If PQF is used, however, the PQF query is transferred anyway
592 using non-standard element <literal>pQuery</literal> in
593 SRW SearchRetrieveRequest.
596 Unfortunately, SRW does not define a database setting. Hence,
597 <literal>databaseName</literal> is unsupported and ignored.
598 However, the path part in host parameter for functions
599 <function>ZOOM_connecton_new</function> and
600 <function>ZOOM_connection_connect</function> acts as a
601 database (at least for the &yaz; SRW server).
605 <sect1 id="zoom.records"><title>Records</title>
607 A record object is a retrieval record on the client side -
608 created from result sets.
611 void ZOOM_resultset_records (ZOOM_resultset r,
613 size_t start, size_t count);
614 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
616 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
619 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
621 void ZOOM_record_destroy (ZOOM_record rec);
624 References to temporary records are returned by functions
625 <function>ZOOM_resultset_records</function> or
626 <function>ZOOM_resultset_record</function>.
629 If a persistent reference to a record is desired
630 <function>ZOOM_record_clone</function> should be used.
631 It returns a record reference that should be destroyed
632 by a call to <function>ZOOM_record_destroy</function>.
635 A single record is returned by function
636 <function>ZOOM_resultset_record</function> that takes a
637 position as argument. First record has position zero.
638 If no record could be obtained <literal>NULL</literal> is returned.
641 Function <function>ZOOM_resultset_records</function> retrieves
642 a number of records from a result set. Parameter <literal>start</literal>
643 and <literal>count</literal> specifies the range of records to
644 be returned. Upon completion array
645 <literal>recs[0], ..recs[count-1]</literal>
646 holds record objects for the records. The array of records
647 <literal>recs</literal> should be allocated prior the call
648 <function>ZOOM_resultset_records</function>. Note that for those
649 records that couldn't be retrieved from the target
650 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
652 <para id="zoom.record.get">
653 In order to extract information about a single record,
654 <function>ZOOM_record_get</function> is provided. The
655 function returns a pointer to certain record information. The
656 nature (type) of the pointer depends on the parameter,
657 <parameter>type</parameter>.
660 The <parameter>type</parameter> is a string of the format:
663 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
666 where <replaceable>form</replaceable> specifies the format of the
667 returned record, <replaceable>from</replaceable>
668 specifies the character set of the record in its original form
669 (as returned by the server), <replaceable>to</replaceable> specifies
670 the output (returned)
671 character set encoding.
672 If charset is not given, then no character set conversion takes place.
673 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
676 In addition, for certain types, the length
677 <literal>len</literal> passed will be set to the size in bytes of
678 the returned information.
681 The following are the supported values for <replaceable>form</replaceable>.
683 <varlistentry><term><literal>database</literal></term>
684 <listitem><para>Database of record is returned
685 as a C null-terminated string. Return type
686 <literal>const char *</literal>.
689 <varlistentry><term><literal>syntax</literal></term>
690 <listitem><para>The transfer syntax of the record is returned
691 as a C null-terminated string containing the symbolic name of
692 the record syntax, e.g. <literal>Usmarc</literal>. Return type
694 <literal>const char *</literal>.
697 <varlistentry><term><literal>render</literal></term>
698 <listitem><para>The record is returned in a display friendly
699 format. Upon completion buffer is returned
700 (type <literal>const char *</literal>) and length is stored in
701 <literal>*len</literal>.
704 <varlistentry><term><literal>raw</literal></term>
705 <listitem><para>The record is returned in the internal
706 YAZ specific format. For GRS-1, Explain, and others, the
707 raw data is returned as type
708 <literal>Z_External *</literal> which is just the type for
709 the member <literal>retrievalRecord</literal> in
710 type <literal>NamePlusRecord</literal>.
711 For SUTRS and octet aligned record (including all MARCs) the
712 octet buffer is returned and the length of the buffer.
715 <varlistentry><term><literal>xml</literal></term>
716 <listitem><para>The record is returned in XML if possible.
717 SRW/SRU and Z39.50 records with transfer syntax XML are
718 returned verbatim. MARC records are returned in
719 <ulink url="http://www.loc.gov/standards/marcxml/">
722 (converted from ISO2709 to MARCXML by YAZ).
723 GRS-1 and OPAC records are not supported for this form.
724 Upon completion, the XML buffer is returned
725 (type <literal>const char *</literal>) and length is stored in
726 <literal>*len</literal>.
729 <varlistentry><term><literal>opac</literal></term>
730 <listitem><para>OPAC for record is returned in XML.
737 <ulink url="http://www.loc.gov/marc/">
741 <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
744 character set encoding.
745 An application that wishes to display in Latin-1 would use
747 render; charset=marc8,iso-8859-1
750 <sect2><title>Z39.50 Protocol behavior</title>
752 The functions <function>ZOOM_resultset_record</function> and
753 <function>ZOOM_resultset_records</function> inspects the client-side
754 record cache. Records not found in cache are fetched using
756 The functions may block (and perform network I/O) - even though option
757 <literal>async</literal> is 1, because they return records objects.
758 (and there's no way to return records objects without retrieving them!).
761 There is a trick, however, in the usage of function
762 <function>ZOOM_resultset_records</function> that allows for
763 delayed retrieval (and makes it non-blocking). By using
764 a null pointer for <parameter>recs</parameter> you're indicating
765 you're not interested in getting records objects
766 <emphasis>now</emphasis>.
769 <sect2><title>SRW Protocol behavior</title>
771 The ZOOM driver for SRW treats records returned by a SRW server
772 as if they where Z39.50 records with transfer syntax XML and
773 no element set name or database name.
777 <sect1 id="zoom.scan"><title>Scan</title>
779 This section describes an interface for Scan. Scan is not an
780 official part of the ZOOM model yet. The result of a scan operation
781 is the <literal>ZOOM_scanset</literal> which is a set of terms
782 returned by a target.
786 The Scan interface is Z39.50 only. SRW version 1.0 does not
791 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
792 const char *startpqf);
794 size_t ZOOM_scanset_size(ZOOM_scanset scan);
796 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
797 int *occ, size_t *len);
799 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
800 int *occ, size_t *len);
802 void ZOOM_scanset_destroy (ZOOM_scanset scan);
804 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
807 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
811 The scan set is created by function
812 <function>ZOOM_connection_scan</function> which performs a scan
813 operation on the connection using the specified
814 <parameter>startpqf</parameter>.
815 If the operation was successful, the size of the scan set can be
816 retrieved by a call to <function>ZOOM_scanset_size</function>.
817 Like result sets, the items are numbered 0,..size-1.
818 To obtain information about a particular scan term, call function
819 <function>ZOOM_scanset_term</function>. This function takes
820 a scan set offset <literal>pos</literal> and returns a pointer
821 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
823 If present, the <literal>occ</literal> and <literal>len</literal>
824 are set to the number of occurrences and the length
825 of the actual term respectively.
826 <function>ZOOM_scanset_display_term</function> is similar to
827 <function>ZOOM_scanset_term</function> except that it returns
828 the <emphasis>display term</emphasis> rather than the raw term.
829 In a few cases, the term is different from display term. Always
830 use the display term for display and the raw term for subsequent
831 scan operations (to get more terms, next scan result, etc).
834 A scan set may be freed by a call to function
835 <function>ZOOM_scanset_destroy</function>.
836 Functions <function>ZOOM_scanset_option_get</function> and
837 <function>ZOOM_scanset_option_set</function> retrieves and sets
838 an option respectively.
842 The <parameter>startpqf</parameter> is a subset of PQF, namely
843 the Attributes+Term part. Multiple <literal>@attr</literal> can
844 be used. For example to scan in title (complete) phrases:
846 @attr 1=4 @attr 6=2 "science o"
850 <table frame="top"><title>ZOOM Scan Set Options</title>
852 <colspec colwidth="4*" colname="name"></colspec>
853 <colspec colwidth="7*" colname="description"></colspec>
854 <colspec colwidth="2*" colname="default"></colspec>
857 <entry>Option</entry>
858 <entry>Description</entry>
859 <entry>Default</entry>
864 number</entry><entry>Number of Scan Terms requested in next scan.
865 After scan it holds the actual number of terms returned.
866 </entry><entry>10</entry></row>
868 position</entry><entry>Preferred Position of term in response
869 in next scan; actual position after completion of scan.
870 </entry><entry>1</entry></row>
872 stepSize</entry><entry>Step Size
873 </entry><entry>0</entry></row>
875 scanStatus</entry><entry>An integer indicating the Scan Status
877 </entry><entry>0</entry></row>
883 <sect1 id="zoom.ext"><title>Extended Services</title>
885 ZOOM offers an interface to a subset of the Z39.50 extended services
886 as well as a few privately defined ones:
891 Z39.50 Item Order (ILL).
892 See <xref linkend="zoom.ext.itemorder"/>.
897 Record Update. This allows a client to insert, modify or delete
899 See <xref linkend="zoom.ext.update"/>.
904 Database Create. This a non-standard feature. Allows a client
905 to create a database.
906 See <xref linkend="zoom.ext.dbcreate"/>.
911 Database Drop. This a non-standard feature. Allows a client
912 to delete/drop a database.
913 See <xref linkend="zoom.ext.dbdrop"/>.
918 Commit operation. This a non-standard feature. Allows a client
919 to commit operations.
920 See <xref linkend="zoom.ext.commit"/>.
923 <!-- all the ILL PDU options should go here too -->
926 To create an extended service operation a <literal>ZOOM_package</literal>
927 must be created. The operation is a five step operation. The
928 package is created, package is configured by means of options,
929 the package is send, result is inspected (by means of options),
930 the package is destroyed.
933 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
934 ZOOM_options options);
936 const char *ZOOM_package_option_get(ZOOM_package p,
938 void ZOOM_package_option_set(ZOOM_package p, const char *key,
940 void ZOOM_package_send(ZOOM_package p, const char *type);
942 void ZOOM_package_destroy(ZOOM_package p);
945 The <function>ZOOM_connection_package</function> creates a
946 package for the connection given using the options specified.
949 Functions <function>ZOOM_package_option_get</function> and
950 <function>ZOOM_package_option_set</function> gets and sets
954 <function>ZOOM_package_send</function> sends
955 the package the via connection specified in
956 <function>ZOOM_connection_package</function>.
957 The <parameter>type</parameter> specifies the actual extended service
958 package type to be sent.
961 <table frame="top"><title>Extended Service Common Options</title>
963 <colspec colwidth="4*" colname="name"></colspec>
964 <colspec colwidth="7*" colname="description"></colspec>
965 <colspec colwidth="3*" colname="default"></colspec>
968 <entry>Option</entry>
969 <entry>Description</entry>
970 <entry>Default</entry>
975 <entry>package-name</entry>
976 <entry>Extended Service Request package name. Must be specified
977 as part of a request</entry>
981 <entry>user-id</entry>
982 <entry>User ID of Extended Service Package. Is a request option</entry>
986 <entry>function</entry>
988 Function of package - one of <literal>create</literal>,
989 <literal>delete</literal>, <literal>modify</literal>. Is
992 <entry><literal>create</literal></entry>
995 <entry>targetReference</entry>
997 Target Reference. This is part of the response as returned
998 by the server. Read it after a succesful operation.
1000 <entry><literal>none</literal></entry>
1006 <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
1008 For Item Order, type must be set to <literal>itemorder</literal> in
1009 <function>ZOOM_package_send</function>.
1012 <table frame="top"><title>Item Order Options</title>
1014 <colspec colwidth="4*" colname="name"></colspec>
1015 <colspec colwidth="7*" colname="description"></colspec>
1016 <colspec colwidth="3*" colname="default"></colspec>
1019 <entry>Option</entry>
1020 <entry>Description</entry>
1021 <entry>Default</entry>
1026 <entry>contact-name</entry>
1027 <entry>ILL contact name</entry>
1031 <entry>contact-phone</entry>
1032 <entry>ILL contact phone</entry>
1036 <entry>contact-email</entry>
1037 <entry>ILL contact email</entry>
1041 <entry>itemorder-item</entry>
1042 <entry>Position for item (record) requested. An integer</entry>
1051 <sect2 id="zoom.ext.update"><title>Record Update</title>
1053 For Record Update, type must be set to <literal>update</literal> in
1054 <function>ZOOM_package_send</function>.
1057 <table frame="top"><title>Record Update Options</title>
1059 <colspec colwidth="4*" colname="name"></colspec>
1060 <colspec colwidth="7*" colname="description"></colspec>
1061 <colspec colwidth="3*" colname="default"></colspec>
1064 <entry>Option</entry>
1065 <entry>Description</entry>
1066 <entry>Default</entry>
1071 <entry>action</entry>
1073 The update action. One of
1074 <literal>specialUpdate</literal>,
1075 <literal>recordInsert</literal>,
1076 <literal>recordReplace</literal>,
1077 <literal>recordDelete</literal>,
1078 <literal>elementUpdate</literal>.
1080 <entry><literal>specialUpdate</literal></entry>
1083 <entry>recordIdOpaque</entry>
1084 <entry>Opaque Record ID</entry>
1088 <entry>recordIdNumber</entry>
1089 <entry>Record ID number</entry>
1093 <entry>record</entry>
1094 <entry>The record itself</entry>
1098 <entry>syntax</entry>
1099 <entry>The record syntax (transfer syntax). Is a string that
1100 is a known record syntax.
1102 <entry>no syntax</entry>
1105 <entry>databaseName</entry>
1106 <entry>Database from connection object</entry>
1107 <entry>Default</entry>
1115 <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
1117 For Database Create, type must be set to <literal>create</literal> in
1118 <function>ZOOM_package_send</function>.
1121 <table frame="top"><title>Database Create Options</title>
1123 <colspec colwidth="4*" colname="name"></colspec>
1124 <colspec colwidth="7*" colname="description"></colspec>
1125 <colspec colwidth="3*" colname="default"></colspec>
1128 <entry>Option</entry>
1129 <entry>Description</entry>
1130 <entry>Default</entry>
1135 <entry>databaseName</entry>
1136 <entry>Database from connection object</entry>
1137 <entry>Default</entry>
1144 <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
1146 For Database Drop, type must be set to <literal>drop</literal> in
1147 <function>ZOOM_package_send</function>.
1150 <table frame="top"><title>Database Create Options</title>
1152 <colspec colwidth="4*" colname="name"></colspec>
1153 <colspec colwidth="7*" colname="description"></colspec>
1154 <colspec colwidth="3*" colname="default"></colspec>
1157 <entry>Option</entry>
1158 <entry>Description</entry>
1159 <entry>Default</entry>
1164 <entry>databaseName</entry>
1165 <entry>Database from connection object</entry>
1166 <entry>Default</entry>
1173 <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
1175 For Commit, type must be set to <literal>commit</literal> in
1176 <function>ZOOM_package_send</function>.
1180 <sect2><title>Protocol behavior</title>
1182 All the extended services are Z39.50-only.
1186 The database create, drop and commit services are privately defined
1188 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1195 <sect1 id="zoom.options"><title>Options</title>
1197 Most &zoom; objects provide a way to specify options to change behavior.
1198 From an implementation point of view a set of options is just like
1199 an associative array / hash.
1202 ZOOM_options ZOOM_options_create (void);
1204 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1206 void ZOOM_options_destroy (ZOOM_options opt);
1209 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1211 void ZOOM_options_set (ZOOM_options opt, const char *name,
1215 typedef const char *(*ZOOM_options_callback)
1216 (void *handle, const char *name);
1218 ZOOM_options_callback
1219 ZOOM_options_set_callback (ZOOM_options opt,
1220 ZOOM_options_callback c,
1224 <sect1 id="zoom.events"><title>Events</title>
1226 If you're developing non-blocking applications, you have to deal
1230 int ZOOM_event (int no, ZOOM_connection *cs);
1233 The <function>ZOOM_event</function> executes pending events for
1234 a number of connections. Supply the number of connections in
1235 <literal>no</literal> and an array of connections in
1236 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1237 A pending event could be a sending a search, receiving a response,
1239 When an event has occurred for one of the connections, this function
1240 returns a positive integer <literal>n</literal> denoting that an event
1241 occurred for connection <literal>cs[n-1]</literal>.
1242 When no events are pending for the connections, a value of zero is
1244 To ensure that all outstanding requests are performed call this function
1245 repeatedly until zero is returned.
1248 If <function>ZOOM_event</function> returns and returns non-zero, the
1249 last event that occurred can be expected.
1252 int ZOOM_connection_last_event(ZOOM_connection cs);
1255 <function>ZOOM_connection_last_event</function> returns an event type
1256 (integer) for the last event.
1259 <table frame="top"><title>ZOOM Event IDs</title>
1261 <colspec colwidth="4*" colname="name"></colspec>
1262 <colspec colwidth="7*" colname="description"></colspec>
1265 <entry>Event</entry>
1266 <entry>Description</entry>
1271 <entry>ZOOM_EVENT_NONE</entry>
1272 <entry>No event has occurred</entry>
1275 <entry>ZOOM_EVENT_CONNECT</entry>
1276 <entry>TCP/IP connect has initiated</entry>
1279 <entry>ZOOM_EVENT_SEND_DATA</entry>
1280 <entry>Data has been transmitted (sending)</entry>
1283 <entry>ZOOM_EVENT_RECV_DATA</entry>
1284 <entry>Data has been received)</entry>
1287 <entry>ZOOM_EVENT_TIMEOUT</entry>
1288 <entry>Timeout</entry>
1291 <entry>ZOOM_EVENT_UNKNOWN</entry>
1292 <entry>Unknown event</entry>
1295 <entry>ZOOM_EVENT_SEND_APDU</entry>
1296 <entry>An APDU has been transmitted (sending)</entry>
1299 <entry>ZOOM_EVENT_RECV_APDU</entry>
1300 <entry>An APDU has been received</entry>
1303 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1304 <entry>A result-set record has been received</entry>
1307 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1308 <entry>A search result been received</entry>
1316 <!-- Keep this comment at the end of the file
1321 sgml-minimize-attributes:nil
1322 sgml-always-quote-attributes:t
1325 sgml-parent-document: "yaz.xml"
1326 sgml-local-catalogs: nil
1327 sgml-namecase-general:t