1 <!-- $Id: zoom.xml,v 1.22 2003-02-21 00:24:26 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 a new scheme for the
15 host name 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>
174 If either option <literal>lang</literal> or <literal>charset</literal>
176 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
177 Character Set and Language Negotiation</ulink> is in effect.
180 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
181 const char **addinfo);
182 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
183 const char **addinfo, const char **dset);
186 Function <function>ZOOM_connection_error</function> checks for
187 errors for the last operation(s) performed. The function returns
188 zero if no errors occurred; non-zero otherwise indicating the error.
189 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
190 holds messages for the error and additional-info if passed as
191 non-<literal>NULL</literal>. Function
192 <function>ZOOM_connection_error_x</function> is an extended version
193 of <function>ZOOM_connection_error</function> that is capable of
194 returning name of diagnostic set in <parameter>dset</parameter>.
196 <sect2><title>Z39.50 Protocol behavior</title>
198 The calls <function>ZOOM_connection_new</function> and
199 <function>ZOOM_connection_connect</function> establishes a TCP/IP
200 connection and sends an Initialize Request to the target if
201 possible. In addition, the calls waits for an Initialize Response
202 from the target and the result is inspected (OK or rejected).
205 If <literal>proxy</literal> is set then the client will establish
206 a TCP/IP connection with the peer as specified by the
207 <literal>proxy</literal> host and the hostname as part of the
208 connect calls will be set as part of the Initialize Request.
209 The proxy server will then "forward" the PDU's transparently
210 to the target behind the proxy.
213 For the authentication parameters, if option <literal>user</literal>
214 is set and both options <literal>group</literal> and
215 <literal>pass</literal> are unset, then Open style
216 authentication is used (Version 2/3) in which case the username
217 is usually followed by a slash, then by a password.
218 If either <literal>group</literal>
219 or <literal>pass</literal> is set then idPass authentication
220 (Version 3 only) is used. If none of the options are set, no
221 authentication parameters are set as part of the Initialize Request
225 When option <literal>async</literal> is 1, it really means that
226 all network operations are postponed (and queued) until the
227 function <literal>ZOOM_event</literal> is invoked. When doing so
228 it doesn't make sense to check for errors after
229 <literal>ZOOM_connection_new</literal> is called since that
230 operation "connecting - and init" is still incomplete and the
231 API cannot tell the outcome (yet).
234 <sect2><title>SRW Protocol behavior</title>
236 The SRW protocol doesn't feature an Init Request, so
237 the connection phase merely establishes a TCP/IP connection
238 with the SOAP service.
240 <para>None of the ZOOM connection options
241 affect SRW and they are ignored. However, future versions
242 of &yaz; might honor <literal>implementationName</literal> and
243 put that as part of User-Agent header for HTTP requests.
244 The <literal>charset</literal>, and <literal>lang</literal>
245 might also affect HTTP headers in future releases.
249 <sect1 id="zoom.query"><title>Queries</title>
251 Query objects represents queries.
254 ZOOM_query ZOOM_query_create(void);
256 void ZOOM_query_destroy(ZOOM_query q);
258 int ZOOM_query_prefix(ZOOM_query q, const char *str);
260 int ZOOM_query_cql(ZOOM_query s, const char *str);
262 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
265 Create query objects using <function>ZOOM_query_create</function>
266 and destroy them by calling <function>ZOOM_query_destroy</function>.
267 RPN-queries can be specified in <link linkend="PQF">PQF</link>
268 notation by using the
269 function <function>ZOOM_query_prefix</function>.
270 The <function>ZOOM_query_cql</function> specifies a CQL
271 query to be sent to the server/target.
272 More query types will be added in future versions of &yaz;, such as
273 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
274 etc. In addition to a search, a sort criteria may be set. Function
275 <function>ZOOM_query_sortby</function> specifies a
276 sort criteria using the same string notation for sort as offered by
277 the <link linkend="sortspec">YAZ client</link>.
279 <sect2><title>Protocol behavior</title>
281 The query object is just an interface for the member Query
282 in the SearchRequest. The sortby-function is an interface to the
283 sortSequence member of the SortRequest.
287 <sect1 id="zoom.resultsets"><title>Result sets</title>
289 The result set object is a container for records returned from
293 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
296 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
299 void ZOOM_resultset_destroy(ZOOM_resultset r);
302 Function <function>ZOOM_connection_search</function> creates
303 a result set given a connection and query.
304 Destroy a result set by calling
305 <function>ZOOM_resultset_destroy</function>.
306 Simple clients may using PQF only may use function
307 <function>ZOOM_connection_search_pqf</function> in which case
308 creating query objects is not necessary.
311 void ZOOM_resultset_option_set (ZOOM_resultset r,
315 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
318 size_t ZOOM_resultset_size (ZOOM_resultset r);
321 Functions <function>ZOOM_resultset_options_set</function> and
322 <function>ZOOM_resultset_get</function> sets and gets an option
323 for a result set similar to <function>ZOOM_connection_option_get</function>
324 and <function>ZOOM_connection_option_set</function>.
327 The number of hits also called result-count is returned by
328 function <function>ZOOM_resultset_size</function>.
330 <table frame="top"><title>ZOOM Result set Options</title>
332 <colspec colwidth="4*" colname="name"></colspec>
333 <colspec colwidth="7*" colname="description"></colspec>
334 <colspec colwidth="2*" colname="default"></colspec>
337 <entry>Option</entry>
338 <entry>Description</entry>
339 <entry>Default</entry>
344 piggyback</entry><entry>True (1) if piggyback should be
345 used in searches; false (0) if not.
346 </entry><entry>1</entry></row>
348 start</entry><entry>Offset of first record to be
349 retrieved from target. First record has offset 0 unlike the
350 protocol specifications where first record has position 1.
351 </entry><entry>0</entry></row>
353 count</entry><entry>Number of records to be retrieved.
354 </entry><entry>0</entry></row>
356 elementSetName</entry><entry>Element-Set name of records.
357 Most targets should honor element set name <literal>B</literal>
358 and <literal>F</literal> for brief and full respectively.
359 </entry><entry>none</entry></row>
361 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
362 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
363 </entry><entry>none</entry></row>
365 schema</entry><entry>Schema for retrieval, such as
366 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
367 </entry><entry>none</entry></row>
369 smallSetUpperBound</entry><entry>If hits is less than or equal to this
370 value, then target will return all records using small element set name
371 </entry><entry>0</entry></row>
373 largeSetLowerBound</entry><entry>If hits is greater than this
374 value, the target will return no records.
375 </entry><entry>1</entry></row>
377 mediumSetPresentNumber</entry><entry>This value represents
378 the number of records to be returned as part of a search when when
379 hits is less than or equal to large set lower bound and if hits
380 is greater than small set upper bound.
381 </entry><entry>0</entry></row>
383 smallSetElementSetName</entry><entry>
384 The element set name to be used for small result sets.
385 </entry><entry>none</entry></row>
387 mediumSetElementSetName</entry><entry>
388 The element set name to be for medium-sized result sets.
389 </entry><entry>none</entry></row>
391 databaseName</entry><entry>One or more database names
392 separated by character plus (<literal>+</literal>).
393 </entry><entry>Default</entry></row>
395 setname</entry><entry>Name of Result Set (Result Set ID).
396 If this option isn't set, the ZOOM module will automatically
397 allocate a result set name.
398 </entry><entry>default</entry></row>
403 <title>Z39.50 Protocol behavior</title>
405 The creation of a result set involves at least a SearchRequest
406 - SearchResponse protocol handshake. Following that, if a sort
407 criteria was specified as part of the query, a SortRequest -
408 SortResponse handshake takes place. Note that it is necessary to
409 perform sorting before any retrieval takes place, so no records will
410 be returned from the target as part of the SearchResponse because these
411 would be unsorted. Hence, piggyback is disabled when sort criteria
412 is set. Following Search - and a Possible sort, Retrieval takes
413 place - as one or more Present Requests - Present Response being
417 The API allows for two different modes for retrieval. A high level
418 mode which is somewhat more powerful and a low level one.
419 The low level is "enabled" when the settings
420 <literal>smallSetUpperBound</literal>,
421 <literal>mediumSetPresentNumber</literal> and
422 <literal>largeSetLowerBound</literal> are set. The low level mode
423 thus allows you to precisely set how records are returned as part
424 of a search response as offered by the Z39.50 protocol.
425 Since the client may be retrieving records as part of the
426 search response, this mode doesn't work well if sorting is used.
429 The high-level mode allows you to fetch a range of records from
430 the result set with a given start offset. When you use this mode
431 the client will automatically use piggyback if that is possible
432 with the target and perform one or more present requests as needed.
433 Even if the target returns fewer records as part of a present response
434 because of a record size limit, etc. the client will repeat sending
435 present requests. As an example, if option <literal>start</literal>
436 is 0 (default) and <literal>count</literal> is 4, and
437 <literal>piggyback</literal> is 1 (default) and no sorting criteria
438 is specified, then the client will attempt to retrieve the 4
439 records as part the search response (using piggyback). On the other
440 hand, if either <literal>start</literal> is positive or if
441 a sorting criteria is set, or if <literal>piggyback</literal>
442 is 0, then the client will not perform piggyback but send Present
446 If either of the options <literal>mediumSetElementSetName</literal> and
447 <literal>smallSetElementSetName</literal> are unset, the value
448 of option <literal>elementSetName</literal> is used for piggyback
449 searches. This means that for the high-level mode you only have
450 to specify one elementSetName option rather than three.
454 <title>SRW Protocol behavior</title>
456 Current version of &yaz; does not take advantage of a result set id
457 returned by the SRW server. Future versions might do, however.
458 Since, the ZOOM driver does not save result set IDs any
459 present (retrieval) is transformed to a SRW SearchRetrieveRequest
460 with same query but, possibly, different offsets.
463 Option <literal>schema</literal> specifies SRW schema
464 for retrieval. However, options <literal>elementSetName</literal> and
465 <literal>preferredRecordSyntax</literal> are ignored.
468 Options <literal>start</literal> and <literal>count</literal>
469 are supported by SRW.
470 The remaining options
471 <literal>piggyback</literal>,
472 <literal>smallSetUpperBound</literal>,
473 <literal>largeSetLowerBound</literal>,
474 <literal>mediumSetPresentNumber</literal>,
475 <literal>mediumSetElementSetName</literal>,
476 <literal>smallSetElementSetName</literal> are
480 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
481 If PQF is used, however, the PQF query is transferred anyway
482 using non-standard element <literal>pQuery</literal> in
483 SRW SearchRetrieveRequest.
486 Unfortunately, SRW does not define a database setting. Hence,
487 <literal>databaseName</literal> is unsupported and ignored.
488 However, the path part in host parameter for functions
489 <function>ZOOM_connecton_new</function> and
490 <function>ZOOM_connection_connect</function> acts as a
491 database (at least for the &yaz; SRW server).
495 <sect1 id="zoom.records"><title>Records</title>
497 A record object is a retrieval record on the client side -
498 created from result sets.
501 void ZOOM_resultset_records (ZOOM_resultset r,
503 size_t start, size_t count);
504 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
506 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
509 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
511 void ZOOM_record_destroy (ZOOM_record rec);
514 References to temporary records are returned by functions
515 <function>ZOOM_resultset_records</function> or
516 <function>ZOOM_resultset_record</function>.
519 If a persistent reference to a record is desired
520 <function>ZOOM_record_clone</function> should be used.
521 It returns a record reference that should be destroyed
522 by a call to <function>ZOOM_record_destroy</function>.
525 A single record is returned by function
526 <function>ZOOM_resultset_record</function> that takes a
527 position as argument. First record has position zero.
528 If no record could be obtained <literal>NULL</literal> is returned.
531 Function <function>ZOOM_resultset_records</function> retrieves
532 a number of records from a result set. Parameter <literal>start</literal>
533 and <literal>count</literal> specifies the range of records to
534 be returned. Upon completion array
535 <literal>recs[0], ..recs[count-1]</literal>
536 holds record objects for the records. The array of records
537 <literal>recs</literal> should be allocated prior the call
538 <function>ZOOM_resultset_records</function>. Note that for those
539 records that couldn't be retrieved from the target
540 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
542 <para id="zoom.record.get">
543 In order to extract information about a single record,
544 <function>ZOOM_record_get</function> is provided. The
545 function returns a pointer to certain record information. The
546 nature (type) of the pointer depends on the parameter,
547 <function>type</function>.
548 In addition, for certain types, the length
549 <literal>len</literal> passed will be set to the size in bytes of
550 the returned information.
552 <varlistentry><term><literal>database</literal></term>
553 <listitem><para>Database of record is returned
554 as a C null-terminated string. Return type
555 <literal>const char *</literal>.
558 <varlistentry><term><literal>syntax</literal></term>
559 <listitem><para>The transfer syntax (OID) of the record is returned
560 as a C null-terminated string. Return type is
561 <literal>const char *</literal>.
564 <varlistentry><term><literal>render</literal></term>
565 <listitem><para>The record is returned in a display friendly
566 format. Upon completion buffer is returned
567 (type <literal>const char *</literal>) and length is stored in
568 <literal>*len</literal>.
571 <varlistentry><term><literal>raw</literal></term>
572 <listitem><para>The record is returned in the internal
573 YAZ specific format. For GRS-1, Explain, and others, the
574 raw data is returned as type
575 <literal>Z_External *</literal> which is just the type for
576 the member <literal>retrievalRecord</literal> in
577 type <literal>NamePlusRecord</literal>.
578 For SUTRS and octet aligned record (including all MARCs) the
579 octet buffer is returned and the length of the buffer.
584 <sect2><title>Z39.50 Protocol behavior</title>
586 The functions <function>ZOOM_resultset_record</function> and
587 <function>ZOOM_resultset_records</function> inspects the client-side
588 record cache. Records not found in cache are fetched using
590 The functions may block (and perform network I/O) - even though option
591 <literal>async</literal> is 1, because they return records objects.
592 (and there's no way to return records objects without retrieving them!).
595 There is a trick, however, in the usage of function
596 <function>ZOOM_resultset_records</function> that allows for
597 delayed retrieval (and makes it non-blocking). By passing
598 a null pointer for <parameter>recs</parameter> you're indicating
599 you're not interested in getting records objects
600 <emphasis>now</emphasis>.
603 <sect2><title>SRW Protocol behavior</title>
605 The ZOOM driver for SRW treats records returned by a SRW server
606 as if they where Z39.50 records with transfer syntax XML and
607 no element set name or database name.
611 <sect1 id="zoom.scan"><title>Scan</title>
613 This section describes an interface for Scan. Scan is not an
614 official part of the ZOOM model yet. The result of a scan operation
615 is the <literal>ZOOM_scanset</literal> which is a set of terms
616 returned by a target.
620 The Scan interface is Z39.50 only. SRW version 1.0 does not
625 ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
626 const char *startterm);
628 size_t ZOOM_scanset_size(ZOOM_scanset scan);
630 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
631 int *occ, size_t *len);
634 void ZOOM_scanset_destroy (ZOOM_scanset scan);
636 const char *ZOOM_scanset_option_get (ZOOM_scanset scan,
639 void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
643 The scan set is created by function
644 <function>ZOOM_connection_scan</function> which performs a scan
645 operation on the connection and start term given.
646 If the operation was successful, the size of the scan set can be
647 retrieved by a call to <function>ZOOM_scanset_size</function>.
648 Like result sets, the items are numbered 0,..size-1.
649 To obtain information about a particular scan term, call function
650 <function>ZOOM_scanset_term</function>. This function takes
651 a scan set offset <literal>pos</literal> and returns a pointer
652 to an actual term or <literal>NULL</literal> if non-present.
653 If present, the <literal>occ</literal> and <literal>len</literal>
654 are set to the number of occurrences and the length
655 of the actual term respectively.
656 A scan set may be freed by a call to function
657 <function>ZOOM_scanset_destroy</function>.
658 Functions <function>ZOOM_scanset_option_get</function> and
659 <function>ZOOM_scanset_option_set</function> retrieves and sets
660 an option respectively.
663 <table frame="top"><title>ZOOM Scan Set Options</title>
665 <colspec colwidth="4*" colname="name"></colspec>
666 <colspec colwidth="7*" colname="description"></colspec>
667 <colspec colwidth="2*" colname="default"></colspec>
670 <entry>Option</entry>
671 <entry>Description</entry>
672 <entry>Default</entry>
677 number</entry><entry>Number of Scan Terms requested in next scan.
678 After scan it holds the actual number of terms returned.
679 </entry><entry>10</entry></row>
681 position</entry><entry>Preferred Position of term in response
682 in next scan; actual position after completion of scan.
683 </entry><entry>1</entry></row>
685 stepSize</entry><entry>Step Size
686 </entry><entry>0</entry></row>
688 scanStatus</entry><entry>An integer indicating the Scan Status
690 </entry><entry>0</entry></row>
696 <sect1 id="zoom.options"><title>Options</title>
698 Most &zoom; objects provide a way to specify options to change behavior.
699 From an implementation point of view a set of options is just like
700 an associative array / hash array, etc.
703 ZOOM_options ZOOM_options_create (void);
705 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
707 void ZOOM_options_destroy (ZOOM_options opt);
710 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
712 void ZOOM_options_set (ZOOM_options opt, const char *name,
716 typedef const char *(*ZOOM_options_callback)
717 (void *handle, const char *name);
719 ZOOM_options_callback
720 ZOOM_options_set_callback (ZOOM_options opt,
721 ZOOM_options_callback c,
725 <sect1 id="zoom.events"><title>Events</title>
727 If you're developing non-blocking applications, you have to deal
731 int ZOOM_event (int no, ZOOM_connection *cs);
734 The <function>ZOOM_event</function> executes pending events for
735 a number of connections. Supply the number of connections in
736 <literal>no</literal> and an array of connections in
737 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
738 A pending event could be a sending a search, receiving a response,
740 When an event has occurred for one of the connections, this function
741 returns a positive integer <literal>n</literal> denoting that an event
742 occurred for connection <literal>cs[n-1]</literal>.
743 When no events are pending for the connections, a value of zero is
745 To ensure that all outstanding requests are performed call this function
746 repeatedly until zero is returned.
751 <!-- Keep this comment at the end of the file
756 sgml-minimize-attributes:nil
757 sgml-always-quote-attributes:t
760 sgml-parent-document: "yaz.xml"
761 sgml-local-catalogs: nil
762 sgml-namecase-general:t