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.56 2007-04-30 08:29:07 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. The dialect of SRU used is
38 specified by the value of the connection's <literal>sru</literal>
39 option, which may be SRU over HTTP GET (<literal>get</literal>),
40 SRU over HTTP POST (<literal>post</literal>) or SRW (SRU over
41 SOAP) (<literal>soap</literal>).
46 The lack of a simple Z39.50 client API for &yaz; has become more
47 and more apparent over time. So when the first &zoom; specification
49 an implementation for &yaz; was quickly developed. For the first time, it is
50 now as easy (or easier!) to develop clients than servers with &yaz;. This
51 chapter describes the &zoom; C binding. Before going further, please
52 reconsider whether C is the right programming language for the job.
53 There are other language bindings available for &yaz;, and still
55 are in active development. See the
56 <ulink url="&url.zoom;">ZOOM web-site</ulink> for
61 In order to fully understand this chapter you should read and
62 try the example programs <literal>zoomtst1.c</literal>,
63 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
68 The C language misses features found in object oriented languages
69 such as C++, Java, etc. For example, you'll have to manually,
70 destroy all objects you create, even though you may think of them as
71 temporary. Most objects has a <literal>_create</literal> - and a
72 <literal>_destroy</literal> variant.
73 All objects are in fact pointers to internal stuff, but you don't see
74 that because of typedefs. All destroy methods should gracefully ignore a
75 <literal>NULL</literal> pointer.
78 In each of the sections below you'll find a sub section called
79 protocol behavior, that describes how the API maps to the Z39.50
82 <sect1 id="zoom-connections"><title>Connections</title>
84 <para>The Connection object is a session with a target.
87 #include <yaz/zoom.h>
89 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
91 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
93 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
95 void ZOOM_connection_destroy (ZOOM_connection c);
98 Connection objects are created with either function
99 <function>ZOOM_connection_new</function> or
100 <function>ZOOM_connection_create</function>.
101 The former creates and automatically attempts to establish a network
102 connection with the target. The latter doesn't establish
103 a connection immediately, thus allowing you to specify options
104 before establishing network connection using the function
105 <function>ZOOM_connection_connect</function>.
106 If the port number, <literal>portnum</literal>, is zero, the
107 <literal>host</literal> is consulted for a port specification.
108 If no port is given, 210 is used. A colon denotes the beginning of
109 a port number in the host string. If the host string includes a
110 slash, the following part specifies a database for the connection.
113 You can prefix the host with a scheme followed by colon. The
114 default scheme is <literal>tcp</literal> (Z39.50 protocol).
115 The scheme <literal>http</literal> selects SRU over HTTP.
118 You can prefix the scheme-qualified host-string with one or more
120 <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
121 sequences, each of which represents an option to be set into the
122 connection structure <emphasis>before</emphasis> the
123 protocol-level connection is forged and the initialisation
124 handshake takes place. This facility can be used to provide
125 authentication credentials, as in host-strings such as:
126 <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
129 Connection objects should be destroyed using the function
130 <function>ZOOM_connection_destroy</function>.
133 void ZOOM_connection_option_set(ZOOM_connection c,
134 const char *key, const char *val);
136 void ZOOM_connection_option_setl(ZOOM_connection c,
138 const char *val, int len);
140 const char *ZOOM_connection_option_get(ZOOM_connection c,
142 const char *ZOOM_connection_option_getl(ZOOM_connection c,
147 The functions <function>ZOOM_connection_option_set</function> and
148 <function>ZOOM_connection_option_setl</function> allows you to
149 set an option given by <parameter>key</parameter> to the value
150 <parameter>value</parameter> for the connection.
151 For <function>ZOOM_connection_option_set</function>, the
152 value is assumed to be a 0-terminated string. Function
153 <function>ZOOM_connection_option_setl</function> specifies a
154 value of a certain size (len).
157 Functions <function>ZOOM_connection_option_get</function> and
158 <function>ZOOM_connection_option_getl</function> returns
159 the value for an option given by <parameter>key</parameter>.
161 <table id="zoom-connection-options" frame="top">
162 <title>ZOOM Connection Options</title>
164 <colspec colwidth="4*" colname="name"></colspec>
165 <colspec colwidth="7*" colname="description"></colspec>
166 <colspec colwidth="3*" colname="default"></colspec>
169 <entry>Option</entry>
170 <entry>Description</entry>
171 <entry>Default</entry>
176 implementationName</entry><entry>Name of Your client
177 </entry><entry>none</entry></row>
179 user</entry><entry>Authentication user name
180 </entry><entry>none</entry></row>
182 group</entry><entry>Authentication group name
183 </entry><entry>none</entry></row>
185 password</entry><entry>Authentication password.
186 </entry><entry>none</entry></row>
188 host</entry><entry>Target host. This setting is "read-only".
189 It's automatically set internally when connecting to a target.
190 </entry><entry>none</entry></row>
192 proxy</entry><entry>Proxy host
193 </entry><entry>none</entry></row>
195 async</entry><entry>If true (1) the connection operates in
196 asynchronous operation which means that all calls are non-blocking
198 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
199 </entry><entry>0</entry></row>
201 maximumRecordSize</entry><entry> Maximum size of single record.
202 </entry><entry>1 MB</entry></row>
204 preferredMessageSize</entry><entry> Maximum size of multiple records.
205 </entry><entry>1 MB</entry></row>
207 lang</entry><entry> Language for negotiation.
208 </entry><entry>none</entry></row>
210 charset</entry><entry> Character set for negotiation.
211 </entry><entry>none</entry></row>
213 serverImplementationId</entry><entry>
214 Implementation ID of server. (The old targetImplementationId
215 option is also supported for the benefit of old applications.)
216 </entry><entry>none</entry></row>
218 targetImplementationName</entry><entry>
219 Implementation Name of server. (The old
220 targetImplementationName option is also supported for the
221 benefit of old applications.)
222 </entry><entry>none</entry></row>
224 serverImplementationVersion</entry><entry>
225 Implementation Version of server. (the old
226 targetImplementationVersion option is also supported for the
227 benefit of old applications.)
228 </entry><entry>none</entry></row>
230 databaseName</entry><entry>One or more database names
231 separated by character plus (<literal>+</literal>), which to
232 be used by subsequent search requests on this Connection.
233 </entry><entry>Default</entry></row>
235 piggyback</entry><entry>True (1) if piggyback should be
236 used in searches; false (0) if not.
237 </entry><entry>1</entry></row>
239 smallSetUpperBound</entry><entry>If hits is less than or equal to this
240 value, then target will return all records using small element set name
241 </entry><entry>0</entry></row>
243 largeSetLowerBound</entry><entry>If hits is greater than this
244 value, the target will return no records.
245 </entry><entry>1</entry></row>
247 mediumSetPresentNumber</entry><entry>This value represents
248 the number of records to be returned as part of a search when when
249 hits is less than or equal to large set lower bound and if hits
250 is greater than small set upper bound.
251 </entry><entry>0</entry></row>
253 smallSetElementSetName</entry><entry>
254 The element set name to be used for small result sets.
255 </entry><entry>none</entry></row>
257 mediumSetElementSetName</entry><entry>
258 The element set name to be for medium-sized result sets.
259 </entry><entry>none</entry></row>
261 init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
262 After a successful Init, these options may be interrogated to
263 discover whether the server claims to support the specified
265 </entry><entry>none</entry></row>
270 If either option <literal>lang</literal> or <literal>charset</literal>
272 <ulink url="&url.z39.50.charneg;">
273 Character Set and Language Negotiation</ulink> is in effect.
276 int ZOOM_connection_error (ZOOM_connection c, const char **cp,
277 const char **addinfo);
278 int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
279 const char **addinfo, const char **dset);
282 Function <function>ZOOM_connection_error</function> checks for
283 errors for the last operation(s) performed. The function returns
284 zero if no errors occurred; non-zero otherwise indicating the error.
285 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
286 holds messages for the error and additional-info if passed as
287 non-<literal>NULL</literal>. Function
288 <function>ZOOM_connection_error_x</function> is an extended version
289 of <function>ZOOM_connection_error</function> that is capable of
290 returning name of diagnostic set in <parameter>dset</parameter>.
292 <sect2 id="zoom-connection-z39.50">
293 <title>Z39.50 Protocol behavior</title>
295 The calls <function>ZOOM_connection_new</function> and
296 <function>ZOOM_connection_connect</function> establishes a TCP/IP
297 connection and sends an Initialize Request to the target if
298 possible. In addition, the calls waits for an Initialize Response
299 from the target and the result is inspected (OK or rejected).
302 If <literal>proxy</literal> is set then the client will establish
303 a TCP/IP connection with the peer as specified by the
304 <literal>proxy</literal> host and the hostname as part of the
305 connect calls will be set as part of the Initialize Request.
306 The proxy server will then "forward" the PDU's transparently
307 to the target behind the proxy.
310 For the authentication parameters, if option <literal>user</literal>
311 is set and both options <literal>group</literal> and
312 <literal>pass</literal> are unset, then Open style
313 authentication is used (Version 2/3) in which case the username
314 is usually followed by a slash, then by a password.
315 If either <literal>group</literal>
316 or <literal>pass</literal> is set then idPass authentication
317 (Version 3 only) is used. If none of the options are set, no
318 authentication parameters are set as part of the Initialize Request
322 When option <literal>async</literal> is 1, it really means that
323 all network operations are postponed (and queued) until the
324 function <literal>ZOOM_event</literal> is invoked. When doing so
325 it doesn't make sense to check for errors after
326 <literal>ZOOM_connection_new</literal> is called since that
327 operation "connecting - and init" is still incomplete and the
328 API cannot tell the outcome (yet).
331 <sect2 id="zoom.sru.init.behavior">
332 <title>SRU Protocol behavior</title>
334 The SRU protocol doesn't feature an Inititialize Request, so
335 the connection phase merely establishes a TCP/IP connection
336 with the SOAP service.
338 <para>Most of the ZOOM connection options do not
339 affect SRU and they are ignored. However, future versions
340 of &yaz; might honor <literal>implementationName</literal> and
341 put that as part of User-Agent header for HTTP requests.
344 The <literal>charset</literal> is used in the Content-Type header
349 <sect1 id="zoom.query"><title>Queries</title>
351 Query objects represents queries.
354 ZOOM_query ZOOM_query_create(void);
356 void ZOOM_query_destroy(ZOOM_query q);
358 int ZOOM_query_prefix(ZOOM_query q, const char *str);
360 int ZOOM_query_cql(ZOOM_query s, const char *str);
362 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
365 Create query objects using <function>ZOOM_query_create</function>
366 and destroy them by calling <function>ZOOM_query_destroy</function>.
367 RPN-queries can be specified in <link linkend="PQF">PQF</link>
368 notation by using the
369 function <function>ZOOM_query_prefix</function>.
370 The <function>ZOOM_query_cql</function> specifies a CQL
371 query to be sent to the server/target.
372 More query types will be added in future versions of &yaz;, such as
373 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
374 etc. In addition to a search, a sort criteria may be set. Function
375 <function>ZOOM_query_sortby</function> specifies a
376 sort criteria using the same string notation for sort as offered by
377 the <link linkend="sortspec">YAZ client</link>.
379 <sect2 id="zoom.sort.behavior"><title>Protocol behavior</title>
381 The query object is just an interface for the member Query
382 in the SearchRequest. The sortby-function is an interface to the
383 sortSequence member of the SortRequest.
387 <sect1 id="zoom.resultsets"><title>Result sets</title>
389 The result set object is a container for records returned from
393 ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
396 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
399 void ZOOM_resultset_destroy(ZOOM_resultset r);
402 Function <function>ZOOM_connection_search</function> creates
403 a result set given a connection and query.
404 Destroy a result set by calling
405 <function>ZOOM_resultset_destroy</function>.
406 Simple clients may using PQF only may use function
407 <function>ZOOM_connection_search_pqf</function> in which case
408 creating query objects is not necessary.
411 void ZOOM_resultset_option_set (ZOOM_resultset r,
415 const char *ZOOM_resultset_option_get (ZOOM_resultset r,
418 size_t ZOOM_resultset_size (ZOOM_resultset r);
421 Functions <function>ZOOM_resultset_options_set</function> and
422 <function>ZOOM_resultset_get</function> sets and gets an option
423 for a result set similar to <function>ZOOM_connection_option_get</function>
424 and <function>ZOOM_connection_option_set</function>.
427 The number of hits also called result-count is returned by
428 function <function>ZOOM_resultset_size</function>.
430 <table id="zoom.resultset.options"
431 frame="top"><title>ZOOM Result set Options</title>
433 <colspec colwidth="4*" colname="name"></colspec>
434 <colspec colwidth="7*" colname="description"></colspec>
435 <colspec colwidth="2*" colname="default"></colspec>
438 <entry>Option</entry>
439 <entry>Description</entry>
440 <entry>Default</entry>
445 start</entry><entry>Offset of first record to be
446 retrieved from target. First record has offset 0 unlike the
447 protocol specifications where first record has position 1.
448 </entry><entry>0</entry></row>
450 count</entry><entry>Number of records to be retrieved.
451 </entry><entry>0</entry></row>
453 presentChunk</entry><entry>The number of records to be
454 requested from the server in each chunk (present requst). The
455 value 0 means to request all the records in a single chunk.
456 (The old <literal>step</literal>
457 option is also supported for the benefit of old applications.)
458 </entry><entry>0</entry></row>
460 elementSetName</entry><entry>Element-Set name of records.
461 Most targets should honor element set name <literal>B</literal>
462 and <literal>F</literal> for brief and full respectively.
463 </entry><entry>none</entry></row>
465 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
466 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
467 </entry><entry>none</entry></row>
469 schema</entry><entry>Schema for retrieval, such as
470 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
471 </entry><entry>none</entry></row>
473 setname</entry><entry>Name of Result Set (Result Set ID).
474 If this option isn't set, the ZOOM module will automatically
475 allocate a result set name.
476 </entry><entry>default</entry></row>
478 rpnCharset</entry><entry>Character set for RPN terms.
479 If this is set, ZOOM C will assume that the ZOOM application is
480 running UTF-8. Terms in RPN queries are then converted to the
481 rpnCharset. If this is unset, ZOOM C will not assume any encoding
482 of RPN terms and no conversion is performed.
483 </entry><entry>none</entry></row>
488 For servers that support Search Info report, the following
489 options may be read using <function>ZOOM_resultset_get</function>.
490 This detailed information is read after a successful search has
494 This information is a list of of items, where each item is
495 information about a term or subquery. All items in the list
497 <literal>SearchResult.</literal><replaceable>no</replaceable>
498 where no presents the item number (0=first, 1=second).
499 Read <literal>searchresult.size</literal> to determine the
502 <table id="zoom.search.info.report.options"
503 frame="top"><title>Search Info Report Options</title>
505 <colspec colwidth="4*" colname="name"></colspec>
506 <colspec colwidth="7*" colname="description"></colspec>
509 <entry>Option</entry>
510 <entry>Description</entry>
515 <entry>searchresult.size</entry>
517 number of search result entries. This option is-nonexistant
518 if no entries are returned by the server.
522 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
523 <entry>sub query ID</entry>
526 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
527 <entry>result count for item (number of hits)</entry>
530 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
531 <entry>subquery term</entry>
535 searchresult.<replaceable>no</replaceable>.interpretation.term
537 <entry>interpretation term</entry>
541 searchresult.<replaceable>no</replaceable>.recommendation.term
543 <entry>recommendation term</entry>
548 <sect2 id="zoom.z3950.resultset.behavior">
549 <title>Z39.50 Protocol behavior</title>
551 The creation of a result set involves at least a SearchRequest
552 - SearchResponse protocol handshake. Following that, if a sort
553 criteria was specified as part of the query, a SortRequest -
554 SortResponse handshake takes place. Note that it is necessary to
555 perform sorting before any retrieval takes place, so no records will
556 be returned from the target as part of the SearchResponse because these
557 would be unsorted. Hence, piggyback is disabled when sort criteria
558 are set. Following Search - and a possible sort - Retrieval takes
559 place - as one or more Present Requests/Response pairs being
563 The API allows for two different modes for retrieval. A high level
564 mode which is somewhat more powerful and a low level one.
565 The low level is enabled when searching on a Connection object
566 for which the settings
567 <literal>smallSetUpperBound</literal>,
568 <literal>mediumSetPresentNumber</literal> and
569 <literal>largeSetLowerBound</literal> are set. The low level mode
570 thus allows you to precisely set how records are returned as part
571 of a search response as offered by the Z39.50 protocol.
572 Since the client may be retrieving records as part of the
573 search response, this mode doesn't work well if sorting is used.
576 The high-level mode allows you to fetch a range of records from
577 the result set with a given start offset. When you use this mode
578 the client will automatically use piggyback if that is possible
579 with the target and perform one or more present requests as needed.
580 Even if the target returns fewer records as part of a present response
581 because of a record size limit, etc. the client will repeat sending
582 present requests. As an example, if option <literal>start</literal>
583 is 0 (default) and <literal>count</literal> is 4, and
584 <literal>piggyback</literal> is 1 (default) and no sorting criteria
585 is specified, then the client will attempt to retrieve the 4
586 records as part the search response (using piggyback). On the other
587 hand, if either <literal>start</literal> is positive or if
588 a sorting criteria is set, or if <literal>piggyback</literal>
589 is 0, then the client will not perform piggyback but send Present
593 If either of the options <literal>mediumSetElementSetName</literal> and
594 <literal>smallSetElementSetName</literal> are unset, the value
595 of option <literal>elementSetName</literal> is used for piggyback
596 searches. This means that for the high-level mode you only have
597 to specify one elementSetName option rather than three.
600 <sect2 id="zoom.sru.resultset.behavior">
601 <title>SRU Protocol behavior</title>
603 Current version of &yaz; does not take advantage of a result set id
604 returned by the SRU server. Future versions might do, however.
605 Since, the ZOOM driver does not save result set IDs any
606 present (retrieval) is transformed to a SRU SearchRetrieveRequest
607 with same query but, possibly, different offsets.
610 Option <literal>schema</literal> specifies SRU schema
611 for retrieval. However, options <literal>elementSetName</literal> and
612 <literal>preferredRecordSyntax</literal> are ignored.
615 Options <literal>start</literal> and <literal>count</literal>
616 are supported by SRU.
617 The remaining options
618 <literal>piggyback</literal>,
619 <literal>smallSetUpperBound</literal>,
620 <literal>largeSetLowerBound</literal>,
621 <literal>mediumSetPresentNumber</literal>,
622 <literal>mediumSetElementSetName</literal>,
623 <literal>smallSetElementSetName</literal> are
627 SRU supports CQL queries, <emphasis>not</emphasis> PQF.
628 If PQF is used, however, the PQF query is transferred anyway
629 using non-standard element <literal>pQuery</literal> in
630 SRU SearchRetrieveRequest.
633 Unfortunately, SRU does not define a database setting. Hence,
634 <literal>databaseName</literal> is unsupported and ignored.
635 However, the path part in host parameter for functions
636 <function>ZOOM_connecton_new</function> and
637 <function>ZOOM_connection_connect</function> acts as a
638 database (at least for the &yaz; SRU server).
642 <sect1 id="zoom.records"><title>Records</title>
644 A record object is a retrieval record on the client side -
645 created from result sets.
648 void ZOOM_resultset_records(ZOOM_resultset r,
650 size_t start, size_t count);
651 ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
653 const char *ZOOM_record_get(ZOOM_record rec, const char *type,
656 int ZOOM_record_error(ZOOM_record rec, const char **msg,
657 const char **addinfo, const char **diagset);
659 ZOOM_record ZOOM_record_clone (ZOOM_record rec);
661 void ZOOM_record_destroy (ZOOM_record rec);
664 References to temporary records are returned by functions
665 <function>ZOOM_resultset_records</function> or
666 <function>ZOOM_resultset_record</function>.
669 If a persistent reference to a record is desired
670 <function>ZOOM_record_clone</function> should be used.
671 It returns a record reference that should be destroyed
672 by a call to <function>ZOOM_record_destroy</function>.
675 A single record is returned by function
676 <function>ZOOM_resultset_record</function> that takes a
677 position as argument. First record has position zero.
678 If no record could be obtained <literal>NULL</literal> is returned.
681 Error information for a record can be checked with
682 <function>ZOOM_record_error</function> which returns non-zero
683 (error code) if record is in error, called <emphasis>Surrogate
684 Diagnostics</emphasis> in Z39.50.
687 Function <function>ZOOM_resultset_records</function> retrieves
688 a number of records from a result set. Parameter <literal>start</literal>
689 and <literal>count</literal> specifies the range of records to
690 be returned. Upon completion array
691 <literal>recs[0], ..recs[count-1]</literal>
692 holds record objects for the records. The array of records
693 <literal>recs</literal> should be allocated prior the call
694 <function>ZOOM_resultset_records</function>. Note that for those
695 records that couldn't be retrieved from the target
696 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
698 <para id="zoom.record.get">
699 In order to extract information about a single record,
700 <function>ZOOM_record_get</function> is provided. The
701 function returns a pointer to certain record information. The
702 nature (type) of the pointer depends on the parameter,
703 <parameter>type</parameter>.
706 The <parameter>type</parameter> is a string of the format:
709 <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
712 where <replaceable>form</replaceable> specifies the format of the
713 returned record, <replaceable>from</replaceable>
714 specifies the character set of the record in its original form
715 (as returned by the server), <replaceable>to</replaceable> specifies
716 the output (returned)
717 character set encoding.
718 If charset is not given, then no character set conversion takes place.
719 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
722 In addition, for certain types, the length
723 <literal>len</literal> passed will be set to the size in bytes of
724 the returned information.
727 The following are the supported values for <replaceable>form</replaceable>.
729 <varlistentry><term><literal>database</literal></term>
730 <listitem><para>Database of record is returned
731 as a C null-terminated string. Return type
732 <literal>const char *</literal>.
735 <varlistentry><term><literal>syntax</literal></term>
736 <listitem><para>The transfer syntax of the record is returned
737 as a C null-terminated string containing the symbolic name of
738 the record syntax, e.g. <literal>Usmarc</literal>. Return type
740 <literal>const char *</literal>.
743 <varlistentry><term><literal>render</literal></term>
744 <listitem><para>The record is returned in a display friendly
745 format. Upon completion buffer is returned
746 (type <literal>const char *</literal>) and length is stored in
747 <literal>*len</literal>.
750 <varlistentry><term><literal>raw</literal></term>
751 <listitem><para>The record is returned in the internal
752 YAZ specific format. For GRS-1, Explain, and others, the
753 raw data is returned as type
754 <literal>Z_External *</literal> which is just the type for
755 the member <literal>retrievalRecord</literal> in
756 type <literal>NamePlusRecord</literal>.
757 For SUTRS and octet aligned record (including all MARCs) the
758 octet buffer is returned and the length of the buffer.
761 <varlistentry><term><literal>xml</literal></term>
762 <listitem><para>The record is returned in XML if possible.
763 SRU and Z39.50 records with transfer syntax XML are
764 returned verbatim. MARC records are returned in
765 <ulink url="&url.marcxml;">
768 (converted from ISO2709 to MARCXML by YAZ).
769 GRS-1 and OPAC records are not supported for this form.
770 Upon completion, the XML buffer is returned
771 (type <literal>const char *</literal>) and length is stored in
772 <literal>*len</literal>.
775 <varlistentry><term><literal>opac</literal></term>
776 <listitem><para>OPAC for record is returned in XML.
783 <ulink url="&url.marc21;">MARC21</ulink>
785 <ulink url="&url.marc8;">MARC-8</ulink>
786 character set encoding.
787 An application that wishes to display in Latin-1 would use
789 render; charset=marc8,iso-8859-1
792 <sect2 id="zoom.z3950.record.behavior">
793 <title>Z39.50 Protocol behavior</title>
795 The functions <function>ZOOM_resultset_record</function> and
796 <function>ZOOM_resultset_records</function> inspects the client-side
797 record cache. Records not found in cache are fetched using
799 The functions may block (and perform network I/O) - even though option
800 <literal>async</literal> is 1, because they return records objects.
801 (and there's no way to return records objects without retrieving them!).
804 There is a trick, however, in the usage of function
805 <function>ZOOM_resultset_records</function> that allows for
806 delayed retrieval (and makes it non-blocking). By using
807 a null pointer for <parameter>recs</parameter> you're indicating
808 you're not interested in getting records objects
809 <emphasis>now</emphasis>.
812 <sect2 id="zoom.sru.record.behavior">
813 <title>SRU Protocol behavior</title>
815 The ZOOM driver for SRU treats records returned by a SRU server
816 as if they where Z39.50 records with transfer syntax XML and
817 no element set name or database name.
821 <sect1 id="zoom.scan"><title>Scan</title>
823 This section describes an interface for Scan. Scan is not an
824 official part of the ZOOM model yet. The result of a scan operation
825 is the <literal>ZOOM_scanset</literal> which is a set of terms
826 returned by a target.
830 The Scan interface is Z39.50 only. SRW version 1.0 does not
835 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
836 const char *startpqf);
838 size_t ZOOM_scanset_size(ZOOM_scanset scan);
840 const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
841 int *occ, size_t *len);
843 const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
844 int *occ, size_t *len);
846 void ZOOM_scanset_destroy (ZOOM_scanset scan);
848 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
851 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
855 The scan set is created by function
856 <function>ZOOM_connection_scan</function> which performs a scan
857 operation on the connection using the specified
858 <parameter>startpqf</parameter>.
859 If the operation was successful, the size of the scan set can be
860 retrieved by a call to <function>ZOOM_scanset_size</function>.
861 Like result sets, the items are numbered 0,..size-1.
862 To obtain information about a particular scan term, call function
863 <function>ZOOM_scanset_term</function>. This function takes
864 a scan set offset <literal>pos</literal> and returns a pointer
865 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
867 If present, the <literal>occ</literal> and <literal>len</literal>
868 are set to the number of occurrences and the length
869 of the actual term respectively.
870 <function>ZOOM_scanset_display_term</function> is similar to
871 <function>ZOOM_scanset_term</function> except that it returns
872 the <emphasis>display term</emphasis> rather than the raw term.
873 In a few cases, the term is different from display term. Always
874 use the display term for display and the raw term for subsequent
875 scan operations (to get more terms, next scan result, etc).
878 A scan set may be freed by a call to function
879 <function>ZOOM_scanset_destroy</function>.
880 Functions <function>ZOOM_scanset_option_get</function> and
881 <function>ZOOM_scanset_option_set</function> retrieves and sets
882 an option respectively.
886 The <parameter>startpqf</parameter> is a subset of PQF, namely
887 the Attributes+Term part. Multiple <literal>@attr</literal> can
888 be used. For example to scan in title (complete) phrases:
890 @attr 1=4 @attr 6=2 "science o"
894 <table frame="top" id="zoom.scanset.options">
895 <title>ZOOM Scan Set Options</title>
897 <colspec colwidth="4*" colname="name"></colspec>
898 <colspec colwidth="7*" colname="description"></colspec>
899 <colspec colwidth="2*" colname="default"></colspec>
902 <entry>Option</entry>
903 <entry>Description</entry>
904 <entry>Default</entry>
909 number</entry><entry>Number of Scan Terms requested in next scan.
910 After scan it holds the actual number of terms returned.
911 </entry><entry>10</entry></row>
913 position</entry><entry>Preferred Position of term in response
914 in next scan; actual position after completion of scan.
915 </entry><entry>1</entry></row>
917 stepSize</entry><entry>Step Size
918 </entry><entry>0</entry></row>
920 scanStatus</entry><entry>An integer indicating the Scan Status
922 </entry><entry>0</entry></row>
924 rpnCharset</entry><entry>Character set for RPN terms.
925 If this is set, ZOOM C will assume that the ZOOM application is
926 running UTF-8. Terms in RPN queries are then converted to the
927 rpnCharset. If this is unset, ZOOM C will not assume any encoding
928 of RPN terms and no conversion is performed.
929 </entry><entry>none</entry></row>
935 <sect1 id="zoom.extendedservices"><title>Extended Services</title>
937 ZOOM offers an interface to a subset of the Z39.50 extended services
938 as well as a few privately defined ones:
943 Z39.50 Item Order (ILL).
944 See <xref linkend="zoom.item.order"/>.
949 Record Update. This allows a client to insert, modify or delete
951 See <xref linkend="zoom.record.update"/>.
956 Database Create. This a non-standard feature. Allows a client
957 to create a database.
958 See <xref linkend="zoom.database.create"/>.
963 Database Drop. This a non-standard feature. Allows a client
964 to delete/drop a database.
965 See <xref linkend="zoom.database.drop"/>.
970 Commit operation. This a non-standard feature. Allows a client
971 to commit operations.
972 See <xref linkend="zoom.commit"/>.
975 <!-- all the ILL PDU options should go here too -->
978 To create an extended service operation a <literal>ZOOM_package</literal>
979 must be created. The operation is a five step operation. The
980 package is created, package is configured by means of options,
981 the package is send, result is inspected (by means of options),
982 the package is destroyed.
985 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
986 ZOOM_options options);
988 const char *ZOOM_package_option_get(ZOOM_package p,
990 void ZOOM_package_option_set(ZOOM_package p, const char *key,
992 void ZOOM_package_send(ZOOM_package p, const char *type);
994 void ZOOM_package_destroy(ZOOM_package p);
997 The <function>ZOOM_connection_package</function> creates a
998 package for the connection given using the options specified.
1001 Functions <function>ZOOM_package_option_get</function> and
1002 <function>ZOOM_package_option_set</function> gets and sets
1006 <function>ZOOM_package_send</function> sends
1007 the package the via connection specified in
1008 <function>ZOOM_connection_package</function>.
1009 The <parameter>type</parameter> specifies the actual extended service
1010 package type to be sent.
1013 <table frame="top" id="zoom.extendedservices.options">
1014 <title>Extended Service Common Options</title>
1016 <colspec colwidth="4*" colname="name"></colspec>
1017 <colspec colwidth="7*" colname="description"></colspec>
1018 <colspec colwidth="3*" colname="default"></colspec>
1021 <entry>Option</entry>
1022 <entry>Description</entry>
1023 <entry>Default</entry>
1028 <entry>package-name</entry>
1029 <entry>Extended Service Request package name. Must be specified
1030 as part of a request</entry>
1034 <entry>user-id</entry>
1035 <entry>User ID of Extended Service Package. Is a request option</entry>
1039 <entry>function</entry>
1041 Function of package - one of <literal>create</literal>,
1042 <literal>delete</literal>, <literal>modify</literal>. Is
1045 <entry><literal>create</literal></entry>
1048 <entry>targetReference</entry>
1050 Target Reference. This is part of the response as returned
1051 by the server. Read it after a succesful operation.
1053 <entry><literal>none</literal></entry>
1059 <sect2 id="zoom.item.order"><title>Item Order</title>
1061 For Item Order, type must be set to <literal>itemorder</literal> in
1062 <function>ZOOM_package_send</function>.
1065 <table frame="top" id="zoom.item.order.options">
1066 <title>Item Order Options</title>
1068 <colspec colwidth="4*" colname="name"></colspec>
1069 <colspec colwidth="7*" colname="description"></colspec>
1070 <colspec colwidth="3*" colname="default"></colspec>
1073 <entry>Option</entry>
1074 <entry>Description</entry>
1075 <entry>Default</entry>
1080 <entry>contact-name</entry>
1081 <entry>ILL contact name</entry>
1085 <entry>contact-phone</entry>
1086 <entry>ILL contact phone</entry>
1090 <entry>contact-email</entry>
1091 <entry>ILL contact email</entry>
1095 <entry>itemorder-item</entry>
1096 <entry>Position for item (record) requested. An integer</entry>
1105 <sect2 id="zoom.record.update"><title>Record Update</title>
1107 For Record Update, type must be set to <literal>update</literal> in
1108 <function>ZOOM_package_send</function>.
1111 <table frame="top" id="zoom.record.update.options">
1112 <title>Record Update Options</title>
1114 <colspec colwidth="4*" colname="name"></colspec>
1115 <colspec colwidth="7*" colname="description"></colspec>
1116 <colspec colwidth="3*" colname="default"></colspec>
1119 <entry>Option</entry>
1120 <entry>Description</entry>
1121 <entry>Default</entry>
1126 <entry>action</entry>
1128 The update action. One of
1129 <literal>specialUpdate</literal>,
1130 <literal>recordInsert</literal>,
1131 <literal>recordReplace</literal>,
1132 <literal>recordDelete</literal>,
1133 <literal>elementUpdate</literal>.
1135 <entry><literal>specialUpdate</literal></entry>
1138 <entry>recordIdOpaque</entry>
1139 <entry>Opaque Record ID</entry>
1143 <entry>recordIdNumber</entry>
1144 <entry>Record ID number</entry>
1148 <entry>record</entry>
1149 <entry>The record itself</entry>
1153 <entry>syntax</entry>
1154 <entry>The record syntax (transfer syntax). Is a string that
1155 is a known record syntax.
1157 <entry>no syntax</entry>
1160 <entry>databaseName</entry>
1161 <entry>Database from connection object</entry>
1162 <entry>Default</entry>
1170 <sect2 id="zoom.database.create"><title>Database Create</title>
1172 For Database Create, type must be set to <literal>create</literal> in
1173 <function>ZOOM_package_send</function>.
1176 <table frame="top" id="zoom.database.create.options">
1177 <title>Database Create Options</title>
1179 <colspec colwidth="4*" colname="name"></colspec>
1180 <colspec colwidth="7*" colname="description"></colspec>
1181 <colspec colwidth="3*" colname="default"></colspec>
1184 <entry>Option</entry>
1185 <entry>Description</entry>
1186 <entry>Default</entry>
1191 <entry>databaseName</entry>
1192 <entry>Database from connection object</entry>
1193 <entry>Default</entry>
1200 <sect2 id="zoom.database.drop"><title>Database Drop</title>
1202 For Database Drop, type must be set to <literal>drop</literal> in
1203 <function>ZOOM_package_send</function>.
1206 <table frame="top" id="zoom.database.drop.options">
1207 <title>Database Drop Options</title>
1209 <colspec colwidth="4*" colname="name"></colspec>
1210 <colspec colwidth="7*" colname="description"></colspec>
1211 <colspec colwidth="3*" colname="default"></colspec>
1214 <entry>Option</entry>
1215 <entry>Description</entry>
1216 <entry>Default</entry>
1221 <entry>databaseName</entry>
1222 <entry>Database from connection object</entry>
1223 <entry>Default</entry>
1230 <sect2 id="zoom.commit"><title>Commit Operation</title>
1232 For Commit, type must be set to <literal>commit</literal> in
1233 <function>ZOOM_package_send</function>.
1237 <sect2 id="zoom.extended.services.behavior">
1238 <title>Protocol behavior</title>
1240 All the extended services are Z39.50-only.
1244 The database create, drop and commit services are privately defined
1246 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1253 <sect1 id="zoom.options"><title>Options</title>
1255 Most &zoom; objects provide a way to specify options to change behavior.
1256 From an implementation point of view a set of options is just like
1257 an associative array / hash.
1260 ZOOM_options ZOOM_options_create (void);
1262 ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
1264 void ZOOM_options_destroy (ZOOM_options opt);
1267 const char *ZOOM_options_get (ZOOM_options opt, const char *name);
1269 void ZOOM_options_set (ZOOM_options opt, const char *name,
1273 typedef const char *(*ZOOM_options_callback)
1274 (void *handle, const char *name);
1276 ZOOM_options_callback
1277 ZOOM_options_set_callback (ZOOM_options opt,
1278 ZOOM_options_callback c,
1282 <sect1 id="zoom.events"><title>Events</title>
1284 If you're developing non-blocking applications, you have to deal
1288 int ZOOM_event (int no, ZOOM_connection *cs);
1291 The <function>ZOOM_event</function> executes pending events for
1292 a number of connections. Supply the number of connections in
1293 <literal>no</literal> and an array of connections in
1294 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1295 A pending event could be a sending a search, receiving a response,
1297 When an event has occurred for one of the connections, this function
1298 returns a positive integer <literal>n</literal> denoting that an event
1299 occurred for connection <literal>cs[n-1]</literal>.
1300 When no events are pending for the connections, a value of zero is
1302 To ensure that all outstanding requests are performed call this function
1303 repeatedly until zero is returned.
1306 If <function>ZOOM_event</function> returns and returns non-zero, the
1307 last event that occurred can be expected.
1310 int ZOOM_connection_last_event(ZOOM_connection cs);
1313 <function>ZOOM_connection_last_event</function> returns an event type
1314 (integer) for the last event.
1317 <table frame="top" id="zoom.event.ids">
1318 <title>ZOOM Event IDs</title>
1320 <colspec colwidth="4*" colname="name"></colspec>
1321 <colspec colwidth="7*" colname="description"></colspec>
1324 <entry>Event</entry>
1325 <entry>Description</entry>
1330 <entry>ZOOM_EVENT_NONE</entry>
1331 <entry>No event has occurred</entry>
1334 <entry>ZOOM_EVENT_CONNECT</entry>
1335 <entry>TCP/IP connect has initiated</entry>
1338 <entry>ZOOM_EVENT_SEND_DATA</entry>
1339 <entry>Data has been transmitted (sending)</entry>
1342 <entry>ZOOM_EVENT_RECV_DATA</entry>
1343 <entry>Data has been received)</entry>
1346 <entry>ZOOM_EVENT_TIMEOUT</entry>
1347 <entry>Timeout</entry>
1350 <entry>ZOOM_EVENT_UNKNOWN</entry>
1351 <entry>Unknown event</entry>
1354 <entry>ZOOM_EVENT_SEND_APDU</entry>
1355 <entry>An APDU has been transmitted (sending)</entry>
1358 <entry>ZOOM_EVENT_RECV_APDU</entry>
1359 <entry>An APDU has been received</entry>
1362 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1363 <entry>A result-set record has been received</entry>
1366 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1367 <entry>A search result been received</entry>
1375 <!-- Keep this comment at the end of the file
1380 sgml-minimize-attributes:nil
1381 sgml-always-quote-attributes:t
1384 sgml-parent-document: "yaz.xml"
1385 sgml-local-catalogs: nil
1386 sgml-namecase-general:t