3 ZOOM_connection_option_getl(c, key, len)
4 ZOOM_connection_option_setl(c, key, val, len)
5 ZOOM_connection_errcode(c)
6 ZOOM_connection_errmsg(c)
7 ZOOM_connection_addinfo(c)
9 ZOOM_resultset_record_immediate(s, pos)
10 ZOOM_resultset_cache_reset(r)
11 ZOOM_connection_package(c, options)
12 ZOOM_package_destroy(p)
13 ZOOM_package_send(p, type)
14 ZOOM_package_option_get(p, key)
15 ZOOM_package_option_set(p, key, val)
16 ZOOM_resultset_sort(r, sort_type, sort_spec)
17 ZOOM_options_set_callback(opt, function, handle)
18 ZOOM_options_create_with_parent2(parent1, parent2)
19 ZOOM_options_getl(opt, name, len)
20 ZOOM_options_setl(opt, name, value, len)
21 ZOOM_options_get_bool(opt, name, defa)
22 ZOOM_options_get_int(opt, name, defa)
23 ZOOM_options_set_int(opt, name, value)
26 <!-- $Id: zoom.xml,v 1.41 2005-11-02 14:54:01 mike Exp $ -->
27 <chapter id="zoom"><title>ZOOM</title>
29 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
30 an initiative started by Mike Taylor (Mike is from the UK, which
31 explains the peculiar name of the model). The goal of &zoom; is to
32 provide a common Z39.50 client API not bound to a particular
33 programming language or toolkit.
38 A recent addition to &yaz; is SRW support. You can now make
39 SRW ZOOM connections by specifying scheme <literal>http://</literal>
40 for the hostname for a connection.
45 The lack of a simple Z39.50 client API for &yaz; has become more
46 and more apparent over time. So when the first &zoom; specification
48 an implementation for &yaz; was quickly developed. For the first time, it is
49 now as easy (or easier!) to develop clients than servers with &yaz;. This
50 chapter describes the &zoom; C binding. Before going further, please
51 reconsider whether C is the right programming language for the job.
52 There are other language bindings available for &yaz;, and still
54 are in active development. See the
55 <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
60 In order to fully understand this chapter you should read and
61 try the example programs <literal>zoomtst1.c</literal>,
62 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
67 The C language misses features found in object oriented languages
68 such as C++, Java, etc. For example, you'll have to manually,
69 destroy all objects you create, even though you may think of them as
70 temporary. Most objects has a <literal>_create</literal> - and a
71 <literal>_destroy</literal> variant.
72 All objects are in fact pointers to internal stuff, but you don't see
73 that because of typedefs. All destroy methods should gracefully ignore a
74 <literal>NULL</literal> pointer.
77 In each of the sections below you'll find a sub section called
78 protocol behavior, that describes how the API maps to the Z39.50
81 <sect1 id="zoom.connections"><title>Connections</title>
83 <para>The Connection object is a session with a target.
86 #include <yaz/zoom.h>
88 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
90 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
92 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
94 void ZOOM_connection_destroy (ZOOM_connection c);
97 Connection objects are created with either function
98 <function>ZOOM_connection_new</function> or
99 <function>ZOOM_connection_create</function>.
100 The former creates and automatically attempts to establish a network
101 connection with the target. The latter doesn't establish
102 a connection immediately, thus allowing you to specify options
103 before establishing network connection using the function
104 <function>ZOOM_connection_connect</function>.
105 If the port number, <literal>portnum</literal>, is zero, the
106 <literal>host</literal> is consulted for a port specification.
107 If no port is given, 210 is used. A colon denotes the beginning of
108 a port number in the host string. If the host string includes a
109 slash, the following part specifies a database for the connection.
112 You can prefix the host with a scheme followed by colon. The
113 default scheme is <literal>tcp</literal> (Z39.50 protocol).
114 The scheme <literal>http</literal> selects SRW over HTTP.
117 Connection objects should be destroyed using the function
118 <function>ZOOM_connection_destroy</function>.
121 void ZOOM_connection_option_set (ZOOM_connection c,
125 const char *ZOOM_connection_option_get (ZOOM_connection c,
129 The <function>ZOOM_connection_option_set</function> allows you to
130 set an option given by <parameter>key</parameter> to the value
131 <parameter>value</parameter> for the connection.
132 Function <function>ZOOM_connection_option_get</function> returns
133 the value for an option given by <parameter>key</parameter>.
135 <table frame="top"><title>ZOOM Connection Options</title>
137 <colspec colwidth="4*" colname="name"></colspec>
138 <colspec colwidth="7*" colname="description"></colspec>
139 <colspec colwidth="3*" colname="default"></colspec>
142 <entry>Option</entry>
143 <entry>Description</entry>
144 <entry>Default</entry>
149 implementationName</entry><entry>Name of Your client
150 </entry><entry>none</entry></row>
152 user</entry><entry>Authentication user name
153 </entry><entry>none</entry></row>
155 group</entry><entry>Authentication group name
156 </entry><entry>none</entry></row>
158 password</entry><entry>Authentication password.
159 </entry><entry>none</entry></row>
161 host</entry><entry>Target host. This setting is "read-only".
162 It's automatically set internally when connecting to a target.
163 </entry><entry>none</entry></row>
165 proxy</entry><entry>Proxy host
166 </entry><entry>none</entry></row>
168 async</entry><entry>If true (1) the connection operates in
169 asynchronous operation which means that all calls are non-blocking
171 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
172 </entry><entry>0</entry></row>
174 maximumRecordSize</entry><entry> Maximum size of single record.
175 </entry><entry>1 MB</entry></row>
177 preferredMessageSize</entry><entry> Maximum size of multiple records.
178 </entry><entry>1 MB</entry></row>
180 lang</entry><entry> Language for negotiation.
181 </entry><entry>none</entry></row>
183 charset</entry><entry> Character set for negotiation.
184 </entry><entry>none</entry></row>
186 serverImplementationId</entry><entry>
187 Implementation ID of server. (The old targetImplementationId
188 option is also supported for the benefit of old applications.)
189 </entry><entry>none</entry></row>
191 targetImplementationName</entry><entry>
192 Implementation Name of server. (The old
193 targetImplementationName option is also supported for the
194 benefit of old applications.)
195 </entry><entry>none</entry></row>
197 serverImplementationVersion</entry><entry>
198 Implementation Version of server. (the old
199 targetImplementationVersion option is also supported for the
200 benefit of old applications.)
201 </entry><entry>none</entry></row>
203 databaseName</entry><entry>One or more database names
204 separated by character plus (<literal>+</literal>), which to
205 be used by subsequent search requests on this Connection.
206 </entry><entry>Default</entry></row>
208 piggyback</entry><entry>True (1) if piggyback should be
209 used in searches; false (0) if not.
210 </entry><entry>1</entry></row>
212 smallSetUpperBound</entry><entry>If hits is less than or equal to this
213 value, then target will return all records using small element set name
214 </entry><entry>0</entry></row>
216 largeSetLowerBound</entry><entry>If hits is greater than this
217 value, the target will return no records.
218 </entry><entry>1</entry></row>
220 mediumSetPresentNumber</entry><entry>This value represents
221 the number of records to be returned as part of a search when when
222 hits is less than or equal to large set lower bound and if hits
223 is greater than small set upper bound.
224 </entry><entry>0</entry></row>
226 smallSetElementSetName</entry><entry>
227 The element set name to be used for small result sets.
228 </entry><entry>none</entry></row>
230 mediumSetElementSetName</entry><entry>
231 The element set name to be for medium-sized result sets.
232 </entry><entry>none</entry></row>
237 If either option <literal>lang</literal> or <literal>charset</literal>
239 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
240 Character Set and Language Negotiation</ulink> is in effect.
243 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
244 const char **addinfo);
245 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
246 const char **addinfo, const char **dset);
249 Function <function>ZOOM_connection_error</function> checks for
250 errors for the last operation(s) performed. The function returns
251 zero if no errors occurred; non-zero otherwise indicating the error.
252 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
253 holds messages for the error and additional-info if passed as
254 non-<literal>NULL</literal>. Function
255 <function>ZOOM_connection_error_x</function> is an extended version
256 of <function>ZOOM_connection_error</function> that is capable of
257 returning name of diagnostic set in <parameter>dset</parameter>.
259 <sect2><title>Z39.50 Protocol behavior</title>
261 The calls <function>ZOOM_connection_new</function> and
262 <function>ZOOM_connection_connect</function> establishes a TCP/IP
263 connection and sends an Initialize Request to the target if
264 possible. In addition, the calls waits for an Initialize Response
265 from the target and the result is inspected (OK or rejected).
268 If <literal>proxy</literal> is set then the client will establish
269 a TCP/IP connection with the peer as specified by the
270 <literal>proxy</literal> host and the hostname as part of the
271 connect calls will be set as part of the Initialize Request.
272 The proxy server will then "forward" the PDU's transparently
273 to the target behind the proxy.
276 For the authentication parameters, if option <literal>user</literal>
277 is set and both options <literal>group</literal> and
278 <literal>pass</literal> are unset, then Open style
279 authentication is used (Version 2/3) in which case the username
280 is usually followed by a slash, then by a password.
281 If either <literal>group</literal>
282 or <literal>pass</literal> is set then idPass authentication
283 (Version 3 only) is used. If none of the options are set, no
284 authentication parameters are set as part of the Initialize Request
288 When option <literal>async</literal> is 1, it really means that
289 all network operations are postponed (and queued) until the
290 function <literal>ZOOM_event</literal> is invoked. When doing so
291 it doesn't make sense to check for errors after
292 <literal>ZOOM_connection_new</literal> is called since that
293 operation "connecting - and init" is still incomplete and the
294 API cannot tell the outcome (yet).
297 <sect2><title>SRW Protocol behavior</title>
299 The SRW protocol doesn't feature an Inititialize Request, so
300 the connection phase merely establishes a TCP/IP connection
301 with the SOAP service.
303 <para>Most of the ZOOM connection options do not
304 affect SRW and they are ignored. However, future versions
305 of &yaz; might honor <literal>implementationName</literal> and
306 put that as part of User-Agent header for HTTP requests.
309 The <literal>charset</literal> is used in the Content-Type header
314 <sect1 id="zoom.query"><title>Queries</title>
316 Query objects represents queries.
319 ZOOM_query ZOOM_query_create(void);
321 void ZOOM_query_destroy(ZOOM_query q);
323 int ZOOM_query_prefix(ZOOM_query q, const char *str);
325 int ZOOM_query_cql(ZOOM_query s, const char *str);
327 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
330 Create query objects using <function>ZOOM_query_create</function>
331 and destroy them by calling <function>ZOOM_query_destroy</function>.
332 RPN-queries can be specified in <link linkend="PQF">PQF</link>
333 notation by using the
334 function <function>ZOOM_query_prefix</function>.
335 The <function>ZOOM_query_cql</function> specifies a CQL
336 query to be sent to the server/target.
337 More query types will be added in future versions of &yaz;, such as
338 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
339 etc. In addition to a search, a sort criteria may be set. Function
340 <function>ZOOM_query_sortby</function> specifies a
341 sort criteria using the same string notation for sort as offered by
342 the <link linkend="sortspec">YAZ client</link>.
344 <sect2><title>Protocol behavior</title>
346 The query object is just an interface for the member Query
347 in the SearchRequest. The sortby-function is an interface to the
348 sortSequence member of the SortRequest.
352 <sect1 id="zoom.resultsets"><title>Result sets</title>
354 The result set object is a container for records returned from
358 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
361 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
364 void ZOOM_resultset_destroy(ZOOM_resultset r);
367 Function <function>ZOOM_connection_search</function> creates
368 a result set given a connection and query.
369 Destroy a result set by calling
370 <function>ZOOM_resultset_destroy</function>.
371 Simple clients may using PQF only may use function
372 <function>ZOOM_connection_search_pqf</function> in which case
373 creating query objects is not necessary.
376 void ZOOM_resultset_option_set (ZOOM_resultset r,
380 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
383 size_t ZOOM_resultset_size (ZOOM_resultset r);
386 Functions <function>ZOOM_resultset_options_set</function> and
387 <function>ZOOM_resultset_get</function> sets and gets an option
388 for a result set similar to <function>ZOOM_connection_option_get</function>
389 and <function>ZOOM_connection_option_set</function>.
392 The number of hits also called result-count is returned by
393 function <function>ZOOM_resultset_size</function>.
395 <table frame="top"><title>ZOOM Result set Options</title>
397 <colspec colwidth="4*" colname="name"></colspec>
398 <colspec colwidth="7*" colname="description"></colspec>
399 <colspec colwidth="2*" colname="default"></colspec>
402 <entry>Option</entry>
403 <entry>Description</entry>
404 <entry>Default</entry>
409 start</entry><entry>Offset of first record to be
410 retrieved from target. First record has offset 0 unlike the
411 protocol specifications where first record has position 1.
412 </entry><entry>0</entry></row>
414 count</entry><entry>Number of records to be retrieved.
415 </entry><entry>0</entry></row>
417 presentChunk</entry><entry>The number of records to be
418 requested from the server in each chunk (present requst). The
419 value 0 means to request all the records in a single chunk.
420 (The old <literal>step</literal>
421 option is also supported for the benefit of old applications.)
422 </entry><entry>0</entry></row>
424 elementSetName</entry><entry>Element-Set name of records.
425 Most targets should honor element set name <literal>B</literal>
426 and <literal>F</literal> for brief and full respectively.
427 </entry><entry>none</entry></row>
429 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
430 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
431 </entry><entry>none</entry></row>
433 schema</entry><entry>Schema for retrieval, such as
434 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
435 </entry><entry>none</entry></row>
437 setname</entry><entry>Name of Result Set (Result Set ID).
438 If this option isn't set, the ZOOM module will automatically
439 allocate a result set name.
440 </entry><entry>default</entry></row>
445 For servers that support Search Info report, the following
446 options may be read using <function>ZOOM_resultset_get</function>.
447 This detailed information is read after a successful search has
451 This information is a list of of items, where each item is
452 information about a term or subquery. All items in the list
454 <literal>SearchResult.</literal><replaceable>no</replaceable>
455 where no presents the item number (0=first, 1=second).
456 Read <literal>searchresult.size</literal> to determine the
459 <table frame="top"><title>Search Info Report options</title>
461 <colspec colwidth="4*" colname="name"></colspec>
462 <colspec colwidth="7*" colname="description"></colspec>
465 <entry>Option</entry>
466 <entry>Description</entry>
471 <entry>searchresult.size</entry>
473 number of search result entries. This option is-nonexistant
474 if no entries are returned by the server.
478 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
479 <entry>sub query ID</entry>
482 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
483 <entry>result count for item (number of hits)</entry>
486 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
487 <entry>subquery term</entry>
491 searchresult.<replaceable>no</replaceable>.interpretation.term
493 <entry>interpretation term</entry>
497 searchresult.<replaceable>no</replaceable>.recommendation.term
499 <entry>recommendation term</entry>
505 <title>Z39.50 Protocol behavior</title>
507 The creation of a result set involves at least a SearchRequest
508 - SearchResponse protocol handshake. Following that, if a sort
509 criteria was specified as part of the query, a SortRequest -
510 SortResponse handshake takes place. Note that it is necessary to
511 perform sorting before any retrieval takes place, so no records will
512 be returned from the target as part of the SearchResponse because these
513 would be unsorted. Hence, piggyback is disabled when sort criteria
514 are set. Following Search - and a possible sort - Retrieval takes
515 place - as one or more Present Requests/Response pairs being
519 The API allows for two different modes for retrieval. A high level
520 mode which is somewhat more powerful and a low level one.
521 The low level is enabled when searching on a Connection object
522 for which the settings
523 <literal>smallSetUpperBound</literal>,
524 <literal>mediumSetPresentNumber</literal> and
525 <literal>largeSetLowerBound</literal> are set. The low level mode
526 thus allows you to precisely set how records are returned as part
527 of a search response as offered by the Z39.50 protocol.
528 Since the client may be retrieving records as part of the
529 search response, this mode doesn't work well if sorting is used.
532 The high-level mode allows you to fetch a range of records from
533 the result set with a given start offset. When you use this mode
534 the client will automatically use piggyback if that is possible
535 with the target and perform one or more present requests as needed.
536 Even if the target returns fewer records as part of a present response
537 because of a record size limit, etc. the client will repeat sending
538 present requests. As an example, if option <literal>start</literal>
539 is 0 (default) and <literal>count</literal> is 4, and
540 <literal>piggyback</literal> is 1 (default) and no sorting criteria
541 is specified, then the client will attempt to retrieve the 4
542 records as part the search response (using piggyback). On the other
543 hand, if either <literal>start</literal> is positive or if
544 a sorting criteria is set, or if <literal>piggyback</literal>
545 is 0, then the client will not perform piggyback but send Present
549 If either of the options <literal>mediumSetElementSetName</literal> and
550 <literal>smallSetElementSetName</literal> are unset, the value
551 of option <literal>elementSetName</literal> is used for piggyback
552 searches. This means that for the high-level mode you only have
553 to specify one elementSetName option rather than three.
557 <title>SRW Protocol behavior</title>
559 Current version of &yaz; does not take advantage of a result set id
560 returned by the SRW server. Future versions might do, however.
561 Since, the ZOOM driver does not save result set IDs any
562 present (retrieval) is transformed to a SRW SearchRetrieveRequest
563 with same query but, possibly, different offsets.
566 Option <literal>schema</literal> specifies SRW schema
567 for retrieval. However, options <literal>elementSetName</literal> and
568 <literal>preferredRecordSyntax</literal> are ignored.
571 Options <literal>start</literal> and <literal>count</literal>
572 are supported by SRW.
573 The remaining options
574 <literal>piggyback</literal>,
575 <literal>smallSetUpperBound</literal>,
576 <literal>largeSetLowerBound</literal>,
577 <literal>mediumSetPresentNumber</literal>,
578 <literal>mediumSetElementSetName</literal>,
579 <literal>smallSetElementSetName</literal> are
583 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
584 If PQF is used, however, the PQF query is transferred anyway
585 using non-standard element <literal>pQuery</literal> in
586 SRW SearchRetrieveRequest.
589 Unfortunately, SRW does not define a database setting. Hence,
590 <literal>databaseName</literal> is unsupported and ignored.
591 However, the path part in host parameter for functions
592 <function>ZOOM_connecton_new</function> and
593 <function>ZOOM_connection_connect</function> acts as a
594 database (at least for the &yaz; SRW server).
598 <sect1 id="zoom.records"><title>Records</title>
600 A record object is a retrieval record on the client side -
601 created from result sets.
604 void ZOOM_resultset_records (ZOOM_resultset r,
606 size_t start, size_t count);
607 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
609 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
612 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
614 void ZOOM_record_destroy (ZOOM_record rec);
617 References to temporary records are returned by functions
618 <function>ZOOM_resultset_records</function> or
619 <function>ZOOM_resultset_record</function>.
622 If a persistent reference to a record is desired
623 <function>ZOOM_record_clone</function> should be used.
624 It returns a record reference that should be destroyed
625 by a call to <function>ZOOM_record_destroy</function>.
628 A single record is returned by function
629 <function>ZOOM_resultset_record</function> that takes a
630 position as argument. First record has position zero.
631 If no record could be obtained <literal>NULL</literal> is returned.
634 Function <function>ZOOM_resultset_records</function> retrieves
635 a number of records from a result set. Parameter <literal>start</literal>
636 and <literal>count</literal> specifies the range of records to
637 be returned. Upon completion array
638 <literal>recs[0], ..recs[count-1]</literal>
639 holds record objects for the records. The array of records
640 <literal>recs</literal> should be allocated prior the call
641 <function>ZOOM_resultset_records</function>. Note that for those
642 records that couldn't be retrieved from the target
643 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
645 <para id="zoom.record.get">
646 In order to extract information about a single record,
647 <function>ZOOM_record_get</function> is provided. The
648 function returns a pointer to certain record information. The
649 nature (type) of the pointer depends on the parameter,
650 <parameter>type</parameter>.
653 The <parameter>type</parameter> is a string of the format:
656 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
659 where <replaceable>form</replaceable> specifies the format of the
660 returned record, <replaceable>from</replaceable>
661 specifies the character set of the record in its original form
662 (as returned by the server), <replaceable>to</replaceable> specifies
663 the output (returned)
664 character set encoding.
665 If charset is not given, then no character set conversion takes place.
666 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
669 In addition, for certain types, the length
670 <literal>len</literal> passed will be set to the size in bytes of
671 the returned information.
674 The following are the supported values for <replaceable>form</replaceable>.
676 <varlistentry><term><literal>database</literal></term>
677 <listitem><para>Database of record is returned
678 as a C null-terminated string. Return type
679 <literal>const char *</literal>.
682 <varlistentry><term><literal>syntax</literal></term>
683 <listitem><para>The transfer syntax of the record is returned
684 as a C null-terminated string containing the symbolic name of
685 the record syntax, e.g. <literal>Usmarc</literal>. Return type
687 <literal>const char *</literal>.
690 <varlistentry><term><literal>render</literal></term>
691 <listitem><para>The record is returned in a display friendly
692 format. Upon completion buffer is returned
693 (type <literal>const char *</literal>) and length is stored in
694 <literal>*len</literal>.
697 <varlistentry><term><literal>raw</literal></term>
698 <listitem><para>The record is returned in the internal
699 YAZ specific format. For GRS-1, Explain, and others, the
700 raw data is returned as type
701 <literal>Z_External *</literal> which is just the type for
702 the member <literal>retrievalRecord</literal> in
703 type <literal>NamePlusRecord</literal>.
704 For SUTRS and octet aligned record (including all MARCs) the
705 octet buffer is returned and the length of the buffer.
708 <varlistentry><term><literal>xml</literal></term>
709 <listitem><para>The record is returned in XML if possible.
710 SRW/SRU and Z39.50 records with transfer syntax XML are
711 returned verbatim. MARC records are returned in
712 <ulink url="http://www.loc.gov/standards/marcxml/">
715 (converted from ISO2709 to MARCXML by YAZ).
716 GRS-1 and OPAC records are not supported for this form.
717 Upon completion, the XML buffer is returned
718 (type <literal>const char *</literal>) and length is stored in
719 <literal>*len</literal>.
722 <varlistentry><term><literal>opac</literal></term>
723 <listitem><para>OPAC for record is returned in XML.
730 <ulink url="http://www.loc.gov/marc/">
734 <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
737 character set encoding.
738 An application that wishes to display in Latin-1 would use
740 render; charset=marc8,iso-8859-1
743 <sect2><title>Z39.50 Protocol behavior</title>
745 The functions <function>ZOOM_resultset_record</function> and
746 <function>ZOOM_resultset_records</function> inspects the client-side
747 record cache. Records not found in cache are fetched using
749 The functions may block (and perform network I/O) - even though option
750 <literal>async</literal> is 1, because they return records objects.
751 (and there's no way to return records objects without retrieving them!).
754 There is a trick, however, in the usage of function
755 <function>ZOOM_resultset_records</function> that allows for
756 delayed retrieval (and makes it non-blocking). By using
757 a null pointer for <parameter>recs</parameter> you're indicating
758 you're not interested in getting records objects
759 <emphasis>now</emphasis>.
762 <sect2><title>SRW Protocol behavior</title>
764 The ZOOM driver for SRW treats records returned by a SRW server
765 as if they where Z39.50 records with transfer syntax XML and
766 no element set name or database name.
770 <sect1 id="zoom.scan"><title>Scan</title>
772 This section describes an interface for Scan. Scan is not an
773 official part of the ZOOM model yet. The result of a scan operation
774 is the <literal>ZOOM_scanset</literal> which is a set of terms
775 returned by a target.
779 The Scan interface is Z39.50 only. SRW version 1.0 does not
784 ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
785 const char *startterm);
787 size_t ZOOM_scanset_size(ZOOM_scanset scan);
789 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
790 int *occ, size_t *len);
792 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
793 int *occ, size_t *len);
795 void ZOOM_scanset_destroy (ZOOM_scanset scan);
797 const char *ZOOM_scanset_option_get (ZOOM_scanset scan,
800 void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
804 The scan set is created by function
805 <function>ZOOM_connection_scan</function> which performs a scan
806 operation on the connection using the specified startterm.
807 If the operation was successful, the size of the scan set can be
808 retrieved by a call to <function>ZOOM_scanset_size</function>.
809 Like result sets, the items are numbered 0,..size-1.
810 To obtain information about a particular scan term, call function
811 <function>ZOOM_scanset_term</function>. This function takes
812 a scan set offset <literal>pos</literal> and returns a pointer
813 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
815 If present, the <literal>occ</literal> and <literal>len</literal>
816 are set to the number of occurrences and the length
817 of the actual term respectively.
818 <function>ZOOM_scanset_display_term</function> is similar to
819 <function>ZOOM_scanset_term</function> except that it returns
820 the <emphasis>display term</emphasis> rather than the raw term.
821 In a few cases, the term is different from display term. Always
822 use the display term for display and the raw term for subsequent
823 scan operations (to get more terms, next scan result, etc).
826 A scan set may be freed by a call to function
827 <function>ZOOM_scanset_destroy</function>.
828 Functions <function>ZOOM_scanset_option_get</function> and
829 <function>ZOOM_scanset_option_set</function> retrieves and sets
830 an option respectively.
833 <table frame="top"><title>ZOOM Scan Set Options</title>
835 <colspec colwidth="4*" colname="name"></colspec>
836 <colspec colwidth="7*" colname="description"></colspec>
837 <colspec colwidth="2*" colname="default"></colspec>
840 <entry>Option</entry>
841 <entry>Description</entry>
842 <entry>Default</entry>
847 number</entry><entry>Number of Scan Terms requested in next scan.
848 After scan it holds the actual number of terms returned.
849 </entry><entry>10</entry></row>
851 position</entry><entry>Preferred Position of term in response
852 in next scan; actual position after completion of scan.
853 </entry><entry>1</entry></row>
855 stepSize</entry><entry>Step Size
856 </entry><entry>0</entry></row>
858 scanStatus</entry><entry>An integer indicating the Scan Status
860 </entry><entry>0</entry></row>
866 <sect1 id="zoom.options"><title>Options</title>
868 Most &zoom; objects provide a way to specify options to change behavior.
869 From an implementation point of view a set of options is just like
870 an associative array / hash array, etc.
873 ZOOM_options ZOOM_options_create (void);
875 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
877 void ZOOM_options_destroy (ZOOM_options opt);
880 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
882 void ZOOM_options_set (ZOOM_options opt, const char *name,
886 typedef const char *(*ZOOM_options_callback)
887 (void *handle, const char *name);
889 ZOOM_options_callback
890 ZOOM_options_set_callback (ZOOM_options opt,
891 ZOOM_options_callback c,
895 <sect1 id="zoom.events"><title>Events</title>
897 If you're developing non-blocking applications, you have to deal
901 int ZOOM_event (int no, ZOOM_connection *cs);
904 The <function>ZOOM_event</function> executes pending events for
905 a number of connections. Supply the number of connections in
906 <literal>no</literal> and an array of connections in
907 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
908 A pending event could be a sending a search, receiving a response,
910 When an event has occurred for one of the connections, this function
911 returns a positive integer <literal>n</literal> denoting that an event
912 occurred for connection <literal>cs[n-1]</literal>.
913 When no events are pending for the connections, a value of zero is
915 To ensure that all outstanding requests are performed call this function
916 repeatedly until zero is returned.
919 If <function>ZOOM_event</function> returns and returns non-zero, the
920 last event that occurred can be expected.
923 int ZOOM_connection_last_event(ZOOM_connection cs);
926 <function>ZOOM_connection_last_event</function> returns an event type
927 (integer) for the last event.
930 <table frame="top"><title>ZOOM Event IDs</title>
932 <colspec colwidth="4*" colname="name"></colspec>
933 <colspec colwidth="7*" colname="description"></colspec>
937 <entry>Description</entry>
942 <entry>ZOOM_EVENT_NONE</entry>
943 <entry>No event has occurred</entry>
946 <entry>ZOOM_EVENT_CONNECT</entry>
947 <entry>TCP/IP connect has initiated</entry>
950 <entry>ZOOM_EVENT_SEND_DATA</entry>
951 <entry>Data has been transmitted (sending)</entry>
954 <entry>ZOOM_EVENT_RECV_DATA</entry>
955 <entry>Data has been received)</entry>
958 <entry>ZOOM_EVENT_TIMEOUT</entry>
959 <entry>Timeout</entry>
962 <entry>ZOOM_EVENT_UNKNOWN</entry>
963 <entry>Unknown event</entry>
966 <entry>ZOOM_EVENT_SEND_APDU</entry>
967 <entry>An APDU has been transmitted (sending)</entry>
970 <entry>ZOOM_EVENT_RECV_APDU</entry>
971 <entry>An APDU has been received</entry>
974 <entry>ZOOM_EVENT_RECV_RECORD</entry>
975 <entry>A result-set record has been received</entry>
978 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
979 <entry>A search result been received</entry>
987 <!-- Keep this comment at the end of the file
992 sgml-minimize-attributes:nil
993 sgml-always-quote-attributes:t
996 sgml-parent-document: "yaz.xml"
997 sgml-local-catalogs: nil
998 sgml-namecase-general:t