3 ZOOM_connection_errcode(c)
4 ZOOM_connection_errmsg(c)
5 ZOOM_connection_addinfo(c)
6 ZOOM_connection_addinfo(c)
7 ZOOM_connection_diagset(c);
9 ZOOM_resultset_record_immediate(s, pos)
10 ZOOM_resultset_cache_reset(r)
11 ZOOM_resultset_sort(r, sort_type, sort_spec)
12 ZOOM_resultset_sort1(r, sort_type, sort_spec)
13 ZOOM_options_set_callback(opt, function, handle)
14 ZOOM_options_create_with_parent2(parent1, parent2)
15 ZOOM_options_getl(opt, name, len)
16 ZOOM_options_setl(opt, name, value, len)
17 ZOOM_options_get_bool(opt, name, defa)
18 ZOOM_options_get_int(opt, name, defa)
19 ZOOM_options_set_int(opt, name, value)
20 ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm)
21 ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
23 <!-- $Id: zoom.xml,v 1.52 2006-10-05 08:26:58 adam Exp $ -->
24 <chapter id="zoom"><title>ZOOM</title>
26 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
27 an initiative started by Mike Taylor (Mike is from the UK, which
28 explains the peculiar name of the model). The goal of &zoom; is to
29 provide a common Z39.50 client API not bound to a particular
30 programming language or toolkit.
35 A recent addition to &yaz; is SRU support. You can now make
36 SRU ZOOM connections by specifying scheme <literal>http://</literal>
37 for the hostname for a connection.
42 The lack of a simple Z39.50 client API for &yaz; has become more
43 and more apparent over time. So when the first &zoom; specification
45 an implementation for &yaz; was quickly developed. For the first time, it is
46 now as easy (or easier!) to develop clients than servers with &yaz;. This
47 chapter describes the &zoom; C binding. Before going further, please
48 reconsider whether C is the right programming language for the job.
49 There are other language bindings available for &yaz;, and still
51 are in active development. See the
52 <ulink url="&url.zoom;">ZOOM web-site</ulink> for
57 In order to fully understand this chapter you should read and
58 try the example programs <literal>zoomtst1.c</literal>,
59 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
64 The C language misses features found in object oriented languages
65 such as C++, Java, etc. For example, you'll have to manually,
66 destroy all objects you create, even though you may think of them as
67 temporary. Most objects has a <literal>_create</literal> - and a
68 <literal>_destroy</literal> variant.
69 All objects are in fact pointers to internal stuff, but you don't see
70 that because of typedefs. All destroy methods should gracefully ignore a
71 <literal>NULL</literal> pointer.
74 In each of the sections below you'll find a sub section called
75 protocol behavior, that describes how the API maps to the Z39.50
78 <sect1 id="zoom-connections"><title>Connections</title>
80 <para>The Connection object is a session with a target.
83 #include <yaz/zoom.h>
85 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
87 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
89 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
91 void ZOOM_connection_destroy (ZOOM_connection c);
94 Connection objects are created with either function
95 <function>ZOOM_connection_new</function> or
96 <function>ZOOM_connection_create</function>.
97 The former creates and automatically attempts to establish a network
98 connection with the target. The latter doesn't establish
99 a connection immediately, thus allowing you to specify options
100 before establishing network connection using the function
101 <function>ZOOM_connection_connect</function>.
102 If the port number, <literal>portnum</literal>, is zero, the
103 <literal>host</literal> is consulted for a port specification.
104 If no port is given, 210 is used. A colon denotes the beginning of
105 a port number in the host string. If the host string includes a
106 slash, the following part specifies a database for the connection.
109 You can prefix the host with a scheme followed by colon. The
110 default scheme is <literal>tcp</literal> (Z39.50 protocol).
111 The scheme <literal>http</literal> selects SRU over HTTP.
114 You can prefix the scheme-qualified host-string with one or more
116 <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
117 sequences, each of which represents an option to be set into the
118 connection structure <emphasis>before</emphasis> the
119 protocol-level connection is forged and the initialisation
120 handshake takes place. This facility can be used to provide
121 authentication credentials, as in host-strings such as:
122 <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
125 Connection objects should be destroyed using the function
126 <function>ZOOM_connection_destroy</function>.
129 void ZOOM_connection_option_set(ZOOM_connection c,
130 const char *key, const char *val);
132 void ZOOM_connection_option_setl(ZOOM_connection c,
134 const char *val, int len);
136 const char *ZOOM_connection_option_get(ZOOM_connection c,
138 const char *ZOOM_connection_option_getl(ZOOM_connection c,
143 The functions <function>ZOOM_connection_option_set</function> and
144 <function>ZOOM_connection_option_setl</function> allows you to
145 set an option given by <parameter>key</parameter> to the value
146 <parameter>value</parameter> for the connection.
147 For <function>ZOOM_connection_option_set</function>, the
148 value is assumed to be a 0-terminated string. Function
149 <function>ZOOM_connection_option_setl</function> specifies a
150 value of a certain size (len).
153 Functions <function>ZOOM_connection_option_get</function> and
154 <function>ZOOM_connection_option_getl</function> returns
155 the value for an option given by <parameter>key</parameter>.
157 <table id="zoom-connection-options" frame="top">
158 <title>ZOOM Connection Options</title>
160 <colspec colwidth="4*" colname="name"></colspec>
161 <colspec colwidth="7*" colname="description"></colspec>
162 <colspec colwidth="3*" colname="default"></colspec>
165 <entry>Option</entry>
166 <entry>Description</entry>
167 <entry>Default</entry>
172 implementationName</entry><entry>Name of Your client
173 </entry><entry>none</entry></row>
175 user</entry><entry>Authentication user name
176 </entry><entry>none</entry></row>
178 group</entry><entry>Authentication group name
179 </entry><entry>none</entry></row>
181 password</entry><entry>Authentication password.
182 </entry><entry>none</entry></row>
184 host</entry><entry>Target host. This setting is "read-only".
185 It's automatically set internally when connecting to a target.
186 </entry><entry>none</entry></row>
188 proxy</entry><entry>Proxy host
189 </entry><entry>none</entry></row>
191 async</entry><entry>If true (1) the connection operates in
192 asynchronous operation which means that all calls are non-blocking
194 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
195 </entry><entry>0</entry></row>
197 maximumRecordSize</entry><entry> Maximum size of single record.
198 </entry><entry>1 MB</entry></row>
200 preferredMessageSize</entry><entry> Maximum size of multiple records.
201 </entry><entry>1 MB</entry></row>
203 lang</entry><entry> Language for negotiation.
204 </entry><entry>none</entry></row>
206 charset</entry><entry> Character set for negotiation.
207 </entry><entry>none</entry></row>
209 serverImplementationId</entry><entry>
210 Implementation ID of server. (The old targetImplementationId
211 option is also supported for the benefit of old applications.)
212 </entry><entry>none</entry></row>
214 targetImplementationName</entry><entry>
215 Implementation Name of server. (The old
216 targetImplementationName option is also supported for the
217 benefit of old applications.)
218 </entry><entry>none</entry></row>
220 serverImplementationVersion</entry><entry>
221 Implementation Version of server. (the old
222 targetImplementationVersion option is also supported for the
223 benefit of old applications.)
224 </entry><entry>none</entry></row>
226 databaseName</entry><entry>One or more database names
227 separated by character plus (<literal>+</literal>), which to
228 be used by subsequent search requests on this Connection.
229 </entry><entry>Default</entry></row>
231 piggyback</entry><entry>True (1) if piggyback should be
232 used in searches; false (0) if not.
233 </entry><entry>1</entry></row>
235 smallSetUpperBound</entry><entry>If hits is less than or equal to this
236 value, then target will return all records using small element set name
237 </entry><entry>0</entry></row>
239 largeSetLowerBound</entry><entry>If hits is greater than this
240 value, the target will return no records.
241 </entry><entry>1</entry></row>
243 mediumSetPresentNumber</entry><entry>This value represents
244 the number of records to be returned as part of a search when when
245 hits is less than or equal to large set lower bound and if hits
246 is greater than small set upper bound.
247 </entry><entry>0</entry></row>
249 smallSetElementSetName</entry><entry>
250 The element set name to be used for small result sets.
251 </entry><entry>none</entry></row>
253 mediumSetElementSetName</entry><entry>
254 The element set name to be for medium-sized result sets.
255 </entry><entry>none</entry></row>
260 If either option <literal>lang</literal> or <literal>charset</literal>
262 <ulink url="&url.z39.50.charneg;">
263 Character Set and Language Negotiation</ulink> is in effect.
266 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
267 const char **addinfo);
268 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
269 const char **addinfo, const char **dset);
272 Function <function>ZOOM_connection_error</function> checks for
273 errors for the last operation(s) performed. The function returns
274 zero if no errors occurred; non-zero otherwise indicating the error.
275 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
276 holds messages for the error and additional-info if passed as
277 non-<literal>NULL</literal>. Function
278 <function>ZOOM_connection_error_x</function> is an extended version
279 of <function>ZOOM_connection_error</function> that is capable of
280 returning name of diagnostic set in <parameter>dset</parameter>.
282 <sect2 id="zoom-connection-z39.50">
283 <title>Z39.50 Protocol behavior</title>
285 The calls <function>ZOOM_connection_new</function> and
286 <function>ZOOM_connection_connect</function> establishes a TCP/IP
287 connection and sends an Initialize Request to the target if
288 possible. In addition, the calls waits for an Initialize Response
289 from the target and the result is inspected (OK or rejected).
292 If <literal>proxy</literal> is set then the client will establish
293 a TCP/IP connection with the peer as specified by the
294 <literal>proxy</literal> host and the hostname as part of the
295 connect calls will be set as part of the Initialize Request.
296 The proxy server will then "forward" the PDU's transparently
297 to the target behind the proxy.
300 For the authentication parameters, if option <literal>user</literal>
301 is set and both options <literal>group</literal> and
302 <literal>pass</literal> are unset, then Open style
303 authentication is used (Version 2/3) in which case the username
304 is usually followed by a slash, then by a password.
305 If either <literal>group</literal>
306 or <literal>pass</literal> is set then idPass authentication
307 (Version 3 only) is used. If none of the options are set, no
308 authentication parameters are set as part of the Initialize Request
312 When option <literal>async</literal> is 1, it really means that
313 all network operations are postponed (and queued) until the
314 function <literal>ZOOM_event</literal> is invoked. When doing so
315 it doesn't make sense to check for errors after
316 <literal>ZOOM_connection_new</literal> is called since that
317 operation "connecting - and init" is still incomplete and the
318 API cannot tell the outcome (yet).
321 <sect2 id="zoom.sru.init.behavior">
322 <title>SRU Protocol behavior</title>
324 The SRU protocol doesn't feature an Inititialize Request, so
325 the connection phase merely establishes a TCP/IP connection
326 with the SOAP service.
328 <para>Most of the ZOOM connection options do not
329 affect SRU and they are ignored. However, future versions
330 of &yaz; might honor <literal>implementationName</literal> and
331 put that as part of User-Agent header for HTTP requests.
334 The <literal>charset</literal> is used in the Content-Type header
339 <sect1 id="zoom.query"><title>Queries</title>
341 Query objects represents queries.
344 ZOOM_query ZOOM_query_create(void);
346 void ZOOM_query_destroy(ZOOM_query q);
348 int ZOOM_query_prefix(ZOOM_query q, const char *str);
350 int ZOOM_query_cql(ZOOM_query s, const char *str);
352 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
355 Create query objects using <function>ZOOM_query_create</function>
356 and destroy them by calling <function>ZOOM_query_destroy</function>.
357 RPN-queries can be specified in <link linkend="PQF">PQF</link>
358 notation by using the
359 function <function>ZOOM_query_prefix</function>.
360 The <function>ZOOM_query_cql</function> specifies a CQL
361 query to be sent to the server/target.
362 More query types will be added in future versions of &yaz;, such as
363 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
364 etc. In addition to a search, a sort criteria may be set. Function
365 <function>ZOOM_query_sortby</function> specifies a
366 sort criteria using the same string notation for sort as offered by
367 the <link linkend="sortspec">YAZ client</link>.
369 <sect2 id="zoom.sort.behavior"><title>Protocol behavior</title>
371 The query object is just an interface for the member Query
372 in the SearchRequest. The sortby-function is an interface to the
373 sortSequence member of the SortRequest.
377 <sect1 id="zoom.resultsets"><title>Result sets</title>
379 The result set object is a container for records returned from
383 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
386 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
389 void ZOOM_resultset_destroy(ZOOM_resultset r);
392 Function <function>ZOOM_connection_search</function> creates
393 a result set given a connection and query.
394 Destroy a result set by calling
395 <function>ZOOM_resultset_destroy</function>.
396 Simple clients may using PQF only may use function
397 <function>ZOOM_connection_search_pqf</function> in which case
398 creating query objects is not necessary.
401 void ZOOM_resultset_option_set (ZOOM_resultset r,
405 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
408 size_t ZOOM_resultset_size (ZOOM_resultset r);
411 Functions <function>ZOOM_resultset_options_set</function> and
412 <function>ZOOM_resultset_get</function> sets and gets an option
413 for a result set similar to <function>ZOOM_connection_option_get</function>
414 and <function>ZOOM_connection_option_set</function>.
417 The number of hits also called result-count is returned by
418 function <function>ZOOM_resultset_size</function>.
420 <table id="zoom.resultset.options"
421 frame="top"><title>ZOOM Result set Options</title>
423 <colspec colwidth="4*" colname="name"></colspec>
424 <colspec colwidth="7*" colname="description"></colspec>
425 <colspec colwidth="2*" colname="default"></colspec>
428 <entry>Option</entry>
429 <entry>Description</entry>
430 <entry>Default</entry>
435 start</entry><entry>Offset of first record to be
436 retrieved from target. First record has offset 0 unlike the
437 protocol specifications where first record has position 1.
438 </entry><entry>0</entry></row>
440 count</entry><entry>Number of records to be retrieved.
441 </entry><entry>0</entry></row>
443 presentChunk</entry><entry>The number of records to be
444 requested from the server in each chunk (present requst). The
445 value 0 means to request all the records in a single chunk.
446 (The old <literal>step</literal>
447 option is also supported for the benefit of old applications.)
448 </entry><entry>0</entry></row>
450 elementSetName</entry><entry>Element-Set name of records.
451 Most targets should honor element set name <literal>B</literal>
452 and <literal>F</literal> for brief and full respectively.
453 </entry><entry>none</entry></row>
455 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
456 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
457 </entry><entry>none</entry></row>
459 schema</entry><entry>Schema for retrieval, such as
460 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
461 </entry><entry>none</entry></row>
463 setname</entry><entry>Name of Result Set (Result Set ID).
464 If this option isn't set, the ZOOM module will automatically
465 allocate a result set name.
466 </entry><entry>default</entry></row>
471 For servers that support Search Info report, the following
472 options may be read using <function>ZOOM_resultset_get</function>.
473 This detailed information is read after a successful search has
477 This information is a list of of items, where each item is
478 information about a term or subquery. All items in the list
480 <literal>SearchResult.</literal><replaceable>no</replaceable>
481 where no presents the item number (0=first, 1=second).
482 Read <literal>searchresult.size</literal> to determine the
485 <table id="zoom.search.info.report.options"
486 frame="top"><title>Search Info Report Options</title>
488 <colspec colwidth="4*" colname="name"></colspec>
489 <colspec colwidth="7*" colname="description"></colspec>
492 <entry>Option</entry>
493 <entry>Description</entry>
498 <entry>searchresult.size</entry>
500 number of search result entries. This option is-nonexistant
501 if no entries are returned by the server.
505 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
506 <entry>sub query ID</entry>
509 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
510 <entry>result count for item (number of hits)</entry>
513 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
514 <entry>subquery term</entry>
518 searchresult.<replaceable>no</replaceable>.interpretation.term
520 <entry>interpretation term</entry>
524 searchresult.<replaceable>no</replaceable>.recommendation.term
526 <entry>recommendation term</entry>
531 <sect2 id="zoom.z3950.resultset.behavior">
532 <title>Z39.50 Protocol behavior</title>
534 The creation of a result set involves at least a SearchRequest
535 - SearchResponse protocol handshake. Following that, if a sort
536 criteria was specified as part of the query, a SortRequest -
537 SortResponse handshake takes place. Note that it is necessary to
538 perform sorting before any retrieval takes place, so no records will
539 be returned from the target as part of the SearchResponse because these
540 would be unsorted. Hence, piggyback is disabled when sort criteria
541 are set. Following Search - and a possible sort - Retrieval takes
542 place - as one or more Present Requests/Response pairs being
546 The API allows for two different modes for retrieval. A high level
547 mode which is somewhat more powerful and a low level one.
548 The low level is enabled when searching on a Connection object
549 for which the settings
550 <literal>smallSetUpperBound</literal>,
551 <literal>mediumSetPresentNumber</literal> and
552 <literal>largeSetLowerBound</literal> are set. The low level mode
553 thus allows you to precisely set how records are returned as part
554 of a search response as offered by the Z39.50 protocol.
555 Since the client may be retrieving records as part of the
556 search response, this mode doesn't work well if sorting is used.
559 The high-level mode allows you to fetch a range of records from
560 the result set with a given start offset. When you use this mode
561 the client will automatically use piggyback if that is possible
562 with the target and perform one or more present requests as needed.
563 Even if the target returns fewer records as part of a present response
564 because of a record size limit, etc. the client will repeat sending
565 present requests. As an example, if option <literal>start</literal>
566 is 0 (default) and <literal>count</literal> is 4, and
567 <literal>piggyback</literal> is 1 (default) and no sorting criteria
568 is specified, then the client will attempt to retrieve the 4
569 records as part the search response (using piggyback). On the other
570 hand, if either <literal>start</literal> is positive or if
571 a sorting criteria is set, or if <literal>piggyback</literal>
572 is 0, then the client will not perform piggyback but send Present
576 If either of the options <literal>mediumSetElementSetName</literal> and
577 <literal>smallSetElementSetName</literal> are unset, the value
578 of option <literal>elementSetName</literal> is used for piggyback
579 searches. This means that for the high-level mode you only have
580 to specify one elementSetName option rather than three.
583 <sect2 id="zoom.sru.resultset.behavior">
584 <title>SRU Protocol behavior</title>
586 Current version of &yaz; does not take advantage of a result set id
587 returned by the SRU server. Future versions might do, however.
588 Since, the ZOOM driver does not save result set IDs any
589 present (retrieval) is transformed to a SRU SearchRetrieveRequest
590 with same query but, possibly, different offsets.
593 Option <literal>schema</literal> specifies SRU schema
594 for retrieval. However, options <literal>elementSetName</literal> and
595 <literal>preferredRecordSyntax</literal> are ignored.
598 Options <literal>start</literal> and <literal>count</literal>
599 are supported by SRU.
600 The remaining options
601 <literal>piggyback</literal>,
602 <literal>smallSetUpperBound</literal>,
603 <literal>largeSetLowerBound</literal>,
604 <literal>mediumSetPresentNumber</literal>,
605 <literal>mediumSetElementSetName</literal>,
606 <literal>smallSetElementSetName</literal> are
610 SRU supports CQL queries, <emphasis>not</emphasis> PQF.
611 If PQF is used, however, the PQF query is transferred anyway
612 using non-standard element <literal>pQuery</literal> in
613 SRU SearchRetrieveRequest.
616 Unfortunately, SRU does not define a database setting. Hence,
617 <literal>databaseName</literal> is unsupported and ignored.
618 However, the path part in host parameter for functions
619 <function>ZOOM_connecton_new</function> and
620 <function>ZOOM_connection_connect</function> acts as a
621 database (at least for the &yaz; SRU server).
625 <sect1 id="zoom.records"><title>Records</title>
627 A record object is a retrieval record on the client side -
628 created from result sets.
631 void ZOOM_resultset_records (ZOOM_resultset r,
633 size_t start, size_t count);
634 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
636 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
639 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
641 void ZOOM_record_destroy (ZOOM_record rec);
644 References to temporary records are returned by functions
645 <function>ZOOM_resultset_records</function> or
646 <function>ZOOM_resultset_record</function>.
649 If a persistent reference to a record is desired
650 <function>ZOOM_record_clone</function> should be used.
651 It returns a record reference that should be destroyed
652 by a call to <function>ZOOM_record_destroy</function>.
655 A single record is returned by function
656 <function>ZOOM_resultset_record</function> that takes a
657 position as argument. First record has position zero.
658 If no record could be obtained <literal>NULL</literal> is returned.
661 Function <function>ZOOM_resultset_records</function> retrieves
662 a number of records from a result set. Parameter <literal>start</literal>
663 and <literal>count</literal> specifies the range of records to
664 be returned. Upon completion array
665 <literal>recs[0], ..recs[count-1]</literal>
666 holds record objects for the records. The array of records
667 <literal>recs</literal> should be allocated prior the call
668 <function>ZOOM_resultset_records</function>. Note that for those
669 records that couldn't be retrieved from the target
670 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
672 <para id="zoom.record.get">
673 In order to extract information about a single record,
674 <function>ZOOM_record_get</function> is provided. The
675 function returns a pointer to certain record information. The
676 nature (type) of the pointer depends on the parameter,
677 <parameter>type</parameter>.
680 The <parameter>type</parameter> is a string of the format:
683 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
686 where <replaceable>form</replaceable> specifies the format of the
687 returned record, <replaceable>from</replaceable>
688 specifies the character set of the record in its original form
689 (as returned by the server), <replaceable>to</replaceable> specifies
690 the output (returned)
691 character set encoding.
692 If charset is not given, then no character set conversion takes place.
693 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
696 In addition, for certain types, the length
697 <literal>len</literal> passed will be set to the size in bytes of
698 the returned information.
701 The following are the supported values for <replaceable>form</replaceable>.
703 <varlistentry><term><literal>database</literal></term>
704 <listitem><para>Database of record is returned
705 as a C null-terminated string. Return type
706 <literal>const char *</literal>.
709 <varlistentry><term><literal>syntax</literal></term>
710 <listitem><para>The transfer syntax of the record is returned
711 as a C null-terminated string containing the symbolic name of
712 the record syntax, e.g. <literal>Usmarc</literal>. Return type
714 <literal>const char *</literal>.
717 <varlistentry><term><literal>render</literal></term>
718 <listitem><para>The record is returned in a display friendly
719 format. Upon completion buffer is returned
720 (type <literal>const char *</literal>) and length is stored in
721 <literal>*len</literal>.
724 <varlistentry><term><literal>raw</literal></term>
725 <listitem><para>The record is returned in the internal
726 YAZ specific format. For GRS-1, Explain, and others, the
727 raw data is returned as type
728 <literal>Z_External *</literal> which is just the type for
729 the member <literal>retrievalRecord</literal> in
730 type <literal>NamePlusRecord</literal>.
731 For SUTRS and octet aligned record (including all MARCs) the
732 octet buffer is returned and the length of the buffer.
735 <varlistentry><term><literal>xml</literal></term>
736 <listitem><para>The record is returned in XML if possible.
737 SRU and Z39.50 records with transfer syntax XML are
738 returned verbatim. MARC records are returned in
739 <ulink url="&url.marcxml;">
742 (converted from ISO2709 to MARCXML by YAZ).
743 GRS-1 and OPAC records are not supported for this form.
744 Upon completion, the XML buffer is returned
745 (type <literal>const char *</literal>) and length is stored in
746 <literal>*len</literal>.
749 <varlistentry><term><literal>opac</literal></term>
750 <listitem><para>OPAC for record is returned in XML.
757 <ulink url="&url.marc21;">MARC21</ulink>
759 <ulink url="&url.marc8;">MARC-8</ulink>
760 character set encoding.
761 An application that wishes to display in Latin-1 would use
763 render; charset=marc8,iso-8859-1
766 <sect2 id="zoom.z3950.record.behavior">
767 <title>Z39.50 Protocol behavior</title>
769 The functions <function>ZOOM_resultset_record</function> and
770 <function>ZOOM_resultset_records</function> inspects the client-side
771 record cache. Records not found in cache are fetched using
773 The functions may block (and perform network I/O) - even though option
774 <literal>async</literal> is 1, because they return records objects.
775 (and there's no way to return records objects without retrieving them!).
778 There is a trick, however, in the usage of function
779 <function>ZOOM_resultset_records</function> that allows for
780 delayed retrieval (and makes it non-blocking). By using
781 a null pointer for <parameter>recs</parameter> you're indicating
782 you're not interested in getting records objects
783 <emphasis>now</emphasis>.
786 <sect2 id="zoom.sru.record.behavior">
787 <title>SRU Protocol behavior</title>
789 The ZOOM driver for SRU treats records returned by a SRU server
790 as if they where Z39.50 records with transfer syntax XML and
791 no element set name or database name.
795 <sect1 id="zoom.scan"><title>Scan</title>
797 This section describes an interface for Scan. Scan is not an
798 official part of the ZOOM model yet. The result of a scan operation
799 is the <literal>ZOOM_scanset</literal> which is a set of terms
800 returned by a target.
804 The Scan interface is Z39.50 only. SRW version 1.0 does not
809 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
810 const char *startpqf);
812 size_t ZOOM_scanset_size(ZOOM_scanset scan);
814 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
815 int *occ, size_t *len);
817 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
818 int *occ, size_t *len);
820 void ZOOM_scanset_destroy (ZOOM_scanset scan);
822 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
825 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
829 The scan set is created by function
830 <function>ZOOM_connection_scan</function> which performs a scan
831 operation on the connection using the specified
832 <parameter>startpqf</parameter>.
833 If the operation was successful, the size of the scan set can be
834 retrieved by a call to <function>ZOOM_scanset_size</function>.
835 Like result sets, the items are numbered 0,..size-1.
836 To obtain information about a particular scan term, call function
837 <function>ZOOM_scanset_term</function>. This function takes
838 a scan set offset <literal>pos</literal> and returns a pointer
839 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
841 If present, the <literal>occ</literal> and <literal>len</literal>
842 are set to the number of occurrences and the length
843 of the actual term respectively.
844 <function>ZOOM_scanset_display_term</function> is similar to
845 <function>ZOOM_scanset_term</function> except that it returns
846 the <emphasis>display term</emphasis> rather than the raw term.
847 In a few cases, the term is different from display term. Always
848 use the display term for display and the raw term for subsequent
849 scan operations (to get more terms, next scan result, etc).
852 A scan set may be freed by a call to function
853 <function>ZOOM_scanset_destroy</function>.
854 Functions <function>ZOOM_scanset_option_get</function> and
855 <function>ZOOM_scanset_option_set</function> retrieves and sets
856 an option respectively.
860 The <parameter>startpqf</parameter> is a subset of PQF, namely
861 the Attributes+Term part. Multiple <literal>@attr</literal> can
862 be used. For example to scan in title (complete) phrases:
864 @attr 1=4 @attr 6=2 "science o"
868 <table frame="top" id="zoom.scanset.options">
869 <title>ZOOM Scan Set Options</title>
871 <colspec colwidth="4*" colname="name"></colspec>
872 <colspec colwidth="7*" colname="description"></colspec>
873 <colspec colwidth="2*" colname="default"></colspec>
876 <entry>Option</entry>
877 <entry>Description</entry>
878 <entry>Default</entry>
883 number</entry><entry>Number of Scan Terms requested in next scan.
884 After scan it holds the actual number of terms returned.
885 </entry><entry>10</entry></row>
887 position</entry><entry>Preferred Position of term in response
888 in next scan; actual position after completion of scan.
889 </entry><entry>1</entry></row>
891 stepSize</entry><entry>Step Size
892 </entry><entry>0</entry></row>
894 scanStatus</entry><entry>An integer indicating the Scan Status
896 </entry><entry>0</entry></row>
902 <sect1 id="zoom.extendedservices"><title>Extended Services</title>
904 ZOOM offers an interface to a subset of the Z39.50 extended services
905 as well as a few privately defined ones:
910 Z39.50 Item Order (ILL).
911 See <xref linkend="zoom.item.order"/>.
916 Record Update. This allows a client to insert, modify or delete
918 See <xref linkend="zoom.record.update"/>.
923 Database Create. This a non-standard feature. Allows a client
924 to create a database.
925 See <xref linkend="zoom.database.create"/>.
930 Database Drop. This a non-standard feature. Allows a client
931 to delete/drop a database.
932 See <xref linkend="zoom.database.drop"/>.
937 Commit operation. This a non-standard feature. Allows a client
938 to commit operations.
939 See <xref linkend="zoom.commit"/>.
942 <!-- all the ILL PDU options should go here too -->
945 To create an extended service operation a <literal>ZOOM_package</literal>
946 must be created. The operation is a five step operation. The
947 package is created, package is configured by means of options,
948 the package is send, result is inspected (by means of options),
949 the package is destroyed.
952 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
953 ZOOM_options options);
955 const char *ZOOM_package_option_get(ZOOM_package p,
957 void ZOOM_package_option_set(ZOOM_package p, const char *key,
959 void ZOOM_package_send(ZOOM_package p, const char *type);
961 void ZOOM_package_destroy(ZOOM_package p);
964 The <function>ZOOM_connection_package</function> creates a
965 package for the connection given using the options specified.
968 Functions <function>ZOOM_package_option_get</function> and
969 <function>ZOOM_package_option_set</function> gets and sets
973 <function>ZOOM_package_send</function> sends
974 the package the via connection specified in
975 <function>ZOOM_connection_package</function>.
976 The <parameter>type</parameter> specifies the actual extended service
977 package type to be sent.
980 <table frame="top" id="zoom.extendedservices.options">
981 <title>Extended Service Common Options</title>
983 <colspec colwidth="4*" colname="name"></colspec>
984 <colspec colwidth="7*" colname="description"></colspec>
985 <colspec colwidth="3*" colname="default"></colspec>
988 <entry>Option</entry>
989 <entry>Description</entry>
990 <entry>Default</entry>
995 <entry>package-name</entry>
996 <entry>Extended Service Request package name. Must be specified
997 as part of a request</entry>
1001 <entry>user-id</entry>
1002 <entry>User ID of Extended Service Package. Is a request option</entry>
1006 <entry>function</entry>
1008 Function of package - one of <literal>create</literal>,
1009 <literal>delete</literal>, <literal>modify</literal>. Is
1012 <entry><literal>create</literal></entry>
1015 <entry>targetReference</entry>
1017 Target Reference. This is part of the response as returned
1018 by the server. Read it after a succesful operation.
1020 <entry><literal>none</literal></entry>
1026 <sect2 id="zoom.item.order"><title>Item Order</title>
1028 For Item Order, type must be set to <literal>itemorder</literal> in
1029 <function>ZOOM_package_send</function>.
1032 <table frame="top" id="zoom.item.order.options">
1033 <title>Item Order Options</title>
1035 <colspec colwidth="4*" colname="name"></colspec>
1036 <colspec colwidth="7*" colname="description"></colspec>
1037 <colspec colwidth="3*" colname="default"></colspec>
1040 <entry>Option</entry>
1041 <entry>Description</entry>
1042 <entry>Default</entry>
1047 <entry>contact-name</entry>
1048 <entry>ILL contact name</entry>
1052 <entry>contact-phone</entry>
1053 <entry>ILL contact phone</entry>
1057 <entry>contact-email</entry>
1058 <entry>ILL contact email</entry>
1062 <entry>itemorder-item</entry>
1063 <entry>Position for item (record) requested. An integer</entry>
1072 <sect2 id="zoom.record.update"><title>Record Update</title>
1074 For Record Update, type must be set to <literal>update</literal> in
1075 <function>ZOOM_package_send</function>.
1078 <table frame="top" id="zoom.record.update.options">
1079 <title>Record Update Options</title>
1081 <colspec colwidth="4*" colname="name"></colspec>
1082 <colspec colwidth="7*" colname="description"></colspec>
1083 <colspec colwidth="3*" colname="default"></colspec>
1086 <entry>Option</entry>
1087 <entry>Description</entry>
1088 <entry>Default</entry>
1093 <entry>action</entry>
1095 The update action. One of
1096 <literal>specialUpdate</literal>,
1097 <literal>recordInsert</literal>,
1098 <literal>recordReplace</literal>,
1099 <literal>recordDelete</literal>,
1100 <literal>elementUpdate</literal>.
1102 <entry><literal>specialUpdate</literal></entry>
1105 <entry>recordIdOpaque</entry>
1106 <entry>Opaque Record ID</entry>
1110 <entry>recordIdNumber</entry>
1111 <entry>Record ID number</entry>
1115 <entry>record</entry>
1116 <entry>The record itself</entry>
1120 <entry>syntax</entry>
1121 <entry>The record syntax (transfer syntax). Is a string that
1122 is a known record syntax.
1124 <entry>no syntax</entry>
1127 <entry>databaseName</entry>
1128 <entry>Database from connection object</entry>
1129 <entry>Default</entry>
1137 <sect2 id="zoom.database.create"><title>Database Create</title>
1139 For Database Create, type must be set to <literal>create</literal> in
1140 <function>ZOOM_package_send</function>.
1143 <table frame="top" id="zoom.database.create.options">
1144 <title>Database Create Options</title>
1146 <colspec colwidth="4*" colname="name"></colspec>
1147 <colspec colwidth="7*" colname="description"></colspec>
1148 <colspec colwidth="3*" colname="default"></colspec>
1151 <entry>Option</entry>
1152 <entry>Description</entry>
1153 <entry>Default</entry>
1158 <entry>databaseName</entry>
1159 <entry>Database from connection object</entry>
1160 <entry>Default</entry>
1167 <sect2 id="zoom.database.drop"><title>Database Drop</title>
1169 For Database Drop, type must be set to <literal>drop</literal> in
1170 <function>ZOOM_package_send</function>.
1173 <table frame="top" id="zoom.database.drop.options">
1174 <title>Database Drop Options</title>
1176 <colspec colwidth="4*" colname="name"></colspec>
1177 <colspec colwidth="7*" colname="description"></colspec>
1178 <colspec colwidth="3*" colname="default"></colspec>
1181 <entry>Option</entry>
1182 <entry>Description</entry>
1183 <entry>Default</entry>
1188 <entry>databaseName</entry>
1189 <entry>Database from connection object</entry>
1190 <entry>Default</entry>
1197 <sect2 id="zoom.commit"><title>Commit Operation</title>
1199 For Commit, type must be set to <literal>commit</literal> in
1200 <function>ZOOM_package_send</function>.
1204 <sect2 id="zoom.extended.services.behavior">
1205 <title>Protocol behavior</title>
1207 All the extended services are Z39.50-only.
1211 The database create, drop and commit services are privately defined
1213 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1220 <sect1 id="zoom.options"><title>Options</title>
1222 Most &zoom; objects provide a way to specify options to change behavior.
1223 From an implementation point of view a set of options is just like
1224 an associative array / hash.
1227 ZOOM_options ZOOM_options_create (void);
1229 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1231 void ZOOM_options_destroy (ZOOM_options opt);
1234 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1236 void ZOOM_options_set (ZOOM_options opt, const char *name,
1240 typedef const char *(*ZOOM_options_callback)
1241 (void *handle, const char *name);
1243 ZOOM_options_callback
1244 ZOOM_options_set_callback (ZOOM_options opt,
1245 ZOOM_options_callback c,
1249 <sect1 id="zoom.events"><title>Events</title>
1251 If you're developing non-blocking applications, you have to deal
1255 int ZOOM_event (int no, ZOOM_connection *cs);
1258 The <function>ZOOM_event</function> executes pending events for
1259 a number of connections. Supply the number of connections in
1260 <literal>no</literal> and an array of connections in
1261 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1262 A pending event could be a sending a search, receiving a response,
1264 When an event has occurred for one of the connections, this function
1265 returns a positive integer <literal>n</literal> denoting that an event
1266 occurred for connection <literal>cs[n-1]</literal>.
1267 When no events are pending for the connections, a value of zero is
1269 To ensure that all outstanding requests are performed call this function
1270 repeatedly until zero is returned.
1273 If <function>ZOOM_event</function> returns and returns non-zero, the
1274 last event that occurred can be expected.
1277 int ZOOM_connection_last_event(ZOOM_connection cs);
1280 <function>ZOOM_connection_last_event</function> returns an event type
1281 (integer) for the last event.
1284 <table frame="top" id="zoom.event.ids">
1285 <title>ZOOM Event IDs</title>
1287 <colspec colwidth="4*" colname="name"></colspec>
1288 <colspec colwidth="7*" colname="description"></colspec>
1291 <entry>Event</entry>
1292 <entry>Description</entry>
1297 <entry>ZOOM_EVENT_NONE</entry>
1298 <entry>No event has occurred</entry>
1301 <entry>ZOOM_EVENT_CONNECT</entry>
1302 <entry>TCP/IP connect has initiated</entry>
1305 <entry>ZOOM_EVENT_SEND_DATA</entry>
1306 <entry>Data has been transmitted (sending)</entry>
1309 <entry>ZOOM_EVENT_RECV_DATA</entry>
1310 <entry>Data has been received)</entry>
1313 <entry>ZOOM_EVENT_TIMEOUT</entry>
1314 <entry>Timeout</entry>
1317 <entry>ZOOM_EVENT_UNKNOWN</entry>
1318 <entry>Unknown event</entry>
1321 <entry>ZOOM_EVENT_SEND_APDU</entry>
1322 <entry>An APDU has been transmitted (sending)</entry>
1325 <entry>ZOOM_EVENT_RECV_APDU</entry>
1326 <entry>An APDU has been received</entry>
1329 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1330 <entry>A result-set record has been received</entry>
1333 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1334 <entry>A search result been received</entry>
1342 <!-- Keep this comment at the end of the file
1347 sgml-minimize-attributes:nil
1348 sgml-always-quote-attributes:t
1351 sgml-parent-document: "yaz.xml"
1352 sgml-local-catalogs: nil
1353 sgml-namecase-general:t