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.47 2006-04-24 09:21:35 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 SRW support. You can now make
36 SRW 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 SRW 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 frame="top"><title>ZOOM Connection Options</title>
159 <colspec colwidth="4*" colname="name"></colspec>
160 <colspec colwidth="7*" colname="description"></colspec>
161 <colspec colwidth="3*" colname="default"></colspec>
164 <entry>Option</entry>
165 <entry>Description</entry>
166 <entry>Default</entry>
171 implementationName</entry><entry>Name of Your client
172 </entry><entry>none</entry></row>
174 user</entry><entry>Authentication user name
175 </entry><entry>none</entry></row>
177 group</entry><entry>Authentication group name
178 </entry><entry>none</entry></row>
180 password</entry><entry>Authentication password.
181 </entry><entry>none</entry></row>
183 host</entry><entry>Target host. This setting is "read-only".
184 It's automatically set internally when connecting to a target.
185 </entry><entry>none</entry></row>
187 proxy</entry><entry>Proxy host
188 </entry><entry>none</entry></row>
190 async</entry><entry>If true (1) the connection operates in
191 asynchronous operation which means that all calls are non-blocking
193 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
194 </entry><entry>0</entry></row>
196 maximumRecordSize</entry><entry> Maximum size of single record.
197 </entry><entry>1 MB</entry></row>
199 preferredMessageSize</entry><entry> Maximum size of multiple records.
200 </entry><entry>1 MB</entry></row>
202 lang</entry><entry> Language for negotiation.
203 </entry><entry>none</entry></row>
205 charset</entry><entry> Character set for negotiation.
206 </entry><entry>none</entry></row>
208 serverImplementationId</entry><entry>
209 Implementation ID of server. (The old targetImplementationId
210 option is also supported for the benefit of old applications.)
211 </entry><entry>none</entry></row>
213 targetImplementationName</entry><entry>
214 Implementation Name of server. (The old
215 targetImplementationName option is also supported for the
216 benefit of old applications.)
217 </entry><entry>none</entry></row>
219 serverImplementationVersion</entry><entry>
220 Implementation Version of server. (the old
221 targetImplementationVersion option is also supported for the
222 benefit of old applications.)
223 </entry><entry>none</entry></row>
225 databaseName</entry><entry>One or more database names
226 separated by character plus (<literal>+</literal>), which to
227 be used by subsequent search requests on this Connection.
228 </entry><entry>Default</entry></row>
230 piggyback</entry><entry>True (1) if piggyback should be
231 used in searches; false (0) if not.
232 </entry><entry>1</entry></row>
234 smallSetUpperBound</entry><entry>If hits is less than or equal to this
235 value, then target will return all records using small element set name
236 </entry><entry>0</entry></row>
238 largeSetLowerBound</entry><entry>If hits is greater than this
239 value, the target will return no records.
240 </entry><entry>1</entry></row>
242 mediumSetPresentNumber</entry><entry>This value represents
243 the number of records to be returned as part of a search when when
244 hits is less than or equal to large set lower bound and if hits
245 is greater than small set upper bound.
246 </entry><entry>0</entry></row>
248 smallSetElementSetName</entry><entry>
249 The element set name to be used for small result sets.
250 </entry><entry>none</entry></row>
252 mediumSetElementSetName</entry><entry>
253 The element set name to be for medium-sized result sets.
254 </entry><entry>none</entry></row>
259 If either option <literal>lang</literal> or <literal>charset</literal>
261 <ulink url="&url.z39.50.charneg;">
262 Character Set and Language Negotiation</ulink> is in effect.
265 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
266 const char **addinfo);
267 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
268 const char **addinfo, const char **dset);
271 Function <function>ZOOM_connection_error</function> checks for
272 errors for the last operation(s) performed. The function returns
273 zero if no errors occurred; non-zero otherwise indicating the error.
274 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
275 holds messages for the error and additional-info if passed as
276 non-<literal>NULL</literal>. Function
277 <function>ZOOM_connection_error_x</function> is an extended version
278 of <function>ZOOM_connection_error</function> that is capable of
279 returning name of diagnostic set in <parameter>dset</parameter>.
281 <sect2><title>Z39.50 Protocol behavior</title>
283 The calls <function>ZOOM_connection_new</function> and
284 <function>ZOOM_connection_connect</function> establishes a TCP/IP
285 connection and sends an Initialize Request to the target if
286 possible. In addition, the calls waits for an Initialize Response
287 from the target and the result is inspected (OK or rejected).
290 If <literal>proxy</literal> is set then the client will establish
291 a TCP/IP connection with the peer as specified by the
292 <literal>proxy</literal> host and the hostname as part of the
293 connect calls will be set as part of the Initialize Request.
294 The proxy server will then "forward" the PDU's transparently
295 to the target behind the proxy.
298 For the authentication parameters, if option <literal>user</literal>
299 is set and both options <literal>group</literal> and
300 <literal>pass</literal> are unset, then Open style
301 authentication is used (Version 2/3) in which case the username
302 is usually followed by a slash, then by a password.
303 If either <literal>group</literal>
304 or <literal>pass</literal> is set then idPass authentication
305 (Version 3 only) is used. If none of the options are set, no
306 authentication parameters are set as part of the Initialize Request
310 When option <literal>async</literal> is 1, it really means that
311 all network operations are postponed (and queued) until the
312 function <literal>ZOOM_event</literal> is invoked. When doing so
313 it doesn't make sense to check for errors after
314 <literal>ZOOM_connection_new</literal> is called since that
315 operation "connecting - and init" is still incomplete and the
316 API cannot tell the outcome (yet).
319 <sect2><title>SRW Protocol behavior</title>
321 The SRW protocol doesn't feature an Inititialize Request, so
322 the connection phase merely establishes a TCP/IP connection
323 with the SOAP service.
325 <para>Most of the ZOOM connection options do not
326 affect SRW and they are ignored. However, future versions
327 of &yaz; might honor <literal>implementationName</literal> and
328 put that as part of User-Agent header for HTTP requests.
331 The <literal>charset</literal> is used in the Content-Type header
336 <sect1 id="zoom.query"><title>Queries</title>
338 Query objects represents queries.
341 ZOOM_query ZOOM_query_create(void);
343 void ZOOM_query_destroy(ZOOM_query q);
345 int ZOOM_query_prefix(ZOOM_query q, const char *str);
347 int ZOOM_query_cql(ZOOM_query s, const char *str);
349 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
352 Create query objects using <function>ZOOM_query_create</function>
353 and destroy them by calling <function>ZOOM_query_destroy</function>.
354 RPN-queries can be specified in <link linkend="PQF">PQF</link>
355 notation by using the
356 function <function>ZOOM_query_prefix</function>.
357 The <function>ZOOM_query_cql</function> specifies a CQL
358 query to be sent to the server/target.
359 More query types will be added in future versions of &yaz;, such as
360 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
361 etc. In addition to a search, a sort criteria may be set. Function
362 <function>ZOOM_query_sortby</function> specifies a
363 sort criteria using the same string notation for sort as offered by
364 the <link linkend="sortspec">YAZ client</link>.
366 <sect2><title>Protocol behavior</title>
368 The query object is just an interface for the member Query
369 in the SearchRequest. The sortby-function is an interface to the
370 sortSequence member of the SortRequest.
374 <sect1 id="zoom.resultsets"><title>Result sets</title>
376 The result set object is a container for records returned from
380 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
383 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
386 void ZOOM_resultset_destroy(ZOOM_resultset r);
389 Function <function>ZOOM_connection_search</function> creates
390 a result set given a connection and query.
391 Destroy a result set by calling
392 <function>ZOOM_resultset_destroy</function>.
393 Simple clients may using PQF only may use function
394 <function>ZOOM_connection_search_pqf</function> in which case
395 creating query objects is not necessary.
398 void ZOOM_resultset_option_set (ZOOM_resultset r,
402 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
405 size_t ZOOM_resultset_size (ZOOM_resultset r);
408 Functions <function>ZOOM_resultset_options_set</function> and
409 <function>ZOOM_resultset_get</function> sets and gets an option
410 for a result set similar to <function>ZOOM_connection_option_get</function>
411 and <function>ZOOM_connection_option_set</function>.
414 The number of hits also called result-count is returned by
415 function <function>ZOOM_resultset_size</function>.
417 <table frame="top"><title>ZOOM Result set Options</title>
419 <colspec colwidth="4*" colname="name"></colspec>
420 <colspec colwidth="7*" colname="description"></colspec>
421 <colspec colwidth="2*" colname="default"></colspec>
424 <entry>Option</entry>
425 <entry>Description</entry>
426 <entry>Default</entry>
431 start</entry><entry>Offset of first record to be
432 retrieved from target. First record has offset 0 unlike the
433 protocol specifications where first record has position 1.
434 </entry><entry>0</entry></row>
436 count</entry><entry>Number of records to be retrieved.
437 </entry><entry>0</entry></row>
439 presentChunk</entry><entry>The number of records to be
440 requested from the server in each chunk (present requst). The
441 value 0 means to request all the records in a single chunk.
442 (The old <literal>step</literal>
443 option is also supported for the benefit of old applications.)
444 </entry><entry>0</entry></row>
446 elementSetName</entry><entry>Element-Set name of records.
447 Most targets should honor element set name <literal>B</literal>
448 and <literal>F</literal> for brief and full respectively.
449 </entry><entry>none</entry></row>
451 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
452 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
453 </entry><entry>none</entry></row>
455 schema</entry><entry>Schema for retrieval, such as
456 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
457 </entry><entry>none</entry></row>
459 setname</entry><entry>Name of Result Set (Result Set ID).
460 If this option isn't set, the ZOOM module will automatically
461 allocate a result set name.
462 </entry><entry>default</entry></row>
467 For servers that support Search Info report, the following
468 options may be read using <function>ZOOM_resultset_get</function>.
469 This detailed information is read after a successful search has
473 This information is a list of of items, where each item is
474 information about a term or subquery. All items in the list
476 <literal>SearchResult.</literal><replaceable>no</replaceable>
477 where no presents the item number (0=first, 1=second).
478 Read <literal>searchresult.size</literal> to determine the
481 <table frame="top"><title>Search Info Report options</title>
483 <colspec colwidth="4*" colname="name"></colspec>
484 <colspec colwidth="7*" colname="description"></colspec>
487 <entry>Option</entry>
488 <entry>Description</entry>
493 <entry>searchresult.size</entry>
495 number of search result entries. This option is-nonexistant
496 if no entries are returned by the server.
500 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
501 <entry>sub query ID</entry>
504 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
505 <entry>result count for item (number of hits)</entry>
508 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
509 <entry>subquery term</entry>
513 searchresult.<replaceable>no</replaceable>.interpretation.term
515 <entry>interpretation term</entry>
519 searchresult.<replaceable>no</replaceable>.recommendation.term
521 <entry>recommendation term</entry>
527 <title>Z39.50 Protocol behavior</title>
529 The creation of a result set involves at least a SearchRequest
530 - SearchResponse protocol handshake. Following that, if a sort
531 criteria was specified as part of the query, a SortRequest -
532 SortResponse handshake takes place. Note that it is necessary to
533 perform sorting before any retrieval takes place, so no records will
534 be returned from the target as part of the SearchResponse because these
535 would be unsorted. Hence, piggyback is disabled when sort criteria
536 are set. Following Search - and a possible sort - Retrieval takes
537 place - as one or more Present Requests/Response pairs being
541 The API allows for two different modes for retrieval. A high level
542 mode which is somewhat more powerful and a low level one.
543 The low level is enabled when searching on a Connection object
544 for which the settings
545 <literal>smallSetUpperBound</literal>,
546 <literal>mediumSetPresentNumber</literal> and
547 <literal>largeSetLowerBound</literal> are set. The low level mode
548 thus allows you to precisely set how records are returned as part
549 of a search response as offered by the Z39.50 protocol.
550 Since the client may be retrieving records as part of the
551 search response, this mode doesn't work well if sorting is used.
554 The high-level mode allows you to fetch a range of records from
555 the result set with a given start offset. When you use this mode
556 the client will automatically use piggyback if that is possible
557 with the target and perform one or more present requests as needed.
558 Even if the target returns fewer records as part of a present response
559 because of a record size limit, etc. the client will repeat sending
560 present requests. As an example, if option <literal>start</literal>
561 is 0 (default) and <literal>count</literal> is 4, and
562 <literal>piggyback</literal> is 1 (default) and no sorting criteria
563 is specified, then the client will attempt to retrieve the 4
564 records as part the search response (using piggyback). On the other
565 hand, if either <literal>start</literal> is positive or if
566 a sorting criteria is set, or if <literal>piggyback</literal>
567 is 0, then the client will not perform piggyback but send Present
571 If either of the options <literal>mediumSetElementSetName</literal> and
572 <literal>smallSetElementSetName</literal> are unset, the value
573 of option <literal>elementSetName</literal> is used for piggyback
574 searches. This means that for the high-level mode you only have
575 to specify one elementSetName option rather than three.
579 <title>SRW Protocol behavior</title>
581 Current version of &yaz; does not take advantage of a result set id
582 returned by the SRW server. Future versions might do, however.
583 Since, the ZOOM driver does not save result set IDs any
584 present (retrieval) is transformed to a SRW SearchRetrieveRequest
585 with same query but, possibly, different offsets.
588 Option <literal>schema</literal> specifies SRW schema
589 for retrieval. However, options <literal>elementSetName</literal> and
590 <literal>preferredRecordSyntax</literal> are ignored.
593 Options <literal>start</literal> and <literal>count</literal>
594 are supported by SRW.
595 The remaining options
596 <literal>piggyback</literal>,
597 <literal>smallSetUpperBound</literal>,
598 <literal>largeSetLowerBound</literal>,
599 <literal>mediumSetPresentNumber</literal>,
600 <literal>mediumSetElementSetName</literal>,
601 <literal>smallSetElementSetName</literal> are
605 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
606 If PQF is used, however, the PQF query is transferred anyway
607 using non-standard element <literal>pQuery</literal> in
608 SRW SearchRetrieveRequest.
611 Unfortunately, SRW does not define a database setting. Hence,
612 <literal>databaseName</literal> is unsupported and ignored.
613 However, the path part in host parameter for functions
614 <function>ZOOM_connecton_new</function> and
615 <function>ZOOM_connection_connect</function> acts as a
616 database (at least for the &yaz; SRW server).
620 <sect1 id="zoom.records"><title>Records</title>
622 A record object is a retrieval record on the client side -
623 created from result sets.
626 void ZOOM_resultset_records (ZOOM_resultset r,
628 size_t start, size_t count);
629 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
631 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
634 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
636 void ZOOM_record_destroy (ZOOM_record rec);
639 References to temporary records are returned by functions
640 <function>ZOOM_resultset_records</function> or
641 <function>ZOOM_resultset_record</function>.
644 If a persistent reference to a record is desired
645 <function>ZOOM_record_clone</function> should be used.
646 It returns a record reference that should be destroyed
647 by a call to <function>ZOOM_record_destroy</function>.
650 A single record is returned by function
651 <function>ZOOM_resultset_record</function> that takes a
652 position as argument. First record has position zero.
653 If no record could be obtained <literal>NULL</literal> is returned.
656 Function <function>ZOOM_resultset_records</function> retrieves
657 a number of records from a result set. Parameter <literal>start</literal>
658 and <literal>count</literal> specifies the range of records to
659 be returned. Upon completion array
660 <literal>recs[0], ..recs[count-1]</literal>
661 holds record objects for the records. The array of records
662 <literal>recs</literal> should be allocated prior the call
663 <function>ZOOM_resultset_records</function>. Note that for those
664 records that couldn't be retrieved from the target
665 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
667 <para id="zoom.record.get">
668 In order to extract information about a single record,
669 <function>ZOOM_record_get</function> is provided. The
670 function returns a pointer to certain record information. The
671 nature (type) of the pointer depends on the parameter,
672 <parameter>type</parameter>.
675 The <parameter>type</parameter> is a string of the format:
678 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
681 where <replaceable>form</replaceable> specifies the format of the
682 returned record, <replaceable>from</replaceable>
683 specifies the character set of the record in its original form
684 (as returned by the server), <replaceable>to</replaceable> specifies
685 the output (returned)
686 character set encoding.
687 If charset is not given, then no character set conversion takes place.
688 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
691 In addition, for certain types, the length
692 <literal>len</literal> passed will be set to the size in bytes of
693 the returned information.
696 The following are the supported values for <replaceable>form</replaceable>.
698 <varlistentry><term><literal>database</literal></term>
699 <listitem><para>Database of record is returned
700 as a C null-terminated string. Return type
701 <literal>const char *</literal>.
704 <varlistentry><term><literal>syntax</literal></term>
705 <listitem><para>The transfer syntax of the record is returned
706 as a C null-terminated string containing the symbolic name of
707 the record syntax, e.g. <literal>Usmarc</literal>. Return type
709 <literal>const char *</literal>.
712 <varlistentry><term><literal>render</literal></term>
713 <listitem><para>The record is returned in a display friendly
714 format. Upon completion buffer is returned
715 (type <literal>const char *</literal>) and length is stored in
716 <literal>*len</literal>.
719 <varlistentry><term><literal>raw</literal></term>
720 <listitem><para>The record is returned in the internal
721 YAZ specific format. For GRS-1, Explain, and others, the
722 raw data is returned as type
723 <literal>Z_External *</literal> which is just the type for
724 the member <literal>retrievalRecord</literal> in
725 type <literal>NamePlusRecord</literal>.
726 For SUTRS and octet aligned record (including all MARCs) the
727 octet buffer is returned and the length of the buffer.
730 <varlistentry><term><literal>xml</literal></term>
731 <listitem><para>The record is returned in XML if possible.
732 SRW/SRU and Z39.50 records with transfer syntax XML are
733 returned verbatim. MARC records are returned in
734 <ulink url="&url.marcxml;">
737 (converted from ISO2709 to MARCXML by YAZ).
738 GRS-1 and OPAC records are not supported for this form.
739 Upon completion, the XML buffer is returned
740 (type <literal>const char *</literal>) and length is stored in
741 <literal>*len</literal>.
744 <varlistentry><term><literal>opac</literal></term>
745 <listitem><para>OPAC for record is returned in XML.
752 <ulink url="&url.marc21;">MARC21</ulink>
754 <ulink url="&url.marc8;">MARC-8</ulink>
755 character set encoding.
756 An application that wishes to display in Latin-1 would use
758 render; charset=marc8,iso-8859-1
761 <sect2><title>Z39.50 Protocol behavior</title>
763 The functions <function>ZOOM_resultset_record</function> and
764 <function>ZOOM_resultset_records</function> inspects the client-side
765 record cache. Records not found in cache are fetched using
767 The functions may block (and perform network I/O) - even though option
768 <literal>async</literal> is 1, because they return records objects.
769 (and there's no way to return records objects without retrieving them!).
772 There is a trick, however, in the usage of function
773 <function>ZOOM_resultset_records</function> that allows for
774 delayed retrieval (and makes it non-blocking). By using
775 a null pointer for <parameter>recs</parameter> you're indicating
776 you're not interested in getting records objects
777 <emphasis>now</emphasis>.
780 <sect2><title>SRW Protocol behavior</title>
782 The ZOOM driver for SRW treats records returned by a SRW server
783 as if they where Z39.50 records with transfer syntax XML and
784 no element set name or database name.
788 <sect1 id="zoom.scan"><title>Scan</title>
790 This section describes an interface for Scan. Scan is not an
791 official part of the ZOOM model yet. The result of a scan operation
792 is the <literal>ZOOM_scanset</literal> which is a set of terms
793 returned by a target.
797 The Scan interface is Z39.50 only. SRW version 1.0 does not
802 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
803 const char *startpqf);
805 size_t ZOOM_scanset_size(ZOOM_scanset scan);
807 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
808 int *occ, size_t *len);
810 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
811 int *occ, size_t *len);
813 void ZOOM_scanset_destroy (ZOOM_scanset scan);
815 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
818 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
822 The scan set is created by function
823 <function>ZOOM_connection_scan</function> which performs a scan
824 operation on the connection using the specified
825 <parameter>startpqf</parameter>.
826 If the operation was successful, the size of the scan set can be
827 retrieved by a call to <function>ZOOM_scanset_size</function>.
828 Like result sets, the items are numbered 0,..size-1.
829 To obtain information about a particular scan term, call function
830 <function>ZOOM_scanset_term</function>. This function takes
831 a scan set offset <literal>pos</literal> and returns a pointer
832 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
834 If present, the <literal>occ</literal> and <literal>len</literal>
835 are set to the number of occurrences and the length
836 of the actual term respectively.
837 <function>ZOOM_scanset_display_term</function> is similar to
838 <function>ZOOM_scanset_term</function> except that it returns
839 the <emphasis>display term</emphasis> rather than the raw term.
840 In a few cases, the term is different from display term. Always
841 use the display term for display and the raw term for subsequent
842 scan operations (to get more terms, next scan result, etc).
845 A scan set may be freed by a call to function
846 <function>ZOOM_scanset_destroy</function>.
847 Functions <function>ZOOM_scanset_option_get</function> and
848 <function>ZOOM_scanset_option_set</function> retrieves and sets
849 an option respectively.
853 The <parameter>startpqf</parameter> is a subset of PQF, namely
854 the Attributes+Term part. Multiple <literal>@attr</literal> can
855 be used. For example to scan in title (complete) phrases:
857 @attr 1=4 @attr 6=2 "science o"
861 <table frame="top"><title>ZOOM Scan Set Options</title>
863 <colspec colwidth="4*" colname="name"></colspec>
864 <colspec colwidth="7*" colname="description"></colspec>
865 <colspec colwidth="2*" colname="default"></colspec>
868 <entry>Option</entry>
869 <entry>Description</entry>
870 <entry>Default</entry>
875 number</entry><entry>Number of Scan Terms requested in next scan.
876 After scan it holds the actual number of terms returned.
877 </entry><entry>10</entry></row>
879 position</entry><entry>Preferred Position of term in response
880 in next scan; actual position after completion of scan.
881 </entry><entry>1</entry></row>
883 stepSize</entry><entry>Step Size
884 </entry><entry>0</entry></row>
886 scanStatus</entry><entry>An integer indicating the Scan Status
888 </entry><entry>0</entry></row>
894 <sect1 id="zoom.ext"><title>Extended Services</title>
896 ZOOM offers an interface to a subset of the Z39.50 extended services
897 as well as a few privately defined ones:
902 Z39.50 Item Order (ILL).
903 See <xref linkend="zoom.ext.itemorder"/>.
908 Record Update. This allows a client to insert, modify or delete
910 See <xref linkend="zoom.ext.update"/>.
915 Database Create. This a non-standard feature. Allows a client
916 to create a database.
917 See <xref linkend="zoom.ext.dbcreate"/>.
922 Database Drop. This a non-standard feature. Allows a client
923 to delete/drop a database.
924 See <xref linkend="zoom.ext.dbdrop"/>.
929 Commit operation. This a non-standard feature. Allows a client
930 to commit operations.
931 See <xref linkend="zoom.ext.commit"/>.
934 <!-- all the ILL PDU options should go here too -->
937 To create an extended service operation a <literal>ZOOM_package</literal>
938 must be created. The operation is a five step operation. The
939 package is created, package is configured by means of options,
940 the package is send, result is inspected (by means of options),
941 the package is destroyed.
944 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
945 ZOOM_options options);
947 const char *ZOOM_package_option_get(ZOOM_package p,
949 void ZOOM_package_option_set(ZOOM_package p, const char *key,
951 void ZOOM_package_send(ZOOM_package p, const char *type);
953 void ZOOM_package_destroy(ZOOM_package p);
956 The <function>ZOOM_connection_package</function> creates a
957 package for the connection given using the options specified.
960 Functions <function>ZOOM_package_option_get</function> and
961 <function>ZOOM_package_option_set</function> gets and sets
965 <function>ZOOM_package_send</function> sends
966 the package the via connection specified in
967 <function>ZOOM_connection_package</function>.
968 The <parameter>type</parameter> specifies the actual extended service
969 package type to be sent.
972 <table frame="top"><title>Extended Service Common Options</title>
974 <colspec colwidth="4*" colname="name"></colspec>
975 <colspec colwidth="7*" colname="description"></colspec>
976 <colspec colwidth="3*" colname="default"></colspec>
979 <entry>Option</entry>
980 <entry>Description</entry>
981 <entry>Default</entry>
986 <entry>package-name</entry>
987 <entry>Extended Service Request package name. Must be specified
988 as part of a request</entry>
992 <entry>user-id</entry>
993 <entry>User ID of Extended Service Package. Is a request option</entry>
997 <entry>function</entry>
999 Function of package - one of <literal>create</literal>,
1000 <literal>delete</literal>, <literal>modify</literal>. Is
1003 <entry><literal>create</literal></entry>
1006 <entry>targetReference</entry>
1008 Target Reference. This is part of the response as returned
1009 by the server. Read it after a succesful operation.
1011 <entry><literal>none</literal></entry>
1017 <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
1019 For Item Order, type must be set to <literal>itemorder</literal> in
1020 <function>ZOOM_package_send</function>.
1023 <table frame="top"><title>Item Order Options</title>
1025 <colspec colwidth="4*" colname="name"></colspec>
1026 <colspec colwidth="7*" colname="description"></colspec>
1027 <colspec colwidth="3*" colname="default"></colspec>
1030 <entry>Option</entry>
1031 <entry>Description</entry>
1032 <entry>Default</entry>
1037 <entry>contact-name</entry>
1038 <entry>ILL contact name</entry>
1042 <entry>contact-phone</entry>
1043 <entry>ILL contact phone</entry>
1047 <entry>contact-email</entry>
1048 <entry>ILL contact email</entry>
1052 <entry>itemorder-item</entry>
1053 <entry>Position for item (record) requested. An integer</entry>
1062 <sect2 id="zoom.ext.update"><title>Record Update</title>
1064 For Record Update, type must be set to <literal>update</literal> in
1065 <function>ZOOM_package_send</function>.
1068 <table frame="top"><title>Record Update Options</title>
1070 <colspec colwidth="4*" colname="name"></colspec>
1071 <colspec colwidth="7*" colname="description"></colspec>
1072 <colspec colwidth="3*" colname="default"></colspec>
1075 <entry>Option</entry>
1076 <entry>Description</entry>
1077 <entry>Default</entry>
1082 <entry>action</entry>
1084 The update action. One of
1085 <literal>specialUpdate</literal>,
1086 <literal>recordInsert</literal>,
1087 <literal>recordReplace</literal>,
1088 <literal>recordDelete</literal>,
1089 <literal>elementUpdate</literal>.
1091 <entry><literal>specialUpdate</literal></entry>
1094 <entry>recordIdOpaque</entry>
1095 <entry>Opaque Record ID</entry>
1099 <entry>recordIdNumber</entry>
1100 <entry>Record ID number</entry>
1104 <entry>record</entry>
1105 <entry>The record itself</entry>
1109 <entry>syntax</entry>
1110 <entry>The record syntax (transfer syntax). Is a string that
1111 is a known record syntax.
1113 <entry>no syntax</entry>
1116 <entry>databaseName</entry>
1117 <entry>Database from connection object</entry>
1118 <entry>Default</entry>
1126 <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
1128 For Database Create, type must be set to <literal>create</literal> in
1129 <function>ZOOM_package_send</function>.
1132 <table frame="top"><title>Database Create Options</title>
1134 <colspec colwidth="4*" colname="name"></colspec>
1135 <colspec colwidth="7*" colname="description"></colspec>
1136 <colspec colwidth="3*" colname="default"></colspec>
1139 <entry>Option</entry>
1140 <entry>Description</entry>
1141 <entry>Default</entry>
1146 <entry>databaseName</entry>
1147 <entry>Database from connection object</entry>
1148 <entry>Default</entry>
1155 <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
1157 For Database Drop, type must be set to <literal>drop</literal> in
1158 <function>ZOOM_package_send</function>.
1161 <table frame="top"><title>Database Create Options</title>
1163 <colspec colwidth="4*" colname="name"></colspec>
1164 <colspec colwidth="7*" colname="description"></colspec>
1165 <colspec colwidth="3*" colname="default"></colspec>
1168 <entry>Option</entry>
1169 <entry>Description</entry>
1170 <entry>Default</entry>
1175 <entry>databaseName</entry>
1176 <entry>Database from connection object</entry>
1177 <entry>Default</entry>
1184 <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
1186 For Commit, type must be set to <literal>commit</literal> in
1187 <function>ZOOM_package_send</function>.
1191 <sect2><title>Protocol behavior</title>
1193 All the extended services are Z39.50-only.
1197 The database create, drop and commit services are privately defined
1199 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1206 <sect1 id="zoom.options"><title>Options</title>
1208 Most &zoom; objects provide a way to specify options to change behavior.
1209 From an implementation point of view a set of options is just like
1210 an associative array / hash.
1213 ZOOM_options ZOOM_options_create (void);
1215 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1217 void ZOOM_options_destroy (ZOOM_options opt);
1220 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1222 void ZOOM_options_set (ZOOM_options opt, const char *name,
1226 typedef const char *(*ZOOM_options_callback)
1227 (void *handle, const char *name);
1229 ZOOM_options_callback
1230 ZOOM_options_set_callback (ZOOM_options opt,
1231 ZOOM_options_callback c,
1235 <sect1 id="zoom.events"><title>Events</title>
1237 If you're developing non-blocking applications, you have to deal
1241 int ZOOM_event (int no, ZOOM_connection *cs);
1244 The <function>ZOOM_event</function> executes pending events for
1245 a number of connections. Supply the number of connections in
1246 <literal>no</literal> and an array of connections in
1247 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1248 A pending event could be a sending a search, receiving a response,
1250 When an event has occurred for one of the connections, this function
1251 returns a positive integer <literal>n</literal> denoting that an event
1252 occurred for connection <literal>cs[n-1]</literal>.
1253 When no events are pending for the connections, a value of zero is
1255 To ensure that all outstanding requests are performed call this function
1256 repeatedly until zero is returned.
1259 If <function>ZOOM_event</function> returns and returns non-zero, the
1260 last event that occurred can be expected.
1263 int ZOOM_connection_last_event(ZOOM_connection cs);
1266 <function>ZOOM_connection_last_event</function> returns an event type
1267 (integer) for the last event.
1270 <table frame="top"><title>ZOOM Event IDs</title>
1272 <colspec colwidth="4*" colname="name"></colspec>
1273 <colspec colwidth="7*" colname="description"></colspec>
1276 <entry>Event</entry>
1277 <entry>Description</entry>
1282 <entry>ZOOM_EVENT_NONE</entry>
1283 <entry>No event has occurred</entry>
1286 <entry>ZOOM_EVENT_CONNECT</entry>
1287 <entry>TCP/IP connect has initiated</entry>
1290 <entry>ZOOM_EVENT_SEND_DATA</entry>
1291 <entry>Data has been transmitted (sending)</entry>
1294 <entry>ZOOM_EVENT_RECV_DATA</entry>
1295 <entry>Data has been received)</entry>
1298 <entry>ZOOM_EVENT_TIMEOUT</entry>
1299 <entry>Timeout</entry>
1302 <entry>ZOOM_EVENT_UNKNOWN</entry>
1303 <entry>Unknown event</entry>
1306 <entry>ZOOM_EVENT_SEND_APDU</entry>
1307 <entry>An APDU has been transmitted (sending)</entry>
1310 <entry>ZOOM_EVENT_RECV_APDU</entry>
1311 <entry>An APDU has been received</entry>
1314 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1315 <entry>A result-set record has been received</entry>
1318 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1319 <entry>A search result been received</entry>
1327 <!-- Keep this comment at the end of the file
1332 sgml-minimize-attributes:nil
1333 sgml-always-quote-attributes:t
1336 sgml-parent-document: "yaz.xml"
1337 sgml-local-catalogs: nil
1338 sgml-namecase-general:t