1 <!-- $Id: zoom.xml,v 1.6 2001-11-06 17:05:19 adam Exp $ -->
2 <chapter id="zoom"><title>Building clients with ZOOM</title>
5 &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
6 an initiative started by Mike Taylor (Mike is from the UK, which
7 explains the peculiar name of the model). The goal of &zoom; is to
8 provide a common Z39.50 client API not bound to a particular
9 programming language or toolkit.
12 The lack of a simple Z39.50 client API for &yaz; has become more
13 and more apparent over time. So when the first ZOOM specification
15 an implementation for &yaz; was quickly developed. For the first time, it is
16 now as easy (or easier!) to develop clients than servers with &yaz;. This
17 chapter describes the ZOOM C binding. Before going futher, please
18 reconsider whether C is the right programming language for the job.
19 There are other language bindings available for &yaz;, and still
21 are in active development. See the ZOOM website at
22 <ulink url="http://zoom.z3950.org/">zoom.z3950.org</ulink> for
27 In order to fully understand this chapter you should read and
28 try the example programs <literal>zoomtst1.c</literal>,
29 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
34 The C language misses many features found in object oriented languages
35 such as C++, Java, etc. For example, you'll have to manually,
36 destroy all objects you create, even though you may think of them as
37 temporary. Most objects has a <literal>_create</literal> - and a
38 <literal>_destroy</literal> variant.
39 All objects are in fact pointers to internal stuff, but you don't see
40 that because of typedefs. All destroy methods should gracefully ignore a
41 <literal>NULL</literal> pointer.
43 <sect1 id="zoom.connections"><title>Connections</title>
45 <para>The Connection object is a session with a target.
48 #include <yaz/zoom.h>
50 Z3950_connection Z3950_connection_new (const char *host, int portnum);
52 Z3950_connection Z3950_connection_create (Z3950_options options);
54 void Z3950_connection_connect(Z3950_connection c, const char *host,
56 void Z3950_connection_destroy (Z3950_connection c);
59 Connection objects are created with either function
60 <function>Z3950_connection_new</function> or
61 <function>Z3950_connection_create</function>.
62 The former creates and automatically attempts to establish a network
63 connection with the target. The latter doesn't establish
64 a connection immediately, thus allowing you to specify options
65 before establishing network connection using the function
66 <function>Z3950_connection_connect</function>.
67 If the portnumber, <literal>portnum</literal>, is zero, the
68 <literal>host</literal> is consulted for a port specification.
69 If no port is given, 210 is used. A colon denotes the beginning of
70 a port number in the host string. If the host string includes a
71 slash, the following part specifies a database for the connection.
74 Connection objects should be destroyed using the function
75 <function>Z3950_connection_destroy</function>.
78 const char *Z3950_connection_option (Z3950_connection c,
81 const char *Z3950_connection_host (Z3950_connection c);
84 The <function>Z3950_connection_option</function> allows you to
85 inspect or set an option given by <parameter>key</parameter>
87 If <parameter>val</parameter> is non-<literal>NULL</literal> that
88 holds the new value for option.
89 Otherwise, if <parameter>val</parameter> is
90 <literal>NULL</literal>,
91 the option is unchanged.
92 The function returns the previous value of the option.
94 <table frame="top"><title>ZOOM Connection Options</title>
96 <colspec colwidth="4*" colname="name"></colspec>
97 <colspec colwidth="7*" colname="description"></colspec>
98 <colspec colwidth="3*" colname="default"></colspec>
101 <entry>Option</entry>
102 <entry>Description</entry>
103 <entry>Default</entry>
108 implementationName</entry><entry>Name of Your client
109 </entry><entry>none</entry></row>
111 user</entry><entry>Authentication user name
112 </entry><entry>none</entry></row>
114 group</entry><entry>Authentication group name
115 </entry><entry>none</entry></row>
117 pass</entry><entry>Authentication password
118 </entry><entry>none</entry></row>
120 proxy</entry><entry>Proxy host
121 </entry><entry>none</entry></row>
123 async</entry><entry>If true (1) the connection operates in
124 asynchronous operation which means that all calls are non-blocking
125 except <function>Z3950_event</function>.
126 </entry><entry>0</entry></row>
128 maximumRecordSize</entry><entry> Maximum size of single record.
129 </entry><entry>1 MB</entry></row>
131 preferredMessageSize</entry><entry> Maximum size of multiple records.
132 </entry><entry>1 MB</entry></row>
137 Function <function>Z3950_connection_host</function> returns
138 the host for the connection as specified in a call to
139 <function>Z3950_connection_new</function> or
140 <function>Z3950_connection_connect</function>.
141 This function returns <literal>NULL</literal> if host isn't
142 set for the connection.
145 int Z3950_connection_error (Z3950_connection c, const char **cp,
146 const char **addinfo);
149 Use <function>Z3950_connection_error</function> to check for
150 errors for the last operation(s) performed. The function returns
151 zero if no errors occurred; non-zero otherwise indicating the error.
152 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
153 holds messages for the error and additional-info if passed as
154 non-<literal>NULL</literal>.
157 <sect1 id="zoom.query"><title>Queries</title>
159 Query objects represents queries.
162 Z3950_query Z3950_query_create(void);
164 void Z3950_query_destroy(Z3950_query q);
166 int Z3950_query_prefix(Z3950_query q, const char *str);
168 int Z3950_query_sortby(Z3950_query q, const char *criteria);
171 Create query objects using <function>Z3950_query_create</function>
172 and destroy them by calling <function>Z3950_query_destroy</function>.
173 RPN-queries can be specified in <link linkend="PQF">PQF</link>
174 notation by using the
175 function <function>Z3950_query_prefix</function>. More
176 query types will be added later, such as
177 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
178 etc. In addition to a search, a sort criteria may be set. Function
179 <function>Z3950_query_sortby</function> specifies a
180 sort criteria using the same string notation for sort as offered by
181 the <link linkend="sortspec">YAZ client</link>.
184 <sect1 id="zoom.resultsets"><title>Result sets</title>
186 The result set object is a container for records returned from
190 Z3950_resultset Z3950_connection_search(Z3950_connection,
193 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
196 void Z3950_resultset_destroy(Z3950_resultset r);
199 Function <function>Z3950_connection_search</function> creates
200 a result set given a connection and query.
201 Destroy a result set by calling
202 <function>Z3950_resultset_destroy</function>.
203 Simple clients may using PQF only may use function
204 <function>Z3950_connection_search_pqf</function> in which case
205 creating query objects is not necessary.
208 const char *Z3950_resultset_option (Z3950_resultset r,
212 int Z3950_resultset_size (Z3950_resultset r);
214 void *Z3950_resultset_get (Z3950_resultset s, size_t pos,
215 const char *type, size_t *len);
218 Function <function>Z3950_resultset_options</function> sets or
219 modifies an option for a result set similar to
220 <function>Z3950_connection_option</function>.
223 The number of hits also called result-count is returned by
224 function <function>Z3950_resultset_size</function>.
227 Function <function>Z3950_resultset_get</function> is similar to
228 <link linkend="zoom.record.get">
229 <function>Z3950_record_get</function></link> but
230 instead of operating on a record object, it operates on a record on
231 a given offset within a result set.
233 <table frame="top"><title>ZOOM Result set Options</title>
235 <colspec colwidth="4*" colname="name"></colspec>
236 <colspec colwidth="7*" colname="description"></colspec>
237 <colspec colwidth="2*" colname="default"></colspec>
240 <entry>Option</entry>
241 <entry>Description</entry>
242 <entry>Default</entry>
247 piggyback</entry><entry>True (1) if piggyback should be
248 used in searches; false (0) if not.
249 </entry><entry>1</entry></row>
251 start</entry><entry>Offset of first record to be
252 retrieved from target. First record has offset 0 unlike the
253 protocol specifications where first record has position 1.
254 </entry><entry>0</entry></row>
256 count</entry><entry>Number of records to be retrieved.
257 </entry><entry>0</entry></row>
259 elementSetName</entry><entry>Element-Set name of records.
260 Most targets should honor element set name <literal>B</literal>
261 and <literal>F</literal> for brief and full respectively.
262 </entry><entry>none</entry></row>
264 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
265 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
266 </entry><entry>none</entry></row>
268 smallSetUpperBound</entry><entry>If hits is less than or equal to this
269 value, then target will return all records using small element set name
270 </entry><entry>0</entry></row>
272 largeSetLowerBound</entry><entry>If hits is greator than this value, the target
273 will return no records.
274 </entry><entry>1</entry></row>
276 mediumSetPresentNumber</entry><entry>This value represents
277 the number of records to be returned as part of a search when when
278 hits is less than or equal to large set lower bound and if hits
279 is greator than small set upper bound.
280 </entry><entry>0</entry></row>
282 smallSetElementSetName</entry><entry>
283 The element set name to be used for small result sets.
284 </entry><entry>none</entry></row>
286 mediumSetElementSetName</entry><entry>
287 The element set name to be for medium-sized result sets.
288 </entry><entry>none</entry></row>
290 databaseName</entry><entry>One or more database names
291 separated by character plus (<literal>+</literal>).
292 </entry><entry>Default</entry></row>
297 <sect1 id="zoom.records"><title>Records</title>
299 A record object is a retrival record on the client side -
300 created from result sets.
303 void Z3950_resultset_records (Z3950_resultset r,
305 size_t start, size_t count);
306 Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos);
308 void *Z3950_record_get (Z3950_record rec, const char *type,
311 void Z3950_record_destroy (Z3950_record rec);
314 Records are created by functions
315 <function>Z3950_resultset_records</function> or
316 <function>Z3950_resultset_record</function>
317 and destroyed by <function>Z3950_record_destroy</function>.
320 A single record is created and returned by function
321 <function>Z3950_resultset_record</function> that takes a
322 position as argument. First record has position zero.
323 If no record could be obtained <literal>NULL</literal> is returned.
326 Function <function>Z3950_resultset_records</function> retrieves
327 a number of records from a result set. Parameter <literal>start</literal>
328 and <literal>count</literal> specifies the range of records to
329 be returned. Upon completion array <literal>recs[0], ..recs[count-1]</literal>
330 holds record objects for the records. The array of records
331 <literal>recs</literal> should be allocate prior to calling
332 <function>Z3950_resultset_records</function>. Note that for those
333 records that couldn't be retrieved from the target
334 <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
336 <para id="zoom.record.get">
337 In order to extract information about a single record,
338 <function>Z3950_record_get</function> is provided. The
339 function returns a pointer to certain record information. The
340 nature (type) of the pointer depends on the <function>type</function>
341 given. In addition for certain types, the length
342 <literal>len</literal> passed will be set to the size in bytes of
343 the returned information. The types <literal>database</literal>,
344 <literal>syntax</literal> and <literal>render</literal> are
345 supported. More will be added later.
348 <sect1 id="zoom.options"><title>Options</title>
350 Most &zoom; objects provide a way to specify options to default behaviour.
351 From an implementation point of view a set of options is just like
352 an associate array / hash array, etc.
355 Z3950_options Z3950_options_create (void);
357 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
359 void Z3950_options_destroy (Z3950_options opt);
362 const char *Z3950_options_get (Z3950_options opt, const char *name);
364 void Z3950_options_set (Z3950_options opt, const char *name,
368 typedef const char *(*Z3950_options_callback)
369 (void *handle, const char *name);
371 Z3950_options_callback
372 Z3950_options_set_callback (Z3950_options opt,
373 Z3950_options_callback c,
377 <sect1 id="zoom.events"><title>Events</title>
379 If you're developing non-blocking applications, you have to deal
383 int Z3950_event (int no, Z3950_connection *cs);
386 The <function>Z3950_event</function> executes pending events for
387 a number of connections. Supply the number of connections in
388 <literal>no</literal> and an array of connections in
389 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
390 A pending event could be a sending a search, receiving a response,
392 When an event has a occured for one of the connections, this function
393 returns a positive integer <literal>n</literal> denoting that an event
394 occurred for connection <literal>cs[n-1]</literal>.
395 When no events are pending for the connections, a value of zero is
397 To make sure all outstanding requests are performed call this function
398 repeatedly until zero is returned.
403 <!-- Keep this comment at the end of the file
408 sgml-minimize-attributes:nil
409 sgml-always-quote-attributes:t
412 sgml-parent-document: "yaz.xml"
413 sgml-local-catalogs: nil
414 sgml-namecase-general:t