1 <!-- $Id: zoom.xml,v 1.39 2005-11-01 15:08:01 adam Exp $ -->
2 <chapter id="zoom"><title>ZOOM</title>
4 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
5 an initiative started by Mike Taylor (Mike is from the UK, which
6 explains the peculiar name of the model). The goal of &zoom; is to
7 provide a common Z39.50 client API not bound to a particular
8 programming language or toolkit.
13 A recent addition to &yaz; is SRW support. You can now make
14 SRW ZOOM connections by specifying scheme <literal>http://</literal>
15 for the hostname for a connection.
20 The lack of a simple Z39.50 client API for &yaz; has become more
21 and more apparent over time. So when the first &zoom; specification
23 an implementation for &yaz; was quickly developed. For the first time, it is
24 now as easy (or easier!) to develop clients than servers with &yaz;. This
25 chapter describes the &zoom; C binding. Before going further, please
26 reconsider whether C is the right programming language for the job.
27 There are other language bindings available for &yaz;, and still
29 are in active development. See the
30 <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
35 In order to fully understand this chapter you should read and
36 try the example programs <literal>zoomtst1.c</literal>,
37 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
42 The C language misses features found in object oriented languages
43 such as C++, Java, etc. For example, you'll have to manually,
44 destroy all objects you create, even though you may think of them as
45 temporary. Most objects has a <literal>_create</literal> - and a
46 <literal>_destroy</literal> variant.
47 All objects are in fact pointers to internal stuff, but you don't see
48 that because of typedefs. All destroy methods should gracefully ignore a
49 <literal>NULL</literal> pointer.
52 In each of the sections below you'll find a sub section called
53 protocol behavior, that describes how the API maps to the Z39.50
56 <sect1 id="zoom.connections"><title>Connections</title>
58 <para>The Connection object is a session with a target.
61 #include <yaz/zoom.h>
63 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
65 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
67 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
69 void ZOOM_connection_destroy (ZOOM_connection c);
72 Connection objects are created with either function
73 <function>ZOOM_connection_new</function> or
74 <function>ZOOM_connection_create</function>.
75 The former creates and automatically attempts to establish a network
76 connection with the target. The latter doesn't establish
77 a connection immediately, thus allowing you to specify options
78 before establishing network connection using the function
79 <function>ZOOM_connection_connect</function>.
80 If the port number, <literal>portnum</literal>, is zero, the
81 <literal>host</literal> is consulted for a port specification.
82 If no port is given, 210 is used. A colon denotes the beginning of
83 a port number in the host string. If the host string includes a
84 slash, the following part specifies a database for the connection.
87 You can prefix the host with a scheme followed by colon. The
88 default scheme is <literal>tcp</literal> (Z39.50 protocol).
89 The scheme <literal>http</literal> selects SRW over HTTP.
92 Connection objects should be destroyed using the function
93 <function>ZOOM_connection_destroy</function>.
96 void ZOOM_connection_option_set (ZOOM_connection c,
100 const char *ZOOM_connection_option_get (ZOOM_connection c,
104 The <function>ZOOM_connection_option_set</function> allows you to
105 set an option given by <parameter>key</parameter> to the value
106 <parameter>value</parameter> for the connection.
107 Function <function>ZOOM_connection_option_get</function> returns
108 the value for an option given by <parameter>key</parameter>.
110 <table frame="top"><title>ZOOM Connection Options</title>
112 <colspec colwidth="4*" colname="name"></colspec>
113 <colspec colwidth="7*" colname="description"></colspec>
114 <colspec colwidth="3*" colname="default"></colspec>
117 <entry>Option</entry>
118 <entry>Description</entry>
119 <entry>Default</entry>
124 implementationName</entry><entry>Name of Your client
125 </entry><entry>none</entry></row>
127 user</entry><entry>Authentication user name
128 </entry><entry>none</entry></row>
130 group</entry><entry>Authentication group name
131 </entry><entry>none</entry></row>
133 password</entry><entry>Authentication password.
134 </entry><entry>none</entry></row>
136 host</entry><entry>Target host. This setting is "read-only".
137 It's automatically set internally when connecting to a target.
138 </entry><entry>none</entry></row>
140 proxy</entry><entry>Proxy host
141 </entry><entry>none</entry></row>
143 async</entry><entry>If true (1) the connection operates in
144 asynchronous operation which means that all calls are non-blocking
146 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
147 </entry><entry>0</entry></row>
149 maximumRecordSize</entry><entry> Maximum size of single record.
150 </entry><entry>1 MB</entry></row>
152 preferredMessageSize</entry><entry> Maximum size of multiple records.
153 </entry><entry>1 MB</entry></row>
155 lang</entry><entry> Language for negotiation.
156 </entry><entry>none</entry></row>
158 charset</entry><entry> Character set for negotiation.
159 </entry><entry>none</entry></row>
161 serverImplementationId</entry><entry>
162 Implementation ID of server. (The old targetImplementationId
163 option is also supported for the benefit of old applications.)
164 </entry><entry>none</entry></row>
166 targetImplementationName</entry><entry>
167 Implementation Name of server. (The old
168 targetImplementationName option is also supported for the
169 benefit of old applications.)
170 </entry><entry>none</entry></row>
172 serverImplementationVersion</entry><entry>
173 Implementation Version of server. (the old
174 targetImplementationVersion option is also supported for the
175 benefit of old applications.)
176 </entry><entry>none</entry></row>
178 databaseName</entry><entry>One or more database names
179 separated by character plus (<literal>+</literal>), which to
180 be used by subsequent search requests on this Connection.
181 </entry><entry>Default</entry></row>
183 piggyback</entry><entry>True (1) if piggyback should be
184 used in searches; false (0) if not.
185 </entry><entry>1</entry></row>
187 smallSetUpperBound</entry><entry>If hits is less than or equal to this
188 value, then target will return all records using small element set name
189 </entry><entry>0</entry></row>
191 largeSetLowerBound</entry><entry>If hits is greater than this
192 value, the target will return no records.
193 </entry><entry>1</entry></row>
195 mediumSetPresentNumber</entry><entry>This value represents
196 the number of records to be returned as part of a search when when
197 hits is less than or equal to large set lower bound and if hits
198 is greater than small set upper bound.
199 </entry><entry>0</entry></row>
201 smallSetElementSetName</entry><entry>
202 The element set name to be used for small result sets.
203 </entry><entry>none</entry></row>
205 mediumSetElementSetName</entry><entry>
206 The element set name to be for medium-sized result sets.
207 </entry><entry>none</entry></row>
212 If either option <literal>lang</literal> or <literal>charset</literal>
214 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
215 Character Set and Language Negotiation</ulink> is in effect.
218 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
219 const char **addinfo);
220 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
221 const char **addinfo, const char **dset);
224 Function <function>ZOOM_connection_error</function> checks for
225 errors for the last operation(s) performed. The function returns
226 zero if no errors occurred; non-zero otherwise indicating the error.
227 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
228 holds messages for the error and additional-info if passed as
229 non-<literal>NULL</literal>. Function
230 <function>ZOOM_connection_error_x</function> is an extended version
231 of <function>ZOOM_connection_error</function> that is capable of
232 returning name of diagnostic set in <parameter>dset</parameter>.
234 <sect2><title>Z39.50 Protocol behavior</title>
236 The calls <function>ZOOM_connection_new</function> and
237 <function>ZOOM_connection_connect</function> establishes a TCP/IP
238 connection and sends an Initialize Request to the target if
239 possible. In addition, the calls waits for an Initialize Response
240 from the target and the result is inspected (OK or rejected).
243 If <literal>proxy</literal> is set then the client will establish
244 a TCP/IP connection with the peer as specified by the
245 <literal>proxy</literal> host and the hostname as part of the
246 connect calls will be set as part of the Initialize Request.
247 The proxy server will then "forward" the PDU's transparently
248 to the target behind the proxy.
251 For the authentication parameters, if option <literal>user</literal>
252 is set and both options <literal>group</literal> and
253 <literal>pass</literal> are unset, then Open style
254 authentication is used (Version 2/3) in which case the username
255 is usually followed by a slash, then by a password.
256 If either <literal>group</literal>
257 or <literal>pass</literal> is set then idPass authentication
258 (Version 3 only) is used. If none of the options are set, no
259 authentication parameters are set as part of the Initialize Request
263 When option <literal>async</literal> is 1, it really means that
264 all network operations are postponed (and queued) until the
265 function <literal>ZOOM_event</literal> is invoked. When doing so
266 it doesn't make sense to check for errors after
267 <literal>ZOOM_connection_new</literal> is called since that
268 operation "connecting - and init" is still incomplete and the
269 API cannot tell the outcome (yet).
272 <sect2><title>SRW Protocol behavior</title>
274 The SRW protocol doesn't feature an Inititialize Request, so
275 the connection phase merely establishes a TCP/IP connection
276 with the SOAP service.
278 <para>Most of the ZOOM connection options do not
279 affect SRW and they are ignored. However, future versions
280 of &yaz; might honor <literal>implementationName</literal> and
281 put that as part of User-Agent header for HTTP requests.
284 The <literal>charset</literal> is used in the Content-Type header
289 <sect1 id="zoom.query"><title>Queries</title>
291 Query objects represents queries.
294 ZOOM_query ZOOM_query_create(void);
296 void ZOOM_query_destroy(ZOOM_query q);
298 int ZOOM_query_prefix(ZOOM_query q, const char *str);
300 int ZOOM_query_cql(ZOOM_query s, const char *str);
302 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
305 Create query objects using <function>ZOOM_query_create</function>
306 and destroy them by calling <function>ZOOM_query_destroy</function>.
307 RPN-queries can be specified in <link linkend="PQF">PQF</link>
308 notation by using the
309 function <function>ZOOM_query_prefix</function>.
310 The <function>ZOOM_query_cql</function> specifies a CQL
311 query to be sent to the server/target.
312 More query types will be added in future versions of &yaz;, such as
313 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
314 etc. In addition to a search, a sort criteria may be set. Function
315 <function>ZOOM_query_sortby</function> specifies a
316 sort criteria using the same string notation for sort as offered by
317 the <link linkend="sortspec">YAZ client</link>.
319 <sect2><title>Protocol behavior</title>
321 The query object is just an interface for the member Query
322 in the SearchRequest. The sortby-function is an interface to the
323 sortSequence member of the SortRequest.
327 <sect1 id="zoom.resultsets"><title>Result sets</title>
329 The result set object is a container for records returned from
333 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
336 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
339 void ZOOM_resultset_destroy(ZOOM_resultset r);
342 Function <function>ZOOM_connection_search</function> creates
343 a result set given a connection and query.
344 Destroy a result set by calling
345 <function>ZOOM_resultset_destroy</function>.
346 Simple clients may using PQF only may use function
347 <function>ZOOM_connection_search_pqf</function> in which case
348 creating query objects is not necessary.
351 void ZOOM_resultset_option_set (ZOOM_resultset r,
355 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
358 size_t ZOOM_resultset_size (ZOOM_resultset r);
361 Functions <function>ZOOM_resultset_options_set</function> and
362 <function>ZOOM_resultset_get</function> sets and gets an option
363 for a result set similar to <function>ZOOM_connection_option_get</function>
364 and <function>ZOOM_connection_option_set</function>.
367 The number of hits also called result-count is returned by
368 function <function>ZOOM_resultset_size</function>.
370 <table frame="top"><title>ZOOM Result set Options</title>
372 <colspec colwidth="4*" colname="name"></colspec>
373 <colspec colwidth="7*" colname="description"></colspec>
374 <colspec colwidth="2*" colname="default"></colspec>
377 <entry>Option</entry>
378 <entry>Description</entry>
379 <entry>Default</entry>
384 start</entry><entry>Offset of first record to be
385 retrieved from target. First record has offset 0 unlike the
386 protocol specifications where first record has position 1.
387 </entry><entry>0</entry></row>
389 count</entry><entry>Number of records to be retrieved.
390 </entry><entry>0</entry></row>
392 presentChunk</entry><entry>The number of records to be
393 requested from the server in each chunk (present requst). The
394 value 0 means to request all the records in a single chunk.
395 (The old <literal>step</literal>
396 option is also supported for the benefit of old applications.)
397 </entry><entry>0</entry></row>
399 elementSetName</entry><entry>Element-Set name of records.
400 Most targets should honor element set name <literal>B</literal>
401 and <literal>F</literal> for brief and full respectively.
402 </entry><entry>none</entry></row>
404 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
405 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
406 </entry><entry>none</entry></row>
408 schema</entry><entry>Schema for retrieval, such as
409 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
410 </entry><entry>none</entry></row>
412 setname</entry><entry>Name of Result Set (Result Set ID).
413 If this option isn't set, the ZOOM module will automatically
414 allocate a result set name.
415 </entry><entry>default</entry></row>
420 For servers that support Search Info report, the following
421 options may be read using <function>ZOOM_resultset_get</function>.
422 This detailed information is read after a successful search has
426 This information is a list of of items, where each item is
427 information about a term or subquery. All items in the list
429 <literal>SearchResult.</literal><replaceable>no</replaceable>
430 where no presents the item number (0=first, 1=second).
431 Read <literal>SearchResult.size</literal> to determine the
434 <table frame="top"><title>Search Info Report options</title>
436 <colspec colwidth="4*" colname="name"></colspec>
437 <colspec colwidth="7*" colname="description"></colspec>
440 <entry>Option</entry>
441 <entry>Description</entry>
446 <entry>SearchResult.size</entry>
448 number of search result entries. This option is-nonexistant
449 if no entries are returned by the server.
453 <entry>SearchResult.<replaceable>no</replaceable>.subqueryId</entry>
454 <entry>sub query ID</entry>
457 <entry>SearchResult.<replaceable>no</replaceable>.subqueryCount</entry>
458 <entry>result count for item (number of hits)</entry>
461 <entry>SearchResult.<replaceable>no</replaceable>.subquery.term</entry>
462 <entry>subquery term</entry>
466 SearchResult.<replaceable>no</replaceable>.interpretation.term
468 <entry>interpretation term</entry>
472 SearchResult.<replaceable>no</replaceable>.recommendation.term
474 <entry>recommendation term</entry>
480 <title>Z39.50 Protocol behavior</title>
482 The creation of a result set involves at least a SearchRequest
483 - SearchResponse protocol handshake. Following that, if a sort
484 criteria was specified as part of the query, a SortRequest -
485 SortResponse handshake takes place. Note that it is necessary to
486 perform sorting before any retrieval takes place, so no records will
487 be returned from the target as part of the SearchResponse because these
488 would be unsorted. Hence, piggyback is disabled when sort criteria
489 are set. Following Search - and a possible sort - Retrieval takes
490 place - as one or more Present Requests/Response pairs being
494 The API allows for two different modes for retrieval. A high level
495 mode which is somewhat more powerful and a low level one.
496 The low level is enabled when searching on a Connection object
497 for which the settings
498 <literal>smallSetUpperBound</literal>,
499 <literal>mediumSetPresentNumber</literal> and
500 <literal>largeSetLowerBound</literal> are set. The low level mode
501 thus allows you to precisely set how records are returned as part
502 of a search response as offered by the Z39.50 protocol.
503 Since the client may be retrieving records as part of the
504 search response, this mode doesn't work well if sorting is used.
507 The high-level mode allows you to fetch a range of records from
508 the result set with a given start offset. When you use this mode
509 the client will automatically use piggyback if that is possible
510 with the target and perform one or more present requests as needed.
511 Even if the target returns fewer records as part of a present response
512 because of a record size limit, etc. the client will repeat sending
513 present requests. As an example, if option <literal>start</literal>
514 is 0 (default) and <literal>count</literal> is 4, and
515 <literal>piggyback</literal> is 1 (default) and no sorting criteria
516 is specified, then the client will attempt to retrieve the 4
517 records as part the search response (using piggyback). On the other
518 hand, if either <literal>start</literal> is positive or if
519 a sorting criteria is set, or if <literal>piggyback</literal>
520 is 0, then the client will not perform piggyback but send Present
524 If either of the options <literal>mediumSetElementSetName</literal> and
525 <literal>smallSetElementSetName</literal> are unset, the value
526 of option <literal>elementSetName</literal> is used for piggyback
527 searches. This means that for the high-level mode you only have
528 to specify one elementSetName option rather than three.
532 <title>SRW Protocol behavior</title>
534 Current version of &yaz; does not take advantage of a result set id
535 returned by the SRW server. Future versions might do, however.
536 Since, the ZOOM driver does not save result set IDs any
537 present (retrieval) is transformed to a SRW SearchRetrieveRequest
538 with same query but, possibly, different offsets.
541 Option <literal>schema</literal> specifies SRW schema
542 for retrieval. However, options <literal>elementSetName</literal> and
543 <literal>preferredRecordSyntax</literal> are ignored.
546 Options <literal>start</literal> and <literal>count</literal>
547 are supported by SRW.
548 The remaining options
549 <literal>piggyback</literal>,
550 <literal>smallSetUpperBound</literal>,
551 <literal>largeSetLowerBound</literal>,
552 <literal>mediumSetPresentNumber</literal>,
553 <literal>mediumSetElementSetName</literal>,
554 <literal>smallSetElementSetName</literal> are
558 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
559 If PQF is used, however, the PQF query is transferred anyway
560 using non-standard element <literal>pQuery</literal> in
561 SRW SearchRetrieveRequest.
564 Unfortunately, SRW does not define a database setting. Hence,
565 <literal>databaseName</literal> is unsupported and ignored.
566 However, the path part in host parameter for functions
567 <function>ZOOM_connecton_new</function> and
568 <function>ZOOM_connection_connect</function> acts as a
569 database (at least for the &yaz; SRW server).
573 <sect1 id="zoom.records"><title>Records</title>
575 A record object is a retrieval record on the client side -
576 created from result sets.
579 void ZOOM_resultset_records (ZOOM_resultset r,
581 size_t start, size_t count);
582 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
584 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
587 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
589 void ZOOM_record_destroy (ZOOM_record rec);
592 References to temporary records are returned by functions
593 <function>ZOOM_resultset_records</function> or
594 <function>ZOOM_resultset_record</function>.
597 If a persistent reference to a record is desired
598 <function>ZOOM_record_clone</function> should be used.
599 It returns a record reference that should be destroyed
600 by a call to <function>ZOOM_record_destroy</function>.
603 A single record is returned by function
604 <function>ZOOM_resultset_record</function> that takes a
605 position as argument. First record has position zero.
606 If no record could be obtained <literal>NULL</literal> is returned.
609 Function <function>ZOOM_resultset_records</function> retrieves
610 a number of records from a result set. Parameter <literal>start</literal>
611 and <literal>count</literal> specifies the range of records to
612 be returned. Upon completion array
613 <literal>recs[0], ..recs[count-1]</literal>
614 holds record objects for the records. The array of records
615 <literal>recs</literal> should be allocated prior the call
616 <function>ZOOM_resultset_records</function>. Note that for those
617 records that couldn't be retrieved from the target
618 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
620 <para id="zoom.record.get">
621 In order to extract information about a single record,
622 <function>ZOOM_record_get</function> is provided. The
623 function returns a pointer to certain record information. The
624 nature (type) of the pointer depends on the parameter,
625 <parameter>type</parameter>.
628 The <parameter>type</parameter> is a string of the format:
631 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
634 where <replaceable>form</replaceable> specifies the format of the
635 returned record, <replaceable>from</replaceable>
636 specifies the character set of the record in its original form
637 (as returned by the server), <replaceable>to</replaceable> specifies
638 the output (returned)
639 character set encoding.
640 If charset is not given, then no character set conversion takes place.
641 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
644 In addition, for certain types, the length
645 <literal>len</literal> passed will be set to the size in bytes of
646 the returned information.
649 The following are the supported values for <replaceable>form</replaceable>.
651 <varlistentry><term><literal>database</literal></term>
652 <listitem><para>Database of record is returned
653 as a C null-terminated string. Return type
654 <literal>const char *</literal>.
657 <varlistentry><term><literal>syntax</literal></term>
658 <listitem><para>The transfer syntax of the record is returned
659 as a C null-terminated string containing the symbolic name of
660 the record syntax, e.g. <literal>Usmarc</literal>. Return type
662 <literal>const char *</literal>.
665 <varlistentry><term><literal>render</literal></term>
666 <listitem><para>The record is returned in a display friendly
667 format. Upon completion buffer is returned
668 (type <literal>const char *</literal>) and length is stored in
669 <literal>*len</literal>.
672 <varlistentry><term><literal>raw</literal></term>
673 <listitem><para>The record is returned in the internal
674 YAZ specific format. For GRS-1, Explain, and others, the
675 raw data is returned as type
676 <literal>Z_External *</literal> which is just the type for
677 the member <literal>retrievalRecord</literal> in
678 type <literal>NamePlusRecord</literal>.
679 For SUTRS and octet aligned record (including all MARCs) the
680 octet buffer is returned and the length of the buffer.
683 <varlistentry><term><literal>xml</literal></term>
684 <listitem><para>The record is returned in XML if possible.
685 SRW/SRU and Z39.50 records with transfer syntax XML are
686 returned verbatim. MARC records are returned in
687 <ulink url="http://www.loc.gov/standards/marcxml/">
690 (converted from ISO2709 to MARCXML by YAZ).
691 GRS-1 and OPAC records are not supported for this form.
692 Upon completion, the XML buffer is returned
693 (type <literal>const char *</literal>) and length is stored in
694 <literal>*len</literal>.
697 <varlistentry><term><literal>opac</literal></term>
698 <listitem><para>OPAC for record is returned in XML.
705 <ulink url="http://www.loc.gov/marc/">
709 <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
712 character set encoding.
713 An application that wishes to display in Latin-1 would use
715 render; charset=marc8,iso-8859-1
718 <sect2><title>Z39.50 Protocol behavior</title>
720 The functions <function>ZOOM_resultset_record</function> and
721 <function>ZOOM_resultset_records</function> inspects the client-side
722 record cache. Records not found in cache are fetched using
724 The functions may block (and perform network I/O) - even though option
725 <literal>async</literal> is 1, because they return records objects.
726 (and there's no way to return records objects without retrieving them!).
729 There is a trick, however, in the usage of function
730 <function>ZOOM_resultset_records</function> that allows for
731 delayed retrieval (and makes it non-blocking). By using
732 a null pointer for <parameter>recs</parameter> you're indicating
733 you're not interested in getting records objects
734 <emphasis>now</emphasis>.
737 <sect2><title>SRW Protocol behavior</title>
739 The ZOOM driver for SRW treats records returned by a SRW server
740 as if they where Z39.50 records with transfer syntax XML and
741 no element set name or database name.
745 <sect1 id="zoom.scan"><title>Scan</title>
747 This section describes an interface for Scan. Scan is not an
748 official part of the ZOOM model yet. The result of a scan operation
749 is the <literal>ZOOM_scanset</literal> which is a set of terms
750 returned by a target.
754 The Scan interface is Z39.50 only. SRW version 1.0 does not
759 ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
760 const char *startterm);
762 size_t ZOOM_scanset_size(ZOOM_scanset scan);
764 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
765 int *occ, size_t *len);
767 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
768 int *occ, size_t *len);
770 void ZOOM_scanset_destroy (ZOOM_scanset scan);
772 const char *ZOOM_scanset_option_get (ZOOM_scanset scan,
775 void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
779 The scan set is created by function
780 <function>ZOOM_connection_scan</function> which performs a scan
781 operation on the connection using the specified startterm.
782 If the operation was successful, the size of the scan set can be
783 retrieved by a call to <function>ZOOM_scanset_size</function>.
784 Like result sets, the items are numbered 0,..size-1.
785 To obtain information about a particular scan term, call function
786 <function>ZOOM_scanset_term</function>. This function takes
787 a scan set offset <literal>pos</literal> and returns a pointer
788 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
790 If present, the <literal>occ</literal> and <literal>len</literal>
791 are set to the number of occurrences and the length
792 of the actual term respectively.
793 <function>ZOOM_scanset_display_term</function> is similar to
794 <function>ZOOM_scanset_term</function> except that it returns
795 the <emphasis>display term</emphasis> rather than the raw term.
796 In a few cases, the term is different from display term. Always
797 use the display term for display and the raw term for subsequent
798 scan operations (to get more terms, next scan result, etc).
801 A scan set may be freed by a call to function
802 <function>ZOOM_scanset_destroy</function>.
803 Functions <function>ZOOM_scanset_option_get</function> and
804 <function>ZOOM_scanset_option_set</function> retrieves and sets
805 an option respectively.
808 <table frame="top"><title>ZOOM Scan Set Options</title>
810 <colspec colwidth="4*" colname="name"></colspec>
811 <colspec colwidth="7*" colname="description"></colspec>
812 <colspec colwidth="2*" colname="default"></colspec>
815 <entry>Option</entry>
816 <entry>Description</entry>
817 <entry>Default</entry>
822 number</entry><entry>Number of Scan Terms requested in next scan.
823 After scan it holds the actual number of terms returned.
824 </entry><entry>10</entry></row>
826 position</entry><entry>Preferred Position of term in response
827 in next scan; actual position after completion of scan.
828 </entry><entry>1</entry></row>
830 stepSize</entry><entry>Step Size
831 </entry><entry>0</entry></row>
833 scanStatus</entry><entry>An integer indicating the Scan Status
835 </entry><entry>0</entry></row>
841 <sect1 id="zoom.options"><title>Options</title>
843 Most &zoom; objects provide a way to specify options to change behavior.
844 From an implementation point of view a set of options is just like
845 an associative array / hash array, etc.
848 ZOOM_options ZOOM_options_create (void);
850 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
852 void ZOOM_options_destroy (ZOOM_options opt);
855 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
857 void ZOOM_options_set (ZOOM_options opt, const char *name,
861 typedef const char *(*ZOOM_options_callback)
862 (void *handle, const char *name);
864 ZOOM_options_callback
865 ZOOM_options_set_callback (ZOOM_options opt,
866 ZOOM_options_callback c,
870 <sect1 id="zoom.events"><title>Events</title>
872 If you're developing non-blocking applications, you have to deal
876 int ZOOM_event (int no, ZOOM_connection *cs);
879 The <function>ZOOM_event</function> executes pending events for
880 a number of connections. Supply the number of connections in
881 <literal>no</literal> and an array of connections in
882 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
883 A pending event could be a sending a search, receiving a response,
885 When an event has occurred for one of the connections, this function
886 returns a positive integer <literal>n</literal> denoting that an event
887 occurred for connection <literal>cs[n-1]</literal>.
888 When no events are pending for the connections, a value of zero is
890 To ensure that all outstanding requests are performed call this function
891 repeatedly until zero is returned.
894 If <function>ZOOM_event</function> returns and returns non-zero, the
895 last event that occurred can be expected.
898 int ZOOM_connection_last_event(ZOOM_connection cs);
901 <function>ZOOM_connection_last_event</function> returns an event type
902 (integer) for the last event.
905 <table frame="top"><title>ZOOM Event IDs</title>
907 <colspec colwidth="4*" colname="name"></colspec>
908 <colspec colwidth="7*" colname="description"></colspec>
912 <entry>Description</entry>
917 <entry>ZOOM_EVENT_NONE</entry>
918 <entry>No event has occurred</entry>
921 <entry>ZOOM_EVENT_CONNECT</entry>
922 <entry>TCP/IP connect has initiated</entry>
925 <entry>ZOOM_EVENT_SEND_DATA</entry>
926 <entry>Data has been transmitted (sending)</entry>
929 <entry>ZOOM_EVENT_RECV_DATA</entry>
930 <entry>Data has been received)</entry>
933 <entry>ZOOM_EVENT_TIMEOUT</entry>
934 <entry>Timeout</entry>
937 <entry>ZOOM_EVENT_UNKNOWN</entry>
938 <entry>Unknown event</entry>
941 <entry>ZOOM_EVENT_SEND_APDU</entry>
942 <entry>An APDU has been transmitted (sending)</entry>
945 <entry>ZOOM_EVENT_RECV_APDU</entry>
946 <entry>An APDU has been received</entry>
949 <entry>ZOOM_EVENT_RECV_RECORD</entry>
950 <entry>A result-set record has been received</entry>
953 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
954 <entry>A search result been received</entry>
962 <!-- Keep this comment at the end of the file
967 sgml-minimize-attributes:nil
968 sgml-always-quote-attributes:t
971 sgml-parent-document: "yaz.xml"
972 sgml-local-catalogs: nil
973 sgml-namecase-general:t