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 <chapter id="zoom"><title>ZOOM</title>
25 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
26 an initiative started by Mike Taylor (Mike is from the UK, which
27 explains the peculiar name of the model). The goal of &zoom; is to
28 provide a common Z39.50 client API not bound to a particular
29 programming language or toolkit.
34 A recent addition to &yaz; is SRU support. You can now make
35 SRU ZOOM connections by specifying scheme <literal>http://</literal>
36 for the hostname for a connection. The dialect of SRU used is
37 specified by the value of the connection's <literal>sru</literal>
38 option, which may be SRU over HTTP GET (<literal>get</literal>),
39 SRU over HTTP POST (<literal>post</literal>) or SRW (SRU over
40 SOAP) (<literal>soap</literal>). Using the facility for embedding
41 options in target strings, a connection can be forced to use SRU
42 rather the SRW (the default) by prefixing the target string with
43 <literal>sru=get,</literal>, like this:
44 <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
49 The lack of a simple Z39.50 client API for &yaz; has become more
50 and more apparent over time. So when the first &zoom; specification
52 an implementation for &yaz; was quickly developed. For the first time, it is
53 now as easy (or easier!) to develop clients than servers with &yaz;. This
54 chapter describes the &zoom; C binding. Before going further, please
55 reconsider whether C is the right programming language for the job.
56 There are other language bindings available for &yaz;, and still
58 are in active development. See the
59 <ulink url="&url.zoom;">ZOOM web-site</ulink> for
64 In order to fully understand this chapter you should read and
65 try the example programs <literal>zoomtst1.c</literal>,
66 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
71 The C language misses features found in object oriented languages
72 such as C++, Java, etc. For example, you'll have to manually,
73 destroy all objects you create, even though you may think of them as
74 temporary. Most objects has a <literal>_create</literal> - and a
75 <literal>_destroy</literal> variant.
76 All objects are in fact pointers to internal stuff, but you don't see
77 that because of typedefs. All destroy methods should gracefully ignore a
78 <literal>NULL</literal> pointer.
81 In each of the sections below you'll find a sub section called
82 protocol behavior, that describes how the API maps to the Z39.50
85 <sect1 id="zoom-connections"><title>Connections</title>
87 <para>The Connection object is a session with a target.
90 #include <yaz/zoom.h>
92 ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
94 ZOOM_connection ZOOM_connection_create (ZOOM_options options);
96 void ZOOM_connection_connect(ZOOM_connection c, const char *host,
98 void ZOOM_connection_destroy(ZOOM_connection c);
101 Connection objects are created with either function
102 <function>ZOOM_connection_new</function> or
103 <function>ZOOM_connection_create</function>.
104 The former creates and automatically attempts to establish a network
105 connection with the target. The latter doesn't establish
106 a connection immediately, thus allowing you to specify options
107 before establishing network connection using the function
108 <function>ZOOM_connection_connect</function>.
109 If the port number, <literal>portnum</literal>, is zero, the
110 <literal>host</literal> is consulted for a port specification.
111 If no port is given, 210 is used. A colon denotes the beginning of
112 a port number in the host string. If the host string includes a
113 slash, the following part specifies a database for the connection.
116 You can prefix the host with a scheme followed by colon. The
117 default scheme is <literal>tcp</literal> (Z39.50 protocol).
118 The scheme <literal>http</literal> selects SRU over HTTP.
121 You can prefix the scheme-qualified host-string with one or more
123 <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
124 sequences, each of which represents an option to be set into the
125 connection structure <emphasis>before</emphasis> the
126 protocol-level connection is forged and the initialization
127 handshake takes place. This facility can be used to provide
128 authentication credentials, as in host-strings such as:
129 <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
132 Connection objects should be destroyed using the function
133 <function>ZOOM_connection_destroy</function>.
136 void ZOOM_connection_option_set(ZOOM_connection c,
137 const char *key, const char *val);
139 void ZOOM_connection_option_setl(ZOOM_connection c,
141 const char *val, int len);
143 const char *ZOOM_connection_option_get(ZOOM_connection c,
145 const char *ZOOM_connection_option_getl(ZOOM_connection c,
150 The functions <function>ZOOM_connection_option_set</function> and
151 <function>ZOOM_connection_option_setl</function> allows you to
152 set an option given by <parameter>key</parameter> to the value
153 <parameter>value</parameter> for the connection.
154 For <function>ZOOM_connection_option_set</function>, the
155 value is assumed to be a 0-terminated string. Function
156 <function>ZOOM_connection_option_setl</function> specifies a
157 value of a certain size (len).
160 Functions <function>ZOOM_connection_option_get</function> and
161 <function>ZOOM_connection_option_getl</function> returns
162 the value for an option given by <parameter>key</parameter>.
164 <table id="zoom-connection-options" frame="top">
165 <title>ZOOM Connection Options</title>
167 <colspec colwidth="4*" colname="name"></colspec>
168 <colspec colwidth="7*" colname="description"></colspec>
169 <colspec colwidth="3*" colname="default"></colspec>
172 <entry>Option</entry>
173 <entry>Description</entry>
174 <entry>Default</entry>
179 implementationName</entry><entry>Name of Your client
180 </entry><entry>none</entry></row>
182 user</entry><entry>Authentication user name
183 </entry><entry>none</entry></row>
185 group</entry><entry>Authentication group name
186 </entry><entry>none</entry></row>
188 password</entry><entry>Authentication password.
189 </entry><entry>none</entry></row>
191 host</entry><entry>Target host. This setting is "read-only".
192 It's automatically set internally when connecting to a target.
193 </entry><entry>none</entry></row>
195 proxy</entry><entry>Proxy host
196 </entry><entry>none</entry></row>
198 async</entry><entry>If true (1) the connection operates in
199 asynchronous operation which means that all calls are non-blocking
201 <link linkend="zoom.events"><function>ZOOM_event</function></link>.
202 </entry><entry>0</entry></row>
204 maximumRecordSize</entry><entry> Maximum size of single record.
205 </entry><entry>1 MB</entry></row>
207 preferredMessageSize</entry><entry> Maximum size of multiple records.
208 </entry><entry>1 MB</entry></row>
210 lang</entry><entry> Language for negotiation.
211 </entry><entry>none</entry></row>
213 charset</entry><entry> Character set for negotiation.
214 </entry><entry>none</entry></row>
216 serverImplementationId</entry><entry>
217 Implementation ID of server. (The old targetImplementationId
218 option is also supported for the benefit of old applications.)
219 </entry><entry>none</entry></row>
221 targetImplementationName</entry><entry>
222 Implementation Name of server. (The old
223 targetImplementationName option is also supported for the
224 benefit of old applications.)
225 </entry><entry>none</entry></row>
227 serverImplementationVersion</entry><entry>
228 Implementation Version of server. (the old
229 targetImplementationVersion option is also supported for the
230 benefit of old applications.)
231 </entry><entry>none</entry></row>
233 databaseName</entry><entry>One or more database names
234 separated by character plus (<literal>+</literal>), which to
235 be used by subsequent search requests on this Connection.
236 </entry><entry>Default</entry></row>
238 piggyback</entry><entry>True (1) if piggyback should be
239 used in searches; false (0) if not.
240 </entry><entry>1</entry></row>
242 smallSetUpperBound</entry><entry>If hits is less than or equal to this
243 value, then target will return all records using small element set name
244 </entry><entry>0</entry></row>
246 largeSetLowerBound</entry><entry>If hits is greater than this
247 value, the target will return no records.
248 </entry><entry>1</entry></row>
250 mediumSetPresentNumber</entry><entry>This value represents
251 the number of records to be returned as part of a search when when
252 hits is less than or equal to large set lower bound and if hits
253 is greater than small set upper bound.
254 </entry><entry>0</entry></row>
256 smallSetElementSetName</entry><entry>
257 The element set name to be used for small result sets.
258 </entry><entry>none</entry></row>
260 mediumSetElementSetName</entry><entry>
261 The element set name to be for medium-sized result sets.
262 </entry><entry>none</entry></row>
264 init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
265 After a successful Init, these options may be interrogated to
266 discover whether the server claims to support the specified
268 </entry><entry>none</entry></row>
271 SRU transport type. Must be either <literal>soap</literal>,
272 <literal>get</literal> or <literal>post</literal>.
273 </entry><entry>soap</entry></row>
275 sru_version</entry><entry>
276 SRU/SRW version. Should be <literal>1.1</literal>, or
277 <literal>1.2</literal>. This is , prior to connect, the version
278 to offer (highest version). And following connect (in fact
279 first operation), holds the negotiated version with the server
280 (same or lower version).
281 </entry><entry>1.2</entry></row>
286 If either option <literal>lang</literal> or <literal>charset</literal>
288 <ulink url="&url.z39.50.charneg;">
289 Character Set and Language Negotiation</ulink> is in effect.
292 int ZOOM_connection_error(ZOOM_connection c, const char **cp,
293 const char **addinfo);
294 int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
295 const char **addinfo, const char **dset);
298 Function <function>ZOOM_connection_error</function> checks for
299 errors for the last operation(s) performed. The function returns
300 zero if no errors occurred; non-zero otherwise indicating the error.
301 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
302 holds messages for the error and additional-info if passed as
303 non-<literal>NULL</literal>. Function
304 <function>ZOOM_connection_error_x</function> is an extended version
305 of <function>ZOOM_connection_error</function> that is capable of
306 returning name of diagnostic set in <parameter>dset</parameter>.
308 <sect2 id="zoom-connection-z39.50">
309 <title>Z39.50 Protocol behavior</title>
311 The calls <function>ZOOM_connection_new</function> and
312 <function>ZOOM_connection_connect</function> establishes a TCP/IP
313 connection and sends an Initialize Request to the target if
314 possible. In addition, the calls waits for an Initialize Response
315 from the target and the result is inspected (OK or rejected).
318 If <literal>proxy</literal> is set then the client will establish
319 a TCP/IP connection with the peer as specified by the
320 <literal>proxy</literal> host and the hostname as part of the
321 connect calls will be set as part of the Initialize Request.
322 The proxy server will then "forward" the PDU's transparently
323 to the target behind the proxy.
326 For the authentication parameters, if option <literal>user</literal>
327 is set and both options <literal>group</literal> and
328 <literal>pass</literal> are unset, then Open style
329 authentication is used (Version 2/3) in which case the username
330 is usually followed by a slash, then by a password.
331 If either <literal>group</literal>
332 or <literal>pass</literal> is set then idPass authentication
333 (Version 3 only) is used. If none of the options are set, no
334 authentication parameters are set as part of the Initialize Request
338 When option <literal>async</literal> is 1, it really means that
339 all network operations are postponed (and queued) until the
340 function <literal>ZOOM_event</literal> is invoked. When doing so
341 it doesn't make sense to check for errors after
342 <literal>ZOOM_connection_new</literal> is called since that
343 operation "connecting - and init" is still incomplete and the
344 API cannot tell the outcome (yet).
347 <sect2 id="zoom.sru.init.behavior">
348 <title>SRU Protocol behavior</title>
350 The SRU protocol doesn't feature an Inititialize Request, so
351 the connection phase merely establishes a TCP/IP connection
352 with the SOAP service.
354 <para>Most of the ZOOM connection options do not
355 affect SRU and they are ignored. However, future versions
356 of &yaz; might honor <literal>implementationName</literal> and
357 put that as part of User-Agent header for HTTP requests.
360 The <literal>charset</literal> is used in the Content-Type header
365 <sect1 id="zoom.query"><title>Queries</title>
367 Query objects represents queries.
370 ZOOM_query ZOOM_query_create(void);
372 void ZOOM_query_destroy(ZOOM_query q);
374 int ZOOM_query_prefix(ZOOM_query q, const char *str);
376 int ZOOM_query_cql(ZOOM_query s, const char *str);
378 int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
381 Create query objects using <function>ZOOM_query_create</function>
382 and destroy them by calling <function>ZOOM_query_destroy</function>.
383 RPN-queries can be specified in <link linkend="PQF">PQF</link>
384 notation by using the
385 function <function>ZOOM_query_prefix</function>.
386 The <function>ZOOM_query_cql</function> specifies a CQL
387 query to be sent to the server/target.
388 More query types will be added in future versions of &yaz;, such as
389 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
390 etc. In addition to a search, a sort criteria may be set. Function
391 <function>ZOOM_query_sortby</function> specifies a
392 sort criteria using the same string notation for sort as offered by
393 the <link linkend="sortspec">YAZ client</link>.
395 <sect2 id="zoom.sort.behavior"><title>Protocol behavior</title>
397 The query object is just an interface for the member Query
398 in the SearchRequest. The sortby-function is an interface to the
399 sortSequence member of the SortRequest.
403 <sect1 id="zoom.resultsets"><title>Result sets</title>
405 The result set object is a container for records returned from
409 ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
411 ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
413 void ZOOM_resultset_destroy(ZOOM_resultset r);
416 Function <function>ZOOM_connection_search</function> creates
417 a result set given a connection and query.
418 Destroy a result set by calling
419 <function>ZOOM_resultset_destroy</function>.
420 Simple clients may using PQF only may use function
421 <function>ZOOM_connection_search_pqf</function> in which case
422 creating query objects is not necessary.
425 void ZOOM_resultset_option_set(ZOOM_resultset r,
426 const char *key, const char *val);
428 const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
430 size_t ZOOM_resultset_size(ZOOM_resultset r);
433 Functions <function>ZOOM_resultset_options_set</function> and
434 <function>ZOOM_resultset_get</function> sets and gets an option
435 for a result set similar to <function>ZOOM_connection_option_get</function>
436 and <function>ZOOM_connection_option_set</function>.
439 The number of hits also called result-count is returned by
440 function <function>ZOOM_resultset_size</function>.
442 <table id="zoom.resultset.options"
443 frame="top"><title>ZOOM Result set Options</title>
445 <colspec colwidth="4*" colname="name"></colspec>
446 <colspec colwidth="7*" colname="description"></colspec>
447 <colspec colwidth="2*" colname="default"></colspec>
450 <entry>Option</entry>
451 <entry>Description</entry>
452 <entry>Default</entry>
457 start</entry><entry>Offset of first record to be
458 retrieved from target. First record has offset 0 unlike the
459 protocol specifications where first record has position 1.
460 This option affects ZOOM_resultset_search and
461 ZOOM_resultset_search_pqf and must be set before any of
462 these functions are invoked. If a range of
463 records must be fetched manually after search,
464 function ZOOM_resultset_records should be used.
465 </entry><entry>0</entry></row>
467 count</entry><entry>Number of records to be retrieved.
468 This option affects ZOOM_resultset_search and
469 ZOOM_resultset_search_pqf and must be set before any of
470 these functions are invoked.
471 </entry><entry>0</entry></row>
473 presentChunk</entry><entry>The number of records to be
474 requested from the server in each chunk (present request). The
475 value 0 means to request all the records in a single chunk.
476 (The old <literal>step</literal>
477 option is also supported for the benefit of old applications.)
478 </entry><entry>0</entry></row>
480 elementSetName</entry><entry>Element-Set name of records.
481 Most targets should honor element set name <literal>B</literal>
482 and <literal>F</literal> for brief and full respectively.
483 </entry><entry>none</entry></row>
485 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
486 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
487 </entry><entry>none</entry></row>
489 schema</entry><entry>Schema for retrieval, such as
490 <literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
491 </entry><entry>none</entry></row>
493 setname</entry><entry>Name of Result Set (Result Set ID).
494 If this option isn't set, the ZOOM module will automatically
495 allocate a result set name.
496 </entry><entry>default</entry></row>
498 rpnCharset</entry><entry>Character set for RPN terms.
499 If this is set, ZOOM C will assume that the ZOOM application is
500 running UTF-8. Terms in RPN queries are then converted to the
501 rpnCharset. If this is unset, ZOOM C will not assume any encoding
502 of RPN terms and no conversion is performed.
503 </entry><entry>none</entry></row>
508 For servers that support Search Info report, the following
509 options may be read using <function>ZOOM_resultset_get</function>.
510 This detailed information is read after a successful search has
514 This information is a list of of items, where each item is
515 information about a term or subquery. All items in the list
517 <literal>SearchResult.</literal><replaceable>no</replaceable>
518 where no presents the item number (0=first, 1=second).
519 Read <literal>searchresult.size</literal> to determine the
522 <table id="zoom.search.info.report.options"
523 frame="top"><title>Search Info Report Options</title>
525 <colspec colwidth="4*" colname="name"></colspec>
526 <colspec colwidth="7*" colname="description"></colspec>
529 <entry>Option</entry>
530 <entry>Description</entry>
535 <entry>searchresult.size</entry>
537 number of search result entries. This option is-nonexistant
538 if no entries are returned by the server.
542 <entry>searchresult.<replaceable>no</replaceable>.id</entry>
543 <entry>sub query ID</entry>
546 <entry>searchresult.<replaceable>no</replaceable>.count</entry>
547 <entry>result count for item (number of hits)</entry>
550 <entry>searchresult.<replaceable>no</replaceable>.subquery.term</entry>
551 <entry>subquery term</entry>
555 searchresult.<replaceable>no</replaceable>.interpretation.term
557 <entry>interpretation term</entry>
561 searchresult.<replaceable>no</replaceable>.recommendation.term
563 <entry>recommendation term</entry>
568 <sect2 id="zoom.z3950.resultset.behavior">
569 <title>Z39.50 Protocol behavior</title>
571 The creation of a result set involves at least a SearchRequest
572 - SearchResponse protocol handshake. Following that, if a sort
573 criteria was specified as part of the query, a SortRequest -
574 SortResponse handshake takes place. Note that it is necessary to
575 perform sorting before any retrieval takes place, so no records will
576 be returned from the target as part of the SearchResponse because these
577 would be unsorted. Hence, piggyback is disabled when sort criteria
578 are set. Following Search - and a possible sort - Retrieval takes
579 place - as one or more Present Requests/Response pairs being
583 The API allows for two different modes for retrieval. A high level
584 mode which is somewhat more powerful and a low level one.
585 The low level is enabled when searching on a Connection object
586 for which the settings
587 <literal>smallSetUpperBound</literal>,
588 <literal>mediumSetPresentNumber</literal> and
589 <literal>largeSetLowerBound</literal> are set. The low level mode
590 thus allows you to precisely set how records are returned as part
591 of a search response as offered by the Z39.50 protocol.
592 Since the client may be retrieving records as part of the
593 search response, this mode doesn't work well if sorting is used.
596 The high-level mode allows you to fetch a range of records from
597 the result set with a given start offset. When you use this mode
598 the client will automatically use piggyback if that is possible
599 with the target and perform one or more present requests as needed.
600 Even if the target returns fewer records as part of a present response
601 because of a record size limit, etc. the client will repeat sending
602 present requests. As an example, if option <literal>start</literal>
603 is 0 (default) and <literal>count</literal> is 4, and
604 <literal>piggyback</literal> is 1 (default) and no sorting criteria
605 is specified, then the client will attempt to retrieve the 4
606 records as part the search response (using piggyback). On the other
607 hand, if either <literal>start</literal> is positive or if
608 a sorting criteria is set, or if <literal>piggyback</literal>
609 is 0, then the client will not perform piggyback but send Present
613 If either of the options <literal>mediumSetElementSetName</literal> and
614 <literal>smallSetElementSetName</literal> are unset, the value
615 of option <literal>elementSetName</literal> is used for piggyback
616 searches. This means that for the high-level mode you only have
617 to specify one elementSetName option rather than three.
620 <sect2 id="zoom.sru.resultset.behavior">
621 <title>SRU Protocol behavior</title>
623 Current version of &yaz; does not take advantage of a result set id
624 returned by the SRU server. Future versions might do, however.
625 Since, the ZOOM driver does not save result set IDs any
626 present (retrieval) is transformed to a SRU SearchRetrieveRequest
627 with same query but, possibly, different offsets.
630 Option <literal>schema</literal> specifies SRU schema
631 for retrieval. However, options <literal>elementSetName</literal> and
632 <literal>preferredRecordSyntax</literal> are ignored.
635 Options <literal>start</literal> and <literal>count</literal>
636 are supported by SRU.
637 The remaining options
638 <literal>piggyback</literal>,
639 <literal>smallSetUpperBound</literal>,
640 <literal>largeSetLowerBound</literal>,
641 <literal>mediumSetPresentNumber</literal>,
642 <literal>mediumSetElementSetName</literal>,
643 <literal>smallSetElementSetName</literal> are
647 SRU supports CQL queries, <emphasis>not</emphasis> PQF.
648 If PQF is used, however, the PQF query is transferred anyway
649 using non-standard element <literal>pQuery</literal> in
650 SRU SearchRetrieveRequest.
653 Unfortunately, SRU does not define a database setting. Hence,
654 <literal>databaseName</literal> is unsupported and ignored.
655 However, the path part in host parameter for functions
656 <function>ZOOM_connecton_new</function> and
657 <function>ZOOM_connection_connect</function> acts as a
658 database (at least for the &yaz; SRU server).
662 <sect1 id="zoom.records"><title>Records</title>
664 A record object is a retrieval record on the client side -
665 created from result sets.
668 void ZOOM_resultset_records(ZOOM_resultset r,
670 size_t start, size_t count);
671 ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
673 const char *ZOOM_record_get(ZOOM_record rec, const char *type,
676 int ZOOM_record_error(ZOOM_record rec, const char **msg,
677 const char **addinfo, const char **diagset);
679 ZOOM_record ZOOM_record_clone(ZOOM_record rec);
681 void ZOOM_record_destroy(ZOOM_record rec);
684 References to temporary records are returned by functions
685 <function>ZOOM_resultset_records</function> or
686 <function>ZOOM_resultset_record</function>.
689 If a persistent reference to a record is desired
690 <function>ZOOM_record_clone</function> should be used.
691 It returns a record reference that should be destroyed
692 by a call to <function>ZOOM_record_destroy</function>.
695 A single record is returned by function
696 <function>ZOOM_resultset_record</function> that takes a
697 position as argument. First record has position zero.
698 If no record could be obtained <literal>NULL</literal> is returned.
701 Error information for a record can be checked with
702 <function>ZOOM_record_error</function> which returns non-zero
703 (error code) if record is in error, called <emphasis>Surrogate
704 Diagnostics</emphasis> in Z39.50.
707 Function <function>ZOOM_resultset_records</function> retrieves
708 a number of records from a result set. Parameter <literal>start</literal>
709 and <literal>count</literal> specifies the range of records to
710 be returned. Upon completion array
711 <literal>recs[0], ..recs[count-1]</literal>
712 holds record objects for the records. The array of records
713 <literal>recs</literal> should be allocated prior the call
714 <function>ZOOM_resultset_records</function>. Note that for those
715 records that couldn't be retrieved from the target
716 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
718 <para id="zoom.record.get">
719 In order to extract information about a single record,
720 <function>ZOOM_record_get</function> is provided. The
721 function returns a pointer to certain record information. The
722 nature (type) of the pointer depends on the parameter,
723 <parameter>type</parameter>.
726 The <parameter>type</parameter> is a string of the format:
729 <replaceable>form</replaceable>[;charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]
732 where <replaceable>form</replaceable> specifies the format of the
733 returned record, <replaceable>from</replaceable>
734 specifies the character set of the record in its original form
735 (as returned by the server), <replaceable>to</replaceable> specifies
736 the output (returned)
737 character set encoding.
738 If charset is not given, then no character set conversion takes place.
739 If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
742 The format argument controls whether record data should be XML
743 pretty-printed (post process operation).
744 It is enabled only if format value <replaceable>v</replaceable> is
745 <literal>1</literal> and the record content is XML well-formed.
748 In addition, for certain types, the length
749 <literal>len</literal> passed will be set to the size in bytes of
750 the returned information.
753 The following are the supported values for <replaceable>form</replaceable>.
755 <varlistentry><term><literal>database</literal></term>
756 <listitem><para>Database of record is returned
757 as a C null-terminated string. Return type
758 <literal>const char *</literal>.
761 <varlistentry><term><literal>syntax</literal></term>
762 <listitem><para>The transfer syntax of the record is returned
763 as a C null-terminated string containing the symbolic name of
764 the record syntax, e.g. <literal>Usmarc</literal>. Return type
766 <literal>const char *</literal>.
769 <varlistentry><term><literal>schema</literal></term>
770 <listitem><para>The schema of the record is returned
771 as a C null-terminated string. Return type is
772 <literal>const char *</literal>.
775 <varlistentry><term><literal>render</literal></term>
776 <listitem><para>The record is returned in a display friendly
777 format. Upon completion buffer is returned
778 (type <literal>const char *</literal>) and length is stored in
779 <literal>*len</literal>.
782 <varlistentry><term><literal>raw</literal></term>
783 <listitem><para>The record is returned in the internal
784 YAZ specific format. For GRS-1, Explain, and others, the
785 raw data is returned as type
786 <literal>Z_External *</literal> which is just the type for
787 the member <literal>retrievalRecord</literal> in
788 type <literal>NamePlusRecord</literal>.
789 For SUTRS and octet aligned record (including all MARCs) the
790 octet buffer is returned and the length of the buffer.
793 <varlistentry><term><literal>xml</literal></term>
794 <listitem><para>The record is returned in XML if possible.
795 SRU and Z39.50 records with transfer syntax XML are
796 returned verbatim. MARC records are returned in
797 <ulink url="&url.marcxml;">
800 (converted from ISO2709 to MARCXML by YAZ).
801 OPAC records are also converted to XML and the
802 bibliographic record is converted to MARCXML (when possible).
803 GRS-1 records are not supported for this form.
804 Upon completion, the XML buffer is returned
805 (type <literal>const char *</literal>) and length is stored in
806 <literal>*len</literal>.
809 <varlistentry><term><literal>opac</literal></term>
810 <listitem><para>OPAC information for record is returned in XML
811 if an OPAC record is present at the position given. If no
812 OPAC record is present, a NULL pointer is returned.
819 <ulink url="&url.marc21;">MARC21</ulink>
821 <ulink url="&url.marc8;">MARC-8</ulink>
822 character set encoding.
823 An application that wishes to display in Latin-1 would use
825 render; charset=marc8,iso-8859-1
828 <sect2 id="zoom.z3950.record.behavior">
829 <title>Z39.50 Protocol behavior</title>
831 The functions <function>ZOOM_resultset_record</function> and
832 <function>ZOOM_resultset_records</function> inspects the client-side
833 record cache. Records not found in cache are fetched using
835 The functions may block (and perform network I/O) - even though option
836 <literal>async</literal> is 1, because they return records objects.
837 (and there's no way to return records objects without retrieving them!).
840 There is a trick, however, in the usage of function
841 <function>ZOOM_resultset_records</function> that allows for
842 delayed retrieval (and makes it non-blocking). By using
843 a null pointer for <parameter>recs</parameter> you're indicating
844 you're not interested in getting records objects
845 <emphasis>now</emphasis>.
848 <sect2 id="zoom.sru.record.behavior">
849 <title>SRU Protocol behavior</title>
851 The ZOOM driver for SRU treats records returned by a SRU server
852 as if they where Z39.50 records with transfer syntax XML and
853 no element set name or database name.
857 <sect1 id="zoom.scan"><title>Scan</title>
859 This section describes an interface for Scan. Scan is not an
860 official part of the ZOOM model yet. The result of a scan operation
861 is the <literal>ZOOM_scanset</literal> which is a set of terms
862 returned by a target.
866 The Scan interface is supported for both Z39.50 and SRU.
870 ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
871 const char *startpqf);
873 ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
876 size_t ZOOM_scanset_size(ZOOM_scanset scan);
878 const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
879 size_t *occ, size_t *len);
881 const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
882 size_t *occ, size_t *len);
884 void ZOOM_scanset_destroy(ZOOM_scanset scan);
886 const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
889 void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
893 The scan set is created by function
894 <function>ZOOM_connection_scan</function> which performs a scan
895 operation on the connection using the specified
896 <parameter>startpqf</parameter>.
897 If the operation was successful, the size of the scan set can be
898 retrieved by a call to <function>ZOOM_scanset_size</function>.
899 Like result sets, the items are numbered 0,..size-1.
900 To obtain information about a particular scan term, call function
901 <function>ZOOM_scanset_term</function>. This function takes
902 a scan set offset <literal>pos</literal> and returns a pointer
903 to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
905 If present, the <literal>occ</literal> and <literal>len</literal>
906 are set to the number of occurrences and the length
907 of the actual term respectively.
908 <function>ZOOM_scanset_display_term</function> is similar to
909 <function>ZOOM_scanset_term</function> except that it returns
910 the <emphasis>display term</emphasis> rather than the raw term.
911 In a few cases, the term is different from display term. Always
912 use the display term for display and the raw term for subsequent
913 scan operations (to get more terms, next scan result, etc).
916 A scan set may be freed by a call to function
917 <function>ZOOM_scanset_destroy</function>.
918 Functions <function>ZOOM_scanset_option_get</function> and
919 <function>ZOOM_scanset_option_set</function> retrieves and sets
920 an option respectively.
924 The <parameter>startpqf</parameter> is a subset of PQF, namely
925 the Attributes+Term part. Multiple <literal>@attr</literal> can
926 be used. For example to scan in title (complete) phrases:
928 @attr 1=4 @attr 6=2 "science o"
933 The <function>ZOOM_connecton_scan1</function> is a newer and
934 more generic alternative to <function>ZOOM_connection_scan</function>
935 which allows to use both CQL and PQF for Scan.
938 <table frame="top" id="zoom.scanset.options">
939 <title>ZOOM Scan Set Options</title>
941 <colspec colwidth="4*" colname="name"></colspec>
942 <colspec colwidth="7*" colname="description"></colspec>
943 <colspec colwidth="2*" colname="default"></colspec>
946 <entry>Option</entry>
947 <entry>Description</entry>
948 <entry>Default</entry>
953 number</entry><entry>Number of Scan Terms requested in next scan.
954 After scan it holds the actual number of terms returned.
955 </entry><entry>10</entry></row>
957 position</entry><entry>Preferred Position of term in response
958 in next scan; actual position after completion of scan.
959 </entry><entry>1</entry></row>
961 stepSize</entry><entry>Step Size
962 </entry><entry>0</entry></row>
964 scanStatus</entry><entry>An integer indicating the Scan Status
966 </entry><entry>0</entry></row>
968 rpnCharset</entry><entry>Character set for RPN terms.
969 If this is set, ZOOM C will assume that the ZOOM application is
970 running UTF-8. Terms in RPN queries are then converted to the
971 rpnCharset. If this is unset, ZOOM C will not assume any encoding
972 of RPN terms and no conversion is performed.
973 </entry><entry>none</entry></row>
979 <sect1 id="zoom.extendedservices"><title>Extended Services</title>
981 ZOOM offers an interface to a subset of the Z39.50 extended services
982 as well as a few privately defined ones:
987 Z39.50 Item Order (ILL).
988 See <xref linkend="zoom.item.order"/>.
993 Record Update. This allows a client to insert, modify or delete
995 See <xref linkend="zoom.record.update"/>.
1000 Database Create. This a non-standard feature. Allows a client
1001 to create a database.
1002 See <xref linkend="zoom.database.create"/>.
1007 Database Drop. This a non-standard feature. Allows a client
1008 to delete/drop a database.
1009 See <xref linkend="zoom.database.drop"/>.
1014 Commit operation. This a non-standard feature. Allows a client
1015 to commit operations.
1016 See <xref linkend="zoom.commit"/>.
1019 <!-- all the ILL PDU options should go here too -->
1022 To create an extended service operation a <literal>ZOOM_package</literal>
1023 must be created. The operation is a five step operation. The
1024 package is created, package is configured by means of options,
1025 the package is send, result is inspected (by means of options),
1026 the package is destroyed.
1029 ZOOM_package ZOOM_connection_package(ZOOM_connection c,
1030 ZOOM_options options);
1032 const char *ZOOM_package_option_get(ZOOM_package p,
1034 void ZOOM_package_option_set(ZOOM_package p, const char *key,
1036 void ZOOM_package_send(ZOOM_package p, const char *type);
1038 void ZOOM_package_destroy(ZOOM_package p);
1041 The <function>ZOOM_connection_package</function> creates a
1042 package for the connection given using the options specified.
1045 Functions <function>ZOOM_package_option_get</function> and
1046 <function>ZOOM_package_option_set</function> gets and sets
1050 <function>ZOOM_package_send</function> sends
1051 the package the via connection specified in
1052 <function>ZOOM_connection_package</function>.
1053 The <parameter>type</parameter> specifies the actual extended service
1054 package type to be sent.
1057 <table frame="top" id="zoom.extendedservices.options">
1058 <title>Extended Service Common Options</title>
1060 <colspec colwidth="4*" colname="name"></colspec>
1061 <colspec colwidth="7*" colname="description"></colspec>
1062 <colspec colwidth="3*" colname="default"></colspec>
1065 <entry>Option</entry>
1066 <entry>Description</entry>
1067 <entry>Default</entry>
1072 <entry>package-name</entry>
1073 <entry>Extended Service Request package name. Must be specified
1074 as part of a request</entry>
1078 <entry>user-id</entry>
1079 <entry>User ID of Extended Service Package. Is a request option</entry>
1083 <entry>function</entry>
1085 Function of package - one of <literal>create</literal>,
1086 <literal>delete</literal>, <literal>modify</literal>. Is
1089 <entry><literal>create</literal></entry>
1092 <entry>waitAction</entry>
1094 Wait action for package. Possible values:
1095 <literal>wait</literal>, <literal>waitIfPossible</literal>,
1096 <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
1098 <entry><literal>waitIfPossible</literal></entry>
1101 <entry>targetReference</entry>
1103 Target Reference. This is part of the response as returned
1104 by the server. Read it after a successful operation.
1106 <entry><literal>none</literal></entry>
1112 <sect2 id="zoom.item.order"><title>Item Order</title>
1114 For Item Order, type must be set to <literal>itemorder</literal> in
1115 <function>ZOOM_package_send</function>.
1118 <table frame="top" id="zoom.item.order.options">
1119 <title>Item Order Options</title>
1121 <colspec colwidth="4*" colname="name"></colspec>
1122 <colspec colwidth="7*" colname="description"></colspec>
1123 <colspec colwidth="3*" colname="default"></colspec>
1126 <entry>Option</entry>
1127 <entry>Description</entry>
1128 <entry>Default</entry>
1133 <entry>contact-name</entry>
1134 <entry>ILL contact name</entry>
1138 <entry>contact-phone</entry>
1139 <entry>ILL contact phone</entry>
1143 <entry>contact-email</entry>
1144 <entry>ILL contact email</entry>
1148 <entry>itemorder-item</entry>
1149 <entry>Position for item (record) requested. An integer</entry>
1158 <sect2 id="zoom.record.update"><title>Record Update</title>
1160 For Record Update, type must be set to <literal>update</literal> in
1161 <function>ZOOM_package_send</function>.
1164 <table frame="top" id="zoom.record.update.options">
1165 <title>Record Update Options</title>
1167 <colspec colwidth="4*" colname="name"></colspec>
1168 <colspec colwidth="7*" colname="description"></colspec>
1169 <colspec colwidth="3*" colname="default"></colspec>
1172 <entry>Option</entry>
1173 <entry>Description</entry>
1174 <entry>Default</entry>
1179 <entry>action</entry>
1181 The update action. One of
1182 <literal>specialUpdate</literal>,
1183 <literal>recordInsert</literal>,
1184 <literal>recordReplace</literal>,
1185 <literal>recordDelete</literal>,
1186 <literal>elementUpdate</literal>.
1188 <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
1191 <entry>recordIdOpaque</entry>
1192 <entry>Opaque Record ID</entry>
1196 <entry>recordIdNumber</entry>
1197 <entry>Record ID number</entry>
1201 <entry>record</entry>
1202 <entry>The record itself</entry>
1206 <entry>recordOpaque</entry>
1207 <entry>Specifies an opaque record which is
1208 encoded as an ASN.1 ANY type with the OID as tiven by option
1209 <literal>syntax</literal> (see below).
1210 Option <literal>recordOpaque</literal> is an alternative
1211 to record - and <literal>record</literal> option (above) is
1212 ignored if recordOpaque is set. This option is only available in
1213 YAZ 3.0.35 and later and is meant to facilitate Updates with
1219 <entry>syntax</entry>
1220 <entry>The record syntax (transfer syntax). Is a string that
1221 is a known record syntax.
1223 <entry>no syntax</entry>
1226 <entry>databaseName</entry>
1227 <entry>Database from connection object</entry>
1228 <entry>Default</entry>
1231 <entry>correlationInfo.note</entry>
1232 <entry>Correlation Info Note (string)</entry>
1236 <entry>correlationInfo.id</entry>
1237 <entry>Correlation Info ID (integer)</entry>
1241 <entry>elementSetName</entry>
1242 <entry>Element Set for Record</entry>
1246 <entry>updateVersion</entry>
1247 <entry>Record Update version which holds one of the values
1248 1, 2 or 3. Each version has a distinct OID:
1250 (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
1252 (second version) and
1253 1.2.840.10003.9.5.1.1
1254 (<ulink url="&url.z39.50.extupdate3;">third and
1255 newest version</ulink>).
1265 <sect2 id="zoom.database.create"><title>Database Create</title>
1267 For Database Create, type must be set to <literal>create</literal> in
1268 <function>ZOOM_package_send</function>.
1271 <table frame="top" id="zoom.database.create.options">
1272 <title>Database Create Options</title>
1274 <colspec colwidth="4*" colname="name"></colspec>
1275 <colspec colwidth="7*" colname="description"></colspec>
1276 <colspec colwidth="3*" colname="default"></colspec>
1279 <entry>Option</entry>
1280 <entry>Description</entry>
1281 <entry>Default</entry>
1286 <entry>databaseName</entry>
1287 <entry>Database from connection object</entry>
1288 <entry>Default</entry>
1295 <sect2 id="zoom.database.drop"><title>Database Drop</title>
1297 For Database Drop, type must be set to <literal>drop</literal> in
1298 <function>ZOOM_package_send</function>.
1301 <table frame="top" id="zoom.database.drop.options">
1302 <title>Database Drop Options</title>
1304 <colspec colwidth="4*" colname="name"></colspec>
1305 <colspec colwidth="7*" colname="description"></colspec>
1306 <colspec colwidth="3*" colname="default"></colspec>
1309 <entry>Option</entry>
1310 <entry>Description</entry>
1311 <entry>Default</entry>
1316 <entry>databaseName</entry>
1317 <entry>Database from connection object</entry>
1318 <entry>Default</entry>
1325 <sect2 id="zoom.commit"><title>Commit Operation</title>
1327 For Commit, type must be set to <literal>commit</literal> in
1328 <function>ZOOM_package_send</function>.
1332 <sect2 id="zoom.extended.services.behavior">
1333 <title>Protocol behavior</title>
1335 All the extended services are Z39.50-only.
1339 The database create, drop and commit services are privately defined
1341 Refer to <filename>esadmin.asn</filename> in YAZ for the ASN.1
1348 <sect1 id="zoom.options"><title>Options</title>
1350 Most &zoom; objects provide a way to specify options to change behavior.
1351 From an implementation point of view a set of options is just like
1352 an associative array / hash.
1355 ZOOM_options ZOOM_options_create(void);
1357 ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
1359 void ZOOM_options_destroy(ZOOM_options opt);
1362 const char *ZOOM_options_get(ZOOM_options opt, const char *name);
1364 void ZOOM_options_set(ZOOM_options opt, const char *name,
1368 typedef const char *(*ZOOM_options_callback)
1369 (void *handle, const char *name);
1371 ZOOM_options_callback
1372 ZOOM_options_set_callback(ZOOM_options opt,
1373 ZOOM_options_callback c,
1377 <sect1 id="zoom.events"><title>Events</title>
1379 If you're developing non-blocking applications, you have to deal
1383 int ZOOM_event(int no, ZOOM_connection *cs);
1386 The <function>ZOOM_event</function> executes pending events for
1387 a number of connections. Supply the number of connections in
1388 <literal>no</literal> and an array of connections in
1389 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
1390 A pending event could be a sending a search, receiving a response,
1392 When an event has occurred for one of the connections, this function
1393 returns a positive integer <literal>n</literal> denoting that an event
1394 occurred for connection <literal>cs[n-1]</literal>.
1395 When no events are pending for the connections, a value of zero is
1397 To ensure that all outstanding requests are performed call this function
1398 repeatedly until zero is returned.
1401 If <function>ZOOM_event</function> returns and returns non-zero, the
1402 last event that occurred can be expected.
1405 int ZOOM_connection_last_event(ZOOM_connection cs);
1408 <function>ZOOM_connection_last_event</function> returns an event type
1409 (integer) for the last event.
1412 <table frame="top" id="zoom.event.ids">
1413 <title>ZOOM Event IDs</title>
1415 <colspec colwidth="4*" colname="name"></colspec>
1416 <colspec colwidth="7*" colname="description"></colspec>
1419 <entry>Event</entry>
1420 <entry>Description</entry>
1425 <entry>ZOOM_EVENT_NONE</entry>
1426 <entry>No event has occurred</entry>
1429 <entry>ZOOM_EVENT_CONNECT</entry>
1430 <entry>TCP/IP connect has initiated</entry>
1433 <entry>ZOOM_EVENT_SEND_DATA</entry>
1434 <entry>Data has been transmitted (sending)</entry>
1437 <entry>ZOOM_EVENT_RECV_DATA</entry>
1438 <entry>Data has been received)</entry>
1441 <entry>ZOOM_EVENT_TIMEOUT</entry>
1442 <entry>Timeout</entry>
1445 <entry>ZOOM_EVENT_UNKNOWN</entry>
1446 <entry>Unknown event</entry>
1449 <entry>ZOOM_EVENT_SEND_APDU</entry>
1450 <entry>An APDU has been transmitted (sending)</entry>
1453 <entry>ZOOM_EVENT_RECV_APDU</entry>
1454 <entry>An APDU has been received</entry>
1457 <entry>ZOOM_EVENT_RECV_RECORD</entry>
1458 <entry>A result-set record has been received</entry>
1461 <entry>ZOOM_EVENT_RECV_SEARCH</entry>
1462 <entry>A search result been received</entry>
1470 <!-- Keep this comment at the end of the file
1475 sgml-minimize-attributes:nil
1476 sgml-always-quote-attributes:t
1479 sgml-parent-document: "yaz.xml"
1480 sgml-local-catalogs: nil
1481 sgml-namecase-general:t