1 <!-- $Id: zoom.xml,v 1.33 2003-11-17 15:00:41 mike 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 pass</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 targetImplementationId</entry><entry> Implementation ID of target.
162 </entry><entry>none</entry></row>
164 targetImplementationName</entry><entry> Implementation Name of target.
165 </entry><entry>none</entry></row>
167 targetImplementationVersion</entry><entry> Implementation Version
169 </entry><entry>none</entry></row>
171 databaseName</entry><entry>One or more database names
172 separated by character plus (<literal>+</literal>), which to
173 be used by subsequent search requests on this Connection.
174 </entry><entry>Default</entry></row>
176 piggyback</entry><entry>True (1) if piggyback should be
177 used in searches; false (0) if not.
178 </entry><entry>1</entry></row>
180 smallSetUpperBound</entry><entry>If hits is less than or equal to this
181 value, then target will return all records using small element set name
182 </entry><entry>0</entry></row>
184 largeSetLowerBound</entry><entry>If hits is greater than this
185 value, the target will return no records.
186 </entry><entry>1</entry></row>
188 mediumSetPresentNumber</entry><entry>This value represents
189 the number of records to be returned as part of a search when when
190 hits is less than or equal to large set lower bound and if hits
191 is greater than small set upper bound.
192 </entry><entry>0</entry></row>
194 smallSetElementSetName</entry><entry>
195 The element set name to be used for small result sets.
196 </entry><entry>none</entry></row>
198 mediumSetElementSetName</entry><entry>
199 The element set name to be for medium-sized result sets.
200 </entry><entry>none</entry></row>
205 If either option <literal>lang</literal> or <literal>charset</literal>
207 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
208 Character Set and Language Negotiation</ulink> is in effect.
211 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
212 const char **addinfo);
213 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
214 const char **addinfo, const char **dset);
217 Function <function>ZOOM_connection_error</function> checks for
218 errors for the last operation(s) performed. The function returns
219 zero if no errors occurred; non-zero otherwise indicating the error.
220 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
221 holds messages for the error and additional-info if passed as
222 non-<literal>NULL</literal>. Function
223 <function>ZOOM_connection_error_x</function> is an extended version
224 of <function>ZOOM_connection_error</function> that is capable of
225 returning name of diagnostic set in <parameter>dset</parameter>.
227 <sect2><title>Z39.50 Protocol behavior</title>
229 The calls <function>ZOOM_connection_new</function> and
230 <function>ZOOM_connection_connect</function> establishes a TCP/IP
231 connection and sends an Initialize Request to the target if
232 possible. In addition, the calls waits for an Initialize Response
233 from the target and the result is inspected (OK or rejected).
236 If <literal>proxy</literal> is set then the client will establish
237 a TCP/IP connection with the peer as specified by the
238 <literal>proxy</literal> host and the hostname as part of the
239 connect calls will be set as part of the Initialize Request.
240 The proxy server will then "forward" the PDU's transparently
241 to the target behind the proxy.
244 For the authentication parameters, if option <literal>user</literal>
245 is set and both options <literal>group</literal> and
246 <literal>pass</literal> are unset, then Open style
247 authentication is used (Version 2/3) in which case the username
248 is usually followed by a slash, then by a password.
249 If either <literal>group</literal>
250 or <literal>pass</literal> is set then idPass authentication
251 (Version 3 only) is used. If none of the options are set, no
252 authentication parameters are set as part of the Initialize Request
256 When option <literal>async</literal> is 1, it really means that
257 all network operations are postponed (and queued) until the
258 function <literal>ZOOM_event</literal> is invoked. When doing so
259 it doesn't make sense to check for errors after
260 <literal>ZOOM_connection_new</literal> is called since that
261 operation "connecting - and init" is still incomplete and the
262 API cannot tell the outcome (yet).
265 <sect2><title>SRW Protocol behavior</title>
267 The SRW protocol doesn't feature an Inititialize Request, so
268 the connection phase merely establishes a TCP/IP connection
269 with the SOAP service.
271 <para>Most of the ZOOM connection options do not
272 affect SRW and they are ignored. However, future versions
273 of &yaz; might honor <literal>implementationName</literal> and
274 put that as part of User-Agent header for HTTP requests.
277 The <literal>charset</literal> is used in the Content-Type header
282 <sect1 id="zoom.query"><title>Queries</title>
284 Query objects represents queries.
287 ZOOM_query ZOOM_query_create(void);
289 void ZOOM_query_destroy(ZOOM_query q);
291 int ZOOM_query_prefix(ZOOM_query q, const char *str);
293 int ZOOM_query_cql(ZOOM_query s, const char *str);
295 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
298 Create query objects using <function>ZOOM_query_create</function>
299 and destroy them by calling <function>ZOOM_query_destroy</function>.
300 RPN-queries can be specified in <link linkend="PQF">PQF</link>
301 notation by using the
302 function <function>ZOOM_query_prefix</function>.
303 The <function>ZOOM_query_cql</function> specifies a CQL
304 query to be sent to the server/target.
305 More query types will be added in future versions of &yaz;, such as
306 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
307 etc. In addition to a search, a sort criteria may be set. Function
308 <function>ZOOM_query_sortby</function> specifies a
309 sort criteria using the same string notation for sort as offered by
310 the <link linkend="sortspec">YAZ client</link>.
312 <sect2><title>Protocol behavior</title>
314 The query object is just an interface for the member Query
315 in the SearchRequest. The sortby-function is an interface to the
316 sortSequence member of the SortRequest.
320 <sect1 id="zoom.resultsets"><title>Result sets</title>
322 The result set object is a container for records returned from
326 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
329 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
332 void ZOOM_resultset_destroy(ZOOM_resultset r);
335 Function <function>ZOOM_connection_search</function> creates
336 a result set given a connection and query.
337 Destroy a result set by calling
338 <function>ZOOM_resultset_destroy</function>.
339 Simple clients may using PQF only may use function
340 <function>ZOOM_connection_search_pqf</function> in which case
341 creating query objects is not necessary.
344 void ZOOM_resultset_option_set (ZOOM_resultset r,
348 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
351 size_t ZOOM_resultset_size (ZOOM_resultset r);
354 Functions <function>ZOOM_resultset_options_set</function> and
355 <function>ZOOM_resultset_get</function> sets and gets an option
356 for a result set similar to <function>ZOOM_connection_option_get</function>
357 and <function>ZOOM_connection_option_set</function>.
360 The number of hits also called result-count is returned by
361 function <function>ZOOM_resultset_size</function>.
363 <table frame="top"><title>ZOOM Result set Options</title>
365 <colspec colwidth="4*" colname="name"></colspec>
366 <colspec colwidth="7*" colname="description"></colspec>
367 <colspec colwidth="2*" colname="default"></colspec>
370 <entry>Option</entry>
371 <entry>Description</entry>
372 <entry>Default</entry>
377 start</entry><entry>Offset of first record to be
378 retrieved from target. First record has offset 0 unlike the
379 protocol specifications where first record has position 1.
380 </entry><entry>0</entry></row>
382 count</entry><entry>Number of records to be retrieved.
383 </entry><entry>0</entry></row>
385 step</entry><entry>Number of records to be retrieved in
386 one chunk. The value, 0 means unchunked.
387 </entry><entry>0</entry></row>
389 elementSetName</entry><entry>Element-Set name of records.
390 Most targets should honor element set name <literal>B</literal>
391 and <literal>F</literal> for brief and full respectively.
392 </entry><entry>none</entry></row>
394 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
395 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
396 </entry><entry>none</entry></row>
398 schema</entry><entry>Schema for retrieval, such as
399 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
400 </entry><entry>none</entry></row>
402 setname</entry><entry>Name of Result Set (Result Set ID).
403 If this option isn't set, the ZOOM module will automatically
404 allocate a result set name.
405 </entry><entry>default</entry></row>
410 <title>Z39.50 Protocol behavior</title>
412 The creation of a result set involves at least a SearchRequest
413 - SearchResponse protocol handshake. Following that, if a sort
414 criteria was specified as part of the query, a SortRequest -
415 SortResponse handshake takes place. Note that it is necessary to
416 perform sorting before any retrieval takes place, so no records will
417 be returned from the target as part of the SearchResponse because these
418 would be unsorted. Hence, piggyback is disabled when sort criteria
419 are set. Following Search - and a possible sort - Retrieval takes
420 place - as one or more Present Requests/Response pairs being
424 The API allows for two different modes for retrieval. A high level
425 mode which is somewhat more powerful and a low level one.
426 The low level is enabled when searching on a Connection object
427 for which the settings
428 <literal>smallSetUpperBound</literal>,
429 <literal>mediumSetPresentNumber</literal> and
430 <literal>largeSetLowerBound</literal> are set. The low level mode
431 thus allows you to precisely set how records are returned as part
432 of a search response as offered by the Z39.50 protocol.
433 Since the client may be retrieving records as part of the
434 search response, this mode doesn't work well if sorting is used.
437 The high-level mode allows you to fetch a range of records from
438 the result set with a given start offset. When you use this mode
439 the client will automatically use piggyback if that is possible
440 with the target and perform one or more present requests as needed.
441 Even if the target returns fewer records as part of a present response
442 because of a record size limit, etc. the client will repeat sending
443 present requests. As an example, if option <literal>start</literal>
444 is 0 (default) and <literal>count</literal> is 4, and
445 <literal>piggyback</literal> is 1 (default) and no sorting criteria
446 is specified, then the client will attempt to retrieve the 4
447 records as part the search response (using piggyback). On the other
448 hand, if either <literal>start</literal> is positive or if
449 a sorting criteria is set, or if <literal>piggyback</literal>
450 is 0, then the client will not perform piggyback but send Present
454 If either of the options <literal>mediumSetElementSetName</literal> and
455 <literal>smallSetElementSetName</literal> are unset, the value
456 of option <literal>elementSetName</literal> is used for piggyback
457 searches. This means that for the high-level mode you only have
458 to specify one elementSetName option rather than three.
462 <title>SRW Protocol behavior</title>
464 Current version of &yaz; does not take advantage of a result set id
465 returned by the SRW server. Future versions might do, however.
466 Since, the ZOOM driver does not save result set IDs any
467 present (retrieval) is transformed to a SRW SearchRetrieveRequest
468 with same query but, possibly, different offsets.
471 Option <literal>schema</literal> specifies SRW schema
472 for retrieval. However, options <literal>elementSetName</literal> and
473 <literal>preferredRecordSyntax</literal> are ignored.
476 Options <literal>start</literal> and <literal>count</literal>
477 are supported by SRW.
478 The remaining options
479 <literal>piggyback</literal>,
480 <literal>smallSetUpperBound</literal>,
481 <literal>largeSetLowerBound</literal>,
482 <literal>mediumSetPresentNumber</literal>,
483 <literal>mediumSetElementSetName</literal>,
484 <literal>smallSetElementSetName</literal> are
488 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
489 If PQF is used, however, the PQF query is transferred anyway
490 using non-standard element <literal>pQuery</literal> in
491 SRW SearchRetrieveRequest.
494 Unfortunately, SRW does not define a database setting. Hence,
495 <literal>databaseName</literal> is unsupported and ignored.
496 However, the path part in host parameter for functions
497 <function>ZOOM_connecton_new</function> and
498 <function>ZOOM_connection_connect</function> acts as a
499 database (at least for the &yaz; SRW server).
503 <sect1 id="zoom.records"><title>Records</title>
505 A record object is a retrieval record on the client side -
506 created from result sets.
509 void ZOOM_resultset_records (ZOOM_resultset r,
511 size_t start, size_t count);
512 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
514 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
517 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
519 void ZOOM_record_destroy (ZOOM_record rec);
522 References to temporary records are returned by functions
523 <function>ZOOM_resultset_records</function> or
524 <function>ZOOM_resultset_record</function>.
527 If a persistent reference to a record is desired
528 <function>ZOOM_record_clone</function> should be used.
529 It returns a record reference that should be destroyed
530 by a call to <function>ZOOM_record_destroy</function>.
533 A single record is returned by function
534 <function>ZOOM_resultset_record</function> that takes a
535 position as argument. First record has position zero.
536 If no record could be obtained <literal>NULL</literal> is returned.
539 Function <function>ZOOM_resultset_records</function> retrieves
540 a number of records from a result set. Parameter <literal>start</literal>
541 and <literal>count</literal> specifies the range of records to
542 be returned. Upon completion array
543 <literal>recs[0], ..recs[count-1]</literal>
544 holds record objects for the records. The array of records
545 <literal>recs</literal> should be allocated prior the call
546 <function>ZOOM_resultset_records</function>. Note that for those
547 records that couldn't be retrieved from the target
548 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
550 <para id="zoom.record.get">
551 In order to extract information about a single record,
552 <function>ZOOM_record_get</function> is provided. The
553 function returns a pointer to certain record information. The
554 nature (type) of the pointer depends on the parameter,
555 <parameter>type</parameter>.
558 The <parameter>type</parameter> is a string of the format:
561 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
564 where <replaceable>form</replaceable> specifies the format of the
565 returned record, <replaceable>from</replaceable>
566 specifies the character set of the record in its original form
567 (as returned by the server), <replaceable>to</replaceable> specifies
568 the output (returned)
569 character set encoding.
570 If charset is not given, then no character set conversion takes place.
571 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
574 In addition, for certain types, the length
575 <literal>len</literal> passed will be set to the size in bytes of
576 the returned information.
579 The following are the supported values for <replaceable>form</replaceable>.
581 <varlistentry><term><literal>database</literal></term>
582 <listitem><para>Database of record is returned
583 as a C null-terminated string. Return type
584 <literal>const char *</literal>.
587 <varlistentry><term><literal>syntax</literal></term>
588 <listitem><para>The transfer syntax of the record is returned
589 as a C null-terminated string containing the symbolic name of
590 the record syntax, e.g. <literal>Usmarc</literal>. Return type
592 <literal>const char *</literal>.
595 <varlistentry><term><literal>render</literal></term>
596 <listitem><para>The record is returned in a display friendly
597 format. Upon completion buffer is returned
598 (type <literal>const char *</literal>) and length is stored in
599 <literal>*len</literal>.
602 <varlistentry><term><literal>raw</literal></term>
603 <listitem><para>The record is returned in the internal
604 YAZ specific format. For GRS-1, Explain, and others, the
605 raw data is returned as type
606 <literal>Z_External *</literal> which is just the type for
607 the member <literal>retrievalRecord</literal> in
608 type <literal>NamePlusRecord</literal>.
609 For SUTRS and octet aligned record (including all MARCs) the
610 octet buffer is returned and the length of the buffer.
613 <varlistentry><term><literal>xml</literal></term>
614 <listitem><para>The record is returned in XML if possible.
615 SRW/SRU and Z39.50 records with transfer syntax XML are
616 returned verbatim. MARC records are returned in
617 <ulink url="http://www.loc.gov/standards/marcxml/">
620 (converted from ISO2709 to MARCXML by YAZ).
621 GRS-1 and OPAC records are not supported for this form.
622 Upon completion, the XML buffer is returned
623 (type <literal>const char *</literal>) and length is stored in
624 <literal>*len</literal>.
627 <varlistentry><term><literal>opac</literal></term>
628 <listitem><para>OPAC for record is returned in XML.
635 <ulink url="http://www.loc.gov/marc/">
639 <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
642 character set encoding.
643 An application that wishes to display in Latin-1 would use
645 render; charset=marc8,iso-8859-1
648 <sect2><title>Z39.50 Protocol behavior</title>
650 The functions <function>ZOOM_resultset_record</function> and
651 <function>ZOOM_resultset_records</function> inspects the client-side
652 record cache. Records not found in cache are fetched using
654 The functions may block (and perform network I/O) - even though option
655 <literal>async</literal> is 1, because they return records objects.
656 (and there's no way to return records objects without retrieving them!).
659 There is a trick, however, in the usage of function
660 <function>ZOOM_resultset_records</function> that allows for
661 delayed retrieval (and makes it non-blocking). By using
662 a null pointer for <parameter>recs</parameter> you're indicating
663 you're not interested in getting records objects
664 <emphasis>now</emphasis>.
667 <sect2><title>SRW Protocol behavior</title>
669 The ZOOM driver for SRW treats records returned by a SRW server
670 as if they where Z39.50 records with transfer syntax XML and
671 no element set name or database name.
675 <sect1 id="zoom.scan"><title>Scan</title>
677 This section describes an interface for Scan. Scan is not an
678 official part of the ZOOM model yet. The result of a scan operation
679 is the <literal>ZOOM_scanset</literal> which is a set of terms
680 returned by a target.
684 The Scan interface is Z39.50 only. SRW version 1.0 does not
689 ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
690 const char *startterm);
692 size_t ZOOM_scanset_size(ZOOM_scanset scan);
694 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
695 int *occ, size_t *len);
698 void ZOOM_scanset_destroy (ZOOM_scanset scan);
700 const char *ZOOM_scanset_option_get (ZOOM_scanset scan,
703 void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
707 The scan set is created by function
708 <function>ZOOM_connection_scan</function> which performs a scan
709 operation on the connection and start term given.
710 If the operation was successful, the size of the scan set can be
711 retrieved by a call to <function>ZOOM_scanset_size</function>.
712 Like result sets, the items are numbered 0,..size-1.
713 To obtain information about a particular scan term, call function
714 <function>ZOOM_scanset_term</function>. This function takes
715 a scan set offset <literal>pos</literal> and returns a pointer
716 to an actual term or <literal>NULL</literal> if non-present.
717 If present, the <literal>occ</literal> and <literal>len</literal>
718 are set to the number of occurrences and the length
719 of the actual term respectively.
720 A scan set may be freed by a call to function
721 <function>ZOOM_scanset_destroy</function>.
722 Functions <function>ZOOM_scanset_option_get</function> and
723 <function>ZOOM_scanset_option_set</function> retrieves and sets
724 an option respectively.
727 <table frame="top"><title>ZOOM Scan Set Options</title>
729 <colspec colwidth="4*" colname="name"></colspec>
730 <colspec colwidth="7*" colname="description"></colspec>
731 <colspec colwidth="2*" colname="default"></colspec>
734 <entry>Option</entry>
735 <entry>Description</entry>
736 <entry>Default</entry>
741 number</entry><entry>Number of Scan Terms requested in next scan.
742 After scan it holds the actual number of terms returned.
743 </entry><entry>10</entry></row>
745 position</entry><entry>Preferred Position of term in response
746 in next scan; actual position after completion of scan.
747 </entry><entry>1</entry></row>
749 stepSize</entry><entry>Step Size
750 </entry><entry>0</entry></row>
752 scanStatus</entry><entry>An integer indicating the Scan Status
754 </entry><entry>0</entry></row>
760 <sect1 id="zoom.options"><title>Options</title>
762 Most &zoom; objects provide a way to specify options to change behavior.
763 From an implementation point of view a set of options is just like
764 an associative array / hash array, etc.
767 ZOOM_options ZOOM_options_create (void);
769 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
771 void ZOOM_options_destroy (ZOOM_options opt);
774 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
776 void ZOOM_options_set (ZOOM_options opt, const char *name,
780 typedef const char *(*ZOOM_options_callback)
781 (void *handle, const char *name);
783 ZOOM_options_callback
784 ZOOM_options_set_callback (ZOOM_options opt,
785 ZOOM_options_callback c,
789 <sect1 id="zoom.events"><title>Events</title>
791 If you're developing non-blocking applications, you have to deal
795 int ZOOM_event (int no, ZOOM_connection *cs);
798 The <function>ZOOM_event</function> executes pending events for
799 a number of connections. Supply the number of connections in
800 <literal>no</literal> and an array of connections in
801 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
802 A pending event could be a sending a search, receiving a response,
804 When an event has occurred for one of the connections, this function
805 returns a positive integer <literal>n</literal> denoting that an event
806 occurred for connection <literal>cs[n-1]</literal>.
807 When no events are pending for the connections, a value of zero is
809 To ensure that all outstanding requests are performed call this function
810 repeatedly until zero is returned.
815 <!-- Keep this comment at the end of the file
820 sgml-minimize-attributes:nil
821 sgml-always-quote-attributes:t
824 sgml-parent-document: "yaz.xml"
825 sgml-local-catalogs: nil
826 sgml-namecase-general:t