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)
21 <!-- $Id: zoom.xml,v 1.45 2005-12-12 12:09:29 mike Exp $ -->
22 <chapter id="zoom"><title>ZOOM</title>
24 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
25 an initiative started by Mike Taylor (Mike is from the UK, which
26 explains the peculiar name of the model). The goal of &zoom; is to
27 provide a common Z39.50 client API not bound to a particular
28 programming language or toolkit.
33 A recent addition to &yaz; is SRW support. You can now make
34 SRW ZOOM connections by specifying scheme <literal>http://</literal>
35 for the hostname for a connection.
40 The lack of a simple Z39.50 client API for &yaz; has become more
41 and more apparent over time. So when the first &zoom; specification
43 an implementation for &yaz; was quickly developed. For the first time, it is
44 now as easy (or easier!) to develop clients than servers with &yaz;. This
45 chapter describes the &zoom; C binding. Before going further, please
46 reconsider whether C is the right programming language for the job.
47 There are other language bindings available for &yaz;, and still
49 are in active development. See the
50 <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
55 In order to fully understand this chapter you should read and
56 try the example programs <literal>zoomtst1.c</literal>,
57 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
62 The C language misses features found in object oriented languages
63 such as C++, Java, etc. For example, you'll have to manually,
64 destroy all objects you create, even though you may think of them as
65 temporary. Most objects has a <literal>_create</literal> - and a
66 <literal>_destroy</literal> variant.
67 All objects are in fact pointers to internal stuff, but you don't see
68 that because of typedefs. All destroy methods should gracefully ignore a
69 <literal>NULL</literal> pointer.
72 In each of the sections below you'll find a sub section called
73 protocol behavior, that describes how the API maps to the Z39.50
76 <sect1 id="zoom.connections"><title>Connections</title>
78 <para>The Connection object is a session with a target.
81 #include <yaz/zoom.h>
83 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
85 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
87 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
89 void ZOOM_connection_destroy (ZOOM_connection c);
92 Connection objects are created with either function
93 <function>ZOOM_connection_new</function> or
94 <function>ZOOM_connection_create</function>.
95 The former creates and automatically attempts to establish a network
96 connection with the target. The latter doesn't establish
97 a connection immediately, thus allowing you to specify options
98 before establishing network connection using the function
99 <function>ZOOM_connection_connect</function>.
100 If the port number, <literal>portnum</literal>, is zero, the
101 <literal>host</literal> is consulted for a port specification.
102 If no port is given, 210 is used. A colon denotes the beginning of
103 a port number in the host string. If the host string includes a
104 slash, the following part specifies a database for the connection.
107 You can prefix the host with a scheme followed by colon. The
108 default scheme is <literal>tcp</literal> (Z39.50 protocol).
109 The scheme <literal>http</literal> selects SRW over HTTP.
112 You can prefix the scheme-qualified host-string with one or more
114 <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
115 sequences, each of which represents an option to be set into the
116 connection structure <emphasis>before</emphasis> the
117 protocol-level connection is forged and the initialisation
118 handshake takes place. This facility can be used to provide
119 authentication credentials, as in host-strings such as:
120 <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
123 Connection objects should be destroyed using the function
124 <function>ZOOM_connection_destroy</function>.
127 void ZOOM_connection_option_set(ZOOM_connection c,
128 const char *key, const char *val);
130 void ZOOM_connection_option_setl(ZOOM_connection c,
132 const char *val, int len);
134 const char *ZOOM_connection_option_get(ZOOM_connection c,
136 const char *ZOOM_connection_option_getl(ZOOM_connection c,
141 The functions <function>ZOOM_connection_option_set</function> and
142 <function>ZOOM_connection_option_setl</function> allows you to
143 set an option given by <parameter>key</parameter> to the value
144 <parameter>value</parameter> for the connection.
145 For <function>ZOOM_connection_option_set</function>, the
146 value is assumed to be a 0-terminated string. Function
147 <function>ZOOM_connection_option_setl</function> specifies a
148 value of a certain size (len).
151 Functions <function>ZOOM_connection_option_get</function> and
152 <function>ZOOM_connection_option_getl</function> returns
153 the value for an option given by <parameter>key</parameter>.
155 <table frame="top"><title>ZOOM Connection Options</title>
157 <colspec colwidth="4*" colname="name"></colspec>
158 <colspec colwidth="7*" colname="description"></colspec>
159 <colspec colwidth="3*" colname="default"></colspec>
162 <entry>Option</entry>
163 <entry>Description</entry>
164 <entry>Default</entry>
169 implementationName</entry><entry>Name of Your client
170 </entry><entry>none</entry></row>
172 user</entry><entry>Authentication user name
173 </entry><entry>none</entry></row>
175 group</entry><entry>Authentication group name
176 </entry><entry>none</entry></row>
178 password</entry><entry>Authentication password.
179 </entry><entry>none</entry></row>
181 host</entry><entry>Target host. This setting is "read-only".
182 It's automatically set internally when connecting to a target.
183 </entry><entry>none</entry></row>
185 proxy</entry><entry>Proxy host
186 </entry><entry>none</entry></row>
188 async</entry><entry>If true (1) the connection operates in
189 asynchronous operation which means that all calls are non-blocking
191 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
192 </entry><entry>0</entry></row>
194 maximumRecordSize</entry><entry> Maximum size of single record.
195 </entry><entry>1 MB</entry></row>
197 preferredMessageSize</entry><entry> Maximum size of multiple records.
198 </entry><entry>1 MB</entry></row>
200 lang</entry><entry> Language for negotiation.
201 </entry><entry>none</entry></row>
203 charset</entry><entry> Character set for negotiation.
204 </entry><entry>none</entry></row>
206 serverImplementationId</entry><entry>
207 Implementation ID of server. (The old targetImplementationId
208 option is also supported for the benefit of old applications.)
209 </entry><entry>none</entry></row>
211 targetImplementationName</entry><entry>
212 Implementation Name of server. (The old
213 targetImplementationName option is also supported for the
214 benefit of old applications.)
215 </entry><entry>none</entry></row>
217 serverImplementationVersion</entry><entry>
218 Implementation Version of server. (the old
219 targetImplementationVersion option is also supported for the
220 benefit of old applications.)
221 </entry><entry>none</entry></row>
223 databaseName</entry><entry>One or more database names
224 separated by character plus (<literal>+</literal>), which to
225 be used by subsequent search requests on this Connection.
226 </entry><entry>Default</entry></row>
228 piggyback</entry><entry>True (1) if piggyback should be
229 used in searches; false (0) if not.
230 </entry><entry>1</entry></row>
232 smallSetUpperBound</entry><entry>If hits is less than or equal to this
233 value, then target will return all records using small element set name
234 </entry><entry>0</entry></row>
236 largeSetLowerBound</entry><entry>If hits is greater than this
237 value, the target will return no records.
238 </entry><entry>1</entry></row>
240 mediumSetPresentNumber</entry><entry>This value represents
241 the number of records to be returned as part of a search when when
242 hits is less than or equal to large set lower bound and if hits
243 is greater than small set upper bound.
244 </entry><entry>0</entry></row>
246 smallSetElementSetName</entry><entry>
247 The element set name to be used for small result sets.
248 </entry><entry>none</entry></row>
250 mediumSetElementSetName</entry><entry>
251 The element set name to be for medium-sized result sets.
252 </entry><entry>none</entry></row>
257 If either option <literal>lang</literal> or <literal>charset</literal>
259 <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
260 Character Set and Language Negotiation</ulink> is in effect.
263 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
264 const char **addinfo);
265 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
266 const char **addinfo, const char **dset);
269 Function <function>ZOOM_connection_error</function> checks for
270 errors for the last operation(s) performed. The function returns
271 zero if no errors occurred; non-zero otherwise indicating the error.
272 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
273 holds messages for the error and additional-info if passed as
274 non-<literal>NULL</literal>. Function
275 <function>ZOOM_connection_error_x</function> is an extended version
276 of <function>ZOOM_connection_error</function> that is capable of
277 returning name of diagnostic set in <parameter>dset</parameter>.
279 <sect2><title>Z39.50 Protocol behavior</title>
281 The calls <function>ZOOM_connection_new</function> and
282 <function>ZOOM_connection_connect</function> establishes a TCP/IP
283 connection and sends an Initialize Request to the target if
284 possible. In addition, the calls waits for an Initialize Response
285 from the target and the result is inspected (OK or rejected).
288 If <literal>proxy</literal> is set then the client will establish
289 a TCP/IP connection with the peer as specified by the
290 <literal>proxy</literal> host and the hostname as part of the
291 connect calls will be set as part of the Initialize Request.
292 The proxy server will then "forward" the PDU's transparently
293 to the target behind the proxy.
296 For the authentication parameters, if option <literal>user</literal>
297 is set and both options <literal>group</literal> and
298 <literal>pass</literal> are unset, then Open style
299 authentication is used (Version 2/3) in which case the username
300 is usually followed by a slash, then by a password.
301 If either <literal>group</literal>
302 or <literal>pass</literal> is set then idPass authentication
303 (Version 3 only) is used. If none of the options are set, no
304 authentication parameters are set as part of the Initialize Request
308 When option <literal>async</literal> is 1, it really means that
309 all network operations are postponed (and queued) until the
310 function <literal>ZOOM_event</literal> is invoked. When doing so
311 it doesn't make sense to check for errors after
312 <literal>ZOOM_connection_new</literal> is called since that
313 operation "connecting - and init" is still incomplete and the
314 API cannot tell the outcome (yet).
317 <sect2><title>SRW Protocol behavior</title>
319 The SRW protocol doesn't feature an Inititialize Request, so
320 the connection phase merely establishes a TCP/IP connection
321 with the SOAP service.
323 <para>Most of the ZOOM connection options do not
324 affect SRW and they are ignored. However, future versions
325 of &yaz; might honor <literal>implementationName</literal> and
326 put that as part of User-Agent header for HTTP requests.
329 The <literal>charset</literal> is used in the Content-Type header
334 <sect1 id="zoom.query"><title>Queries</title>
336 Query objects represents queries.
339 ZOOM_query ZOOM_query_create(void);
341 void ZOOM_query_destroy(ZOOM_query q);
343 int ZOOM_query_prefix(ZOOM_query q, const char *str);
345 int ZOOM_query_cql(ZOOM_query s, const char *str);
347 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
350 Create query objects using <function>ZOOM_query_create</function>
351 and destroy them by calling <function>ZOOM_query_destroy</function>.
352 RPN-queries can be specified in <link linkend="PQF">PQF</link>
353 notation by using the
354 function <function>ZOOM_query_prefix</function>.
355 The <function>ZOOM_query_cql</function> specifies a CQL
356 query to be sent to the server/target.
357 More query types will be added in future versions of &yaz;, such as
358 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
359 etc. In addition to a search, a sort criteria may be set. Function
360 <function>ZOOM_query_sortby</function> specifies a
361 sort criteria using the same string notation for sort as offered by
362 the <link linkend="sortspec">YAZ client</link>.
364 <sect2><title>Protocol behavior</title>
366 The query object is just an interface for the member Query
367 in the SearchRequest. The sortby-function is an interface to the
368 sortSequence member of the SortRequest.
372 <sect1 id="zoom.resultsets"><title>Result sets</title>
374 The result set object is a container for records returned from
378 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
381 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
384 void ZOOM_resultset_destroy(ZOOM_resultset r);
387 Function <function>ZOOM_connection_search</function> creates
388 a result set given a connection and query.
389 Destroy a result set by calling
390 <function>ZOOM_resultset_destroy</function>.
391 Simple clients may using PQF only may use function
392 <function>ZOOM_connection_search_pqf</function> in which case
393 creating query objects is not necessary.
396 void ZOOM_resultset_option_set (ZOOM_resultset r,
400 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
403 size_t ZOOM_resultset_size (ZOOM_resultset r);
406 Functions <function>ZOOM_resultset_options_set</function> and
407 <function>ZOOM_resultset_get</function> sets and gets an option
408 for a result set similar to <function>ZOOM_connection_option_get</function>
409 and <function>ZOOM_connection_option_set</function>.
412 The number of hits also called result-count is returned by
413 function <function>ZOOM_resultset_size</function>.
415 <table frame="top"><title>ZOOM Result set Options</title>
417 <colspec colwidth="4*" colname="name"></colspec>
418 <colspec colwidth="7*" colname="description"></colspec>
419 <colspec colwidth="2*" colname="default"></colspec>
422 <entry>Option</entry>
423 <entry>Description</entry>
424 <entry>Default</entry>
429 start</entry><entry>Offset of first record to be
430 retrieved from target. First record has offset 0 unlike the
431 protocol specifications where first record has position 1.
432 </entry><entry>0</entry></row>
434 count</entry><entry>Number of records to be retrieved.
435 </entry><entry>0</entry></row>
437 presentChunk</entry><entry>The number of records to be
438 requested from the server in each chunk (present requst). The
439 value 0 means to request all the records in a single chunk.
440 (The old <literal>step</literal>
441 option is also supported for the benefit of old applications.)
442 </entry><entry>0</entry></row>
444 elementSetName</entry><entry>Element-Set name of records.
445 Most targets should honor element set name <literal>B</literal>
446 and <literal>F</literal> for brief and full respectively.
447 </entry><entry>none</entry></row>
449 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
450 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
451 </entry><entry>none</entry></row>
453 schema</entry><entry>Schema for retrieval, such as
454 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
455 </entry><entry>none</entry></row>
457 setname</entry><entry>Name of Result Set (Result Set ID).
458 If this option isn't set, the ZOOM module will automatically
459 allocate a result set name.
460 </entry><entry>default</entry></row>
465 For servers that support Search Info report, the following
466 options may be read using <function>ZOOM_resultset_get</function>.
467 This detailed information is read after a successful search has
471 This information is a list of of items, where each item is
472 information about a term or subquery. All items in the list
474 <literal>SearchResult.</literal><replaceable>no</replaceable>
475 where no presents the item number (0=first, 1=second).
476 Read <literal>searchresult.size</literal> to determine the
479 <table frame="top"><title>Search Info Report options</title>
481 <colspec colwidth="4*" colname="name"></colspec>
482 <colspec colwidth="7*" colname="description"></colspec>
485 <entry>Option</entry>
486 <entry>Description</entry>
491 <entry>searchresult.size</entry>
493 number of search result entries. This option is-nonexistant
494 if no entries are returned by the server.
498 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
499 <entry>sub query ID</entry>
502 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
503 <entry>result count for item (number of hits)</entry>
506 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
507 <entry>subquery term</entry>
511 searchresult.<replaceable>no</replaceable>.interpretation.term
513 <entry>interpretation term</entry>
517 searchresult.<replaceable>no</replaceable>.recommendation.term
519 <entry>recommendation term</entry>
525 <title>Z39.50 Protocol behavior</title>
527 The creation of a result set involves at least a SearchRequest
528 - SearchResponse protocol handshake. Following that, if a sort
529 criteria was specified as part of the query, a SortRequest -
530 SortResponse handshake takes place. Note that it is necessary to
531 perform sorting before any retrieval takes place, so no records will
532 be returned from the target as part of the SearchResponse because these
533 would be unsorted. Hence, piggyback is disabled when sort criteria
534 are set. Following Search - and a possible sort - Retrieval takes
535 place - as one or more Present Requests/Response pairs being
539 The API allows for two different modes for retrieval. A high level
540 mode which is somewhat more powerful and a low level one.
541 The low level is enabled when searching on a Connection object
542 for which the settings
543 <literal>smallSetUpperBound</literal>,
544 <literal>mediumSetPresentNumber</literal> and
545 <literal>largeSetLowerBound</literal> are set. The low level mode
546 thus allows you to precisely set how records are returned as part
547 of a search response as offered by the Z39.50 protocol.
548 Since the client may be retrieving records as part of the
549 search response, this mode doesn't work well if sorting is used.
552 The high-level mode allows you to fetch a range of records from
553 the result set with a given start offset. When you use this mode
554 the client will automatically use piggyback if that is possible
555 with the target and perform one or more present requests as needed.
556 Even if the target returns fewer records as part of a present response
557 because of a record size limit, etc. the client will repeat sending
558 present requests. As an example, if option <literal>start</literal>
559 is 0 (default) and <literal>count</literal> is 4, and
560 <literal>piggyback</literal> is 1 (default) and no sorting criteria
561 is specified, then the client will attempt to retrieve the 4
562 records as part the search response (using piggyback). On the other
563 hand, if either <literal>start</literal> is positive or if
564 a sorting criteria is set, or if <literal>piggyback</literal>
565 is 0, then the client will not perform piggyback but send Present
569 If either of the options <literal>mediumSetElementSetName</literal> and
570 <literal>smallSetElementSetName</literal> are unset, the value
571 of option <literal>elementSetName</literal> is used for piggyback
572 searches. This means that for the high-level mode you only have
573 to specify one elementSetName option rather than three.
577 <title>SRW Protocol behavior</title>
579 Current version of &yaz; does not take advantage of a result set id
580 returned by the SRW server. Future versions might do, however.
581 Since, the ZOOM driver does not save result set IDs any
582 present (retrieval) is transformed to a SRW SearchRetrieveRequest
583 with same query but, possibly, different offsets.
586 Option <literal>schema</literal> specifies SRW schema
587 for retrieval. However, options <literal>elementSetName</literal> and
588 <literal>preferredRecordSyntax</literal> are ignored.
591 Options <literal>start</literal> and <literal>count</literal>
592 are supported by SRW.
593 The remaining options
594 <literal>piggyback</literal>,
595 <literal>smallSetUpperBound</literal>,
596 <literal>largeSetLowerBound</literal>,
597 <literal>mediumSetPresentNumber</literal>,
598 <literal>mediumSetElementSetName</literal>,
599 <literal>smallSetElementSetName</literal> are
603 SRW supports CQL queries, <emphasis>not</emphasis> PQF.
604 If PQF is used, however, the PQF query is transferred anyway
605 using non-standard element <literal>pQuery</literal> in
606 SRW SearchRetrieveRequest.
609 Unfortunately, SRW does not define a database setting. Hence,
610 <literal>databaseName</literal> is unsupported and ignored.
611 However, the path part in host parameter for functions
612 <function>ZOOM_connecton_new</function> and
613 <function>ZOOM_connection_connect</function> acts as a
614 database (at least for the &yaz; SRW server).
618 <sect1 id="zoom.records"><title>Records</title>
620 A record object is a retrieval record on the client side -
621 created from result sets.
624 void ZOOM_resultset_records (ZOOM_resultset r,
626 size_t start, size_t count);
627 ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
629 const char *ZOOM_record_get (ZOOM_record rec, const char *type,
632 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
634 void ZOOM_record_destroy (ZOOM_record rec);
637 References to temporary records are returned by functions
638 <function>ZOOM_resultset_records</function> or
639 <function>ZOOM_resultset_record</function>.
642 If a persistent reference to a record is desired
643 <function>ZOOM_record_clone</function> should be used.
644 It returns a record reference that should be destroyed
645 by a call to <function>ZOOM_record_destroy</function>.
648 A single record is returned by function
649 <function>ZOOM_resultset_record</function> that takes a
650 position as argument. First record has position zero.
651 If no record could be obtained <literal>NULL</literal> is returned.
654 Function <function>ZOOM_resultset_records</function> retrieves
655 a number of records from a result set. Parameter <literal>start</literal>
656 and <literal>count</literal> specifies the range of records to
657 be returned. Upon completion array
658 <literal>recs[0], ..recs[count-1]</literal>
659 holds record objects for the records. The array of records
660 <literal>recs</literal> should be allocated prior the call
661 <function>ZOOM_resultset_records</function>. Note that for those
662 records that couldn't be retrieved from the target
663 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
665 <para id="zoom.record.get">
666 In order to extract information about a single record,
667 <function>ZOOM_record_get</function> is provided. The
668 function returns a pointer to certain record information. The
669 nature (type) of the pointer depends on the parameter,
670 <parameter>type</parameter>.
673 The <parameter>type</parameter> is a string of the format:
676 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
679 where <replaceable>form</replaceable> specifies the format of the
680 returned record, <replaceable>from</replaceable>
681 specifies the character set of the record in its original form
682 (as returned by the server), <replaceable>to</replaceable> specifies
683 the output (returned)
684 character set encoding.
685 If charset is not given, then no character set conversion takes place.
686 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
689 In addition, for certain types, the length
690 <literal>len</literal> passed will be set to the size in bytes of
691 the returned information.
694 The following are the supported values for <replaceable>form</replaceable>.
696 <varlistentry><term><literal>database</literal></term>
697 <listitem><para>Database of record is returned
698 as a C null-terminated string. Return type
699 <literal>const char *</literal>.
702 <varlistentry><term><literal>syntax</literal></term>
703 <listitem><para>The transfer syntax of the record is returned
704 as a C null-terminated string containing the symbolic name of
705 the record syntax, e.g. <literal>Usmarc</literal>. Return type
707 <literal>const char *</literal>.
710 <varlistentry><term><literal>render</literal></term>
711 <listitem><para>The record is returned in a display friendly
712 format. Upon completion buffer is returned
713 (type <literal>const char *</literal>) and length is stored in
714 <literal>*len</literal>.
717 <varlistentry><term><literal>raw</literal></term>
718 <listitem><para>The record is returned in the internal
719 YAZ specific format. For GRS-1, Explain, and others, the
720 raw data is returned as type
721 <literal>Z_External *</literal> which is just the type for
722 the member <literal>retrievalRecord</literal> in
723 type <literal>NamePlusRecord</literal>.
724 For SUTRS and octet aligned record (including all MARCs) the
725 octet buffer is returned and the length of the buffer.
728 <varlistentry><term><literal>xml</literal></term>
729 <listitem><para>The record is returned in XML if possible.
730 SRW/SRU and Z39.50 records with transfer syntax XML are
731 returned verbatim. MARC records are returned in
732 <ulink url="http://www.loc.gov/standards/marcxml/">
735 (converted from ISO2709 to MARCXML by YAZ).
736 GRS-1 and OPAC records are not supported for this form.
737 Upon completion, the XML buffer is returned
738 (type <literal>const char *</literal>) and length is stored in
739 <literal>*len</literal>.
742 <varlistentry><term><literal>opac</literal></term>
743 <listitem><para>OPAC for record is returned in XML.
750 <ulink url="http://www.loc.gov/marc/">
754 <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
757 character set encoding.
758 An application that wishes to display in Latin-1 would use
760 render; charset=marc8,iso-8859-1
763 <sect2><title>Z39.50 Protocol behavior</title>
765 The functions <function>ZOOM_resultset_record</function> and
766 <function>ZOOM_resultset_records</function> inspects the client-side
767 record cache. Records not found in cache are fetched using
769 The functions may block (and perform network I/O) - even though option
770 <literal>async</literal> is 1, because they return records objects.
771 (and there's no way to return records objects without retrieving them!).
774 There is a trick, however, in the usage of function
775 <function>ZOOM_resultset_records</function> that allows for
776 delayed retrieval (and makes it non-blocking). By using
777 a null pointer for <parameter>recs</parameter> you're indicating
778 you're not interested in getting records objects
779 <emphasis>now</emphasis>.
782 <sect2><title>SRW Protocol behavior</title>
784 The ZOOM driver for SRW treats records returned by a SRW server
785 as if they where Z39.50 records with transfer syntax XML and
786 no element set name or database name.
790 <sect1 id="zoom.scan"><title>Scan</title>
792 This section describes an interface for Scan. Scan is not an
793 official part of the ZOOM model yet. The result of a scan operation
794 is the <literal>ZOOM_scanset</literal> which is a set of terms
795 returned by a target.
799 The Scan interface is Z39.50 only. SRW version 1.0 does not
804 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
805 const char *startpqf);
807 size_t ZOOM_scanset_size(ZOOM_scanset scan);
809 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
810 int *occ, size_t *len);
812 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
813 int *occ, size_t *len);
815 void ZOOM_scanset_destroy (ZOOM_scanset scan);
817 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
820 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
824 The scan set is created by function
825 <function>ZOOM_connection_scan</function> which performs a scan
826 operation on the connection using the specified
827 <parameter>startpqf</parameter>.
828 If the operation was successful, the size of the scan set can be
829 retrieved by a call to <function>ZOOM_scanset_size</function>.
830 Like result sets, the items are numbered 0,..size-1.
831 To obtain information about a particular scan term, call function
832 <function>ZOOM_scanset_term</function>. This function takes
833 a scan set offset <literal>pos</literal> and returns a pointer
834 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
836 If present, the <literal>occ</literal> and <literal>len</literal>
837 are set to the number of occurrences and the length
838 of the actual term respectively.
839 <function>ZOOM_scanset_display_term</function> is similar to
840 <function>ZOOM_scanset_term</function> except that it returns
841 the <emphasis>display term</emphasis> rather than the raw term.
842 In a few cases, the term is different from display term. Always
843 use the display term for display and the raw term for subsequent
844 scan operations (to get more terms, next scan result, etc).
847 A scan set may be freed by a call to function
848 <function>ZOOM_scanset_destroy</function>.
849 Functions <function>ZOOM_scanset_option_get</function> and
850 <function>ZOOM_scanset_option_set</function> retrieves and sets
851 an option respectively.
855 The <parameter>startpqf</parameter> is a subset of PQF, namely
856 the Attributes+Term part. Multiple <literal>@attr</literal> can
857 be used. For example to scan in title (complete) phrases:
859 @attr 1=4 @attr 6=2 "science o"
863 <table frame="top"><title>ZOOM Scan Set Options</title>
865 <colspec colwidth="4*" colname="name"></colspec>
866 <colspec colwidth="7*" colname="description"></colspec>
867 <colspec colwidth="2*" colname="default"></colspec>
870 <entry>Option</entry>
871 <entry>Description</entry>
872 <entry>Default</entry>
877 number</entry><entry>Number of Scan Terms requested in next scan.
878 After scan it holds the actual number of terms returned.
879 </entry><entry>10</entry></row>
881 position</entry><entry>Preferred Position of term in response
882 in next scan; actual position after completion of scan.
883 </entry><entry>1</entry></row>
885 stepSize</entry><entry>Step Size
886 </entry><entry>0</entry></row>
888 scanStatus</entry><entry>An integer indicating the Scan Status
890 </entry><entry>0</entry></row>
896 <sect1 id="zoom.ext"><title>Extended Services</title>
898 ZOOM offers an interface to a subset of the Z39.50 extended services
899 as well as a few privately defined ones:
904 Z39.50 Item Order (ILL).
905 See <xref linkend="zoom.ext.itemorder"/>.
910 Record Update. This allows a client to insert, modify or delete
912 See <xref linkend="zoom.ext.update"/>.
917 Database Create. This a non-standard feature. Allows a client
918 to create a database.
919 See <xref linkend="zoom.ext.dbcreate"/>.
924 Database Drop. This a non-standard feature. Allows a client
925 to delete/drop a database.
926 See <xref linkend="zoom.ext.dbdrop"/>.
931 Commit operation. This a non-standard feature. Allows a client
932 to commit operations.
933 See <xref linkend="zoom.ext.commit"/>.
936 <!-- all the ILL PDU options should go here too -->
939 To create an extended service operation a <literal>ZOOM_package</literal>
940 must be created. The operation is a five step operation. The
941 package is created, package is configured by means of options,
942 the package is send, result is inspected (by means of options),
943 the package is destroyed.
946 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
947 ZOOM_options options);
949 const char *ZOOM_package_option_get(ZOOM_package p,
951 void ZOOM_package_option_set(ZOOM_package p, const char *key,
953 void ZOOM_package_send(ZOOM_package p, const char *type);
955 void ZOOM_package_destroy(ZOOM_package p);
958 The <function>ZOOM_connection_package</function> creates a
959 package for the connection given using the options specified.
962 Functions <function>ZOOM_package_option_get</function> and
963 <function>ZOOM_package_option_set</function> gets and sets
967 <function>ZOOM_package_send</function> sends
968 the package the via connection specified in
969 <function>ZOOM_connection_package</function>.
970 The <parameter>type</parameter> specifies the actual extended service
971 package type to be sent.
974 <table frame="top"><title>Extended Service Common Options</title>
976 <colspec colwidth="4*" colname="name"></colspec>
977 <colspec colwidth="7*" colname="description"></colspec>
978 <colspec colwidth="3*" colname="default"></colspec>
981 <entry>Option</entry>
982 <entry>Description</entry>
983 <entry>Default</entry>
988 <entry>package-name</entry>
989 <entry>Extended Service Request package name. Must be specified
990 as part of a request</entry>
994 <entry>user-id</entry>
995 <entry>User ID of Extended Service Package. Is a request option</entry>
999 <entry>function</entry>
1001 Function of package - one of <literal>create</literal>,
1002 <literal>delete</literal>, <literal>modify</literal>. Is
1005 <entry><literal>create</literal></entry>
1008 <entry>targetReference</entry>
1010 Target Reference. This is part of the response as returned
1011 by the server. Read it after a succesful operation.
1013 <entry><literal>none</literal></entry>
1019 <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
1021 For Item Order, type must be set to <literal>itemorder</literal> in
1022 <function>ZOOM_package_send</function>.
1025 <table frame="top"><title>Item Order Options</title>
1027 <colspec colwidth="4*" colname="name"></colspec>
1028 <colspec colwidth="7*" colname="description"></colspec>
1029 <colspec colwidth="3*" colname="default"></colspec>
1032 <entry>Option</entry>
1033 <entry>Description</entry>
1034 <entry>Default</entry>
1039 <entry>contact-name</entry>
1040 <entry>ILL contact name</entry>
1044 <entry>contact-phone</entry>
1045 <entry>ILL contact phone</entry>
1049 <entry>contact-email</entry>
1050 <entry>ILL contact email</entry>
1054 <entry>itemorder-item</entry>
1055 <entry>Position for item (record) requested. An integer</entry>
1064 <sect2 id="zoom.ext.update"><title>Record Update</title>
1066 For Record Update, type must be set to <literal>update</literal> in
1067 <function>ZOOM_package_send</function>.
1070 <table frame="top"><title>Record Update Options</title>
1072 <colspec colwidth="4*" colname="name"></colspec>
1073 <colspec colwidth="7*" colname="description"></colspec>
1074 <colspec colwidth="3*" colname="default"></colspec>
1077 <entry>Option</entry>
1078 <entry>Description</entry>
1079 <entry>Default</entry>
1084 <entry>action</entry>
1086 The update action. One of
1087 <literal>specialUpdate</literal>,
1088 <literal>recordInsert</literal>,
1089 <literal>recordReplace</literal>,
1090 <literal>recordDelete</literal>,
1091 <literal>elementUpdate</literal>.
1093 <entry><literal>specialUpdate</literal></entry>
1096 <entry>recordIdOpaque</entry>
1097 <entry>Opaque Record ID</entry>
1101 <entry>recordIdNumber</entry>
1102 <entry>Record ID number</entry>
1106 <entry>record</entry>
1107 <entry>The record itself</entry>
1111 <entry>syntax</entry>
1112 <entry>The record syntax (transfer syntax). Is a string that
1113 is a known record syntax.
1115 <entry>no syntax</entry>
1118 <entry>databaseName</entry>
1119 <entry>Database from connection object</entry>
1120 <entry>Default</entry>
1128 <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
1130 For Database Create, type must be set to <literal>create</literal> in
1131 <function>ZOOM_package_send</function>.
1134 <table frame="top"><title>Database Create Options</title>
1136 <colspec colwidth="4*" colname="name"></colspec>
1137 <colspec colwidth="7*" colname="description"></colspec>
1138 <colspec colwidth="3*" colname="default"></colspec>
1141 <entry>Option</entry>
1142 <entry>Description</entry>
1143 <entry>Default</entry>
1148 <entry>databaseName</entry>
1149 <entry>Database from connection object</entry>
1150 <entry>Default</entry>
1157 <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
1159 For Database Drop, type must be set to <literal>drop</literal> in
1160 <function>ZOOM_package_send</function>.
1163 <table frame="top"><title>Database Create Options</title>
1165 <colspec colwidth="4*" colname="name"></colspec>
1166 <colspec colwidth="7*" colname="description"></colspec>
1167 <colspec colwidth="3*" colname="default"></colspec>
1170 <entry>Option</entry>
1171 <entry>Description</entry>
1172 <entry>Default</entry>
1177 <entry>databaseName</entry>
1178 <entry>Database from connection object</entry>
1179 <entry>Default</entry>
1186 <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
1188 For Commit, type must be set to <literal>commit</literal> in
1189 <function>ZOOM_package_send</function>.
1193 <sect2><title>Protocol behavior</title>
1195 All the extended services are Z39.50-only.
1199 The database create, drop and commit services are privately defined
1201 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1208 <sect1 id="zoom.options"><title>Options</title>
1210 Most &zoom; objects provide a way to specify options to change behavior.
1211 From an implementation point of view a set of options is just like
1212 an associative array / hash.
1215 ZOOM_options ZOOM_options_create (void);
1217 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1219 void ZOOM_options_destroy (ZOOM_options opt);
1222 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1224 void ZOOM_options_set (ZOOM_options opt, const char *name,
1228 typedef const char *(*ZOOM_options_callback)
1229 (void *handle, const char *name);
1231 ZOOM_options_callback
1232 ZOOM_options_set_callback (ZOOM_options opt,
1233 ZOOM_options_callback c,
1237 <sect1 id="zoom.events"><title>Events</title>
1239 If you're developing non-blocking applications, you have to deal
1243 int ZOOM_event (int no, ZOOM_connection *cs);
1246 The <function>ZOOM_event</function> executes pending events for
1247 a number of connections. Supply the number of connections in
1248 <literal>no</literal> and an array of connections in
1249 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1250 A pending event could be a sending a search, receiving a response,
1252 When an event has occurred for one of the connections, this function
1253 returns a positive integer <literal>n</literal> denoting that an event
1254 occurred for connection <literal>cs[n-1]</literal>.
1255 When no events are pending for the connections, a value of zero is
1257 To ensure that all outstanding requests are performed call this function
1258 repeatedly until zero is returned.
1261 If <function>ZOOM_event</function> returns and returns non-zero, the
1262 last event that occurred can be expected.
1265 int ZOOM_connection_last_event(ZOOM_connection cs);
1268 <function>ZOOM_connection_last_event</function> returns an event type
1269 (integer) for the last event.
1272 <table frame="top"><title>ZOOM Event IDs</title>
1274 <colspec colwidth="4*" colname="name"></colspec>
1275 <colspec colwidth="7*" colname="description"></colspec>
1278 <entry>Event</entry>
1279 <entry>Description</entry>
1284 <entry>ZOOM_EVENT_NONE</entry>
1285 <entry>No event has occurred</entry>
1288 <entry>ZOOM_EVENT_CONNECT</entry>
1289 <entry>TCP/IP connect has initiated</entry>
1292 <entry>ZOOM_EVENT_SEND_DATA</entry>
1293 <entry>Data has been transmitted (sending)</entry>
1296 <entry>ZOOM_EVENT_RECV_DATA</entry>
1297 <entry>Data has been received)</entry>
1300 <entry>ZOOM_EVENT_TIMEOUT</entry>
1301 <entry>Timeout</entry>
1304 <entry>ZOOM_EVENT_UNKNOWN</entry>
1305 <entry>Unknown event</entry>
1308 <entry>ZOOM_EVENT_SEND_APDU</entry>
1309 <entry>An APDU has been transmitted (sending)</entry>
1312 <entry>ZOOM_EVENT_RECV_APDU</entry>
1313 <entry>An APDU has been received</entry>
1316 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1317 <entry>A result-set record has been received</entry>
1320 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1321 <entry>A search result been received</entry>
1329 <!-- Keep this comment at the end of the file
1334 sgml-minimize-attributes:nil
1335 sgml-always-quote-attributes:t
1338 sgml-parent-document: "yaz.xml"
1339 sgml-local-catalogs: nil
1340 sgml-namecase-general:t