1 <!-- $Id: zoom.xml,v 1.4 2001-10-24 21:24:38 quinn 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.search"><title>Search objects</title>
159 Search objects defines how result sets are obtained. They
163 Z3950_search Z3950_search_create(void);
165 void Z3950_search_destroy(Z3950_search s);
167 int Z3950_search_prefix(Z3950_search s, const char *str);
169 int Z3950_search_sortby(Z3950_search s, const char *criteria);
172 Create search objects using <function>Z3950_search_create</function>
173 and destroy them by calling <function>Z3950_search_destroy</function>.
174 RPN-queries can be specified in <link linkend="PQF">PQF</link>
175 notation by using the
176 function <function>Z3950_search_prefix</function>. More
177 query types will be added later, such as
178 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
179 etc. In addition to a search, a sort criteria may be set. Function
180 <function>Z3950_search_sortby</function> specifies a
181 sort criteria using the same string notation for sort as offered by
182 the <link linkend="sortspec">YAZ client</link>.
185 <sect1 id="zoom.resultsets"><title>Result sets</title>
187 The result set object is a container for records returned from
192 Z3950_resultset Z3950_connection_search(Z3950_connection,
195 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
198 void Z3950_resultset_destroy(Z3950_resultset r);
201 Function <function>Z3950_connection_search</function> creates
202 a result set given a connection - and search object.
203 Destroy a result set by calling
204 <function>Z3950_resultset_destroy</function>.
205 Simple clients using PQF only may use function
206 <function>Z3950_connection_search_pqf</function> instead.
209 const char *Z3950_resultset_option (Z3950_resultset r,
213 int Z3950_resultset_size (Z3950_resultset r);
215 void *Z3950_resultset_get (Z3950_resultset s, int pos,
216 const char *type, int *len);
219 Function <function>Z3950_resultset_options</function> sets or
220 modifies an option for a result set similar to
221 <function>Z3950_connection_option</function>.
224 The number of hits also called result-count is returned by
225 function <function>Z3950_resultset_size</function>.
228 Function <function>Z3950_resultset_get</function> is similar to
229 <link linkend="zoom.record.get">
230 <function>Z3950_record_get</function></link> but
231 instead of operating on a record object, it operates on a record on
232 a given offset within a result set.
234 <table frame="top"><title>ZOOM Result set Options</title>
236 <colspec colwidth="4*" colname="name"></colspec>
237 <colspec colwidth="7*" colname="description"></colspec>
238 <colspec colwidth="2*" colname="default"></colspec>
241 <entry>Option</entry>
242 <entry>Description</entry>
243 <entry>Default</entry>
248 piggyback</entry><entry>True (1) if piggyback should be
249 used in searches; false (0) if not.
250 </entry><entry>1</entry></row>
252 start</entry><entry>Offset of first record we wish to
253 retrieve from the target. Note first record has offset 0
254 unlike the protocol specifications where first record has position
256 </entry><entry>0</entry></row>
258 count</entry><entry>Number of records to be retrieved.
259 </entry><entry>0</entry></row>
261 elementSetName</entry><entry>Element-Set name of records.
262 Most targets should honor element set name <literal>B</literal>
263 and <literal>F</literal> for brief and full respectively.
264 </entry><entry>none</entry></row>
266 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
267 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
268 </entry><entry>none</entry></row>
270 databaseName</entry><entry>One or more database names
271 separated by character plus (<literal>+</literal>).
272 </entry><entry>Default</entry></row>
277 <sect1 id="zoom.records"><title>Records</title>
279 A record object is a retrival record on the client side -
280 created from result sets.
283 void Z3950_resultset_records (Z3950_resultset r,
286 Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
288 void *Z3950_record_get (Z3950_record rec, const char *type,
291 void Z3950_record_destroy (Z3950_record rec);
294 Records are created by functions
295 <function>Z3950_resultset_records</function> or
296 <function>Z3950_resultset_record</function>
297 and destroyed by <function>Z3950_record_destroy</function>.
300 A single record is created and returned by function
301 <function>Z3950_resultset_record</function> that takes a
302 position as argument. First record has position zero.
303 If no record could be obtained <literal>NULL</literal> is returned.
306 Function <function>Z3950_resultset_records</function> retrieves
307 a number of records from a result set. Options <literal>start</literal>
308 and <literal>count</literal> specifies the range of records to
309 be returned. Upon completion <literal>recs[0], ..recs[*cnt]</literal>
310 holds record objects for the records. These array of records
311 <literal>recs</literal> should be allocate prior to calling
312 <function>Z3950_resultset_records</function>. Note that for
313 records that couldn't be retrieved from the target
314 <literal>recs[ ..]</literal> is <literal>NULL</literal>.
316 <para id="zoom.record.get">
317 In order to extract information about a single record,
318 <function>Z3950_record_get</function> is provided. The
319 function returns a pointer to certain record information. The
320 nature (type) of the pointer depends on the <function>type</function>
321 given. In addition for certain types, the length
322 <literal>len</literal> passed will be set to the size in bytes of
323 the returned information. The types <literal>database</literal>,
324 <literal>syntax</literal> and <literal>render</literal> are
325 supported. More will be added later.
328 <sect1 id="zoom.options"><title>Options</title>
330 Most objects in &zoom; allow you to specify options to change
331 default behaviour. From an implementation point of view a set of options
332 is just like an associate array / hash array, etc.
335 Z3950_options Z3950_options_create (void);
337 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
339 void Z3950_options_destroy (Z3950_options opt);
342 const char *Z3950_options_get (Z3950_options opt, const char *name);
344 void Z3950_options_set (Z3950_options opt, const char *name,
348 typedef const char *(*Z3950_options_callback)
349 (void *handle, const char *name);
351 Z3950_options_callback
352 Z3950_options_set_callback (Z3950_options opt,
353 Z3950_options_callback c,
357 <sect1 id="zoom.events"><title>Events</title>
359 If you're developing non-blocking applications, you have to deal
363 int Z3950_event (int no, Z3950_connection *cs);
366 The <function>Z3950_event</function> executes pending events for
367 a number of connections. Supply the number of connections in
368 <literal>no</literal> and an array of connections in
369 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
370 A pending event could be a sending a search, receiving a response,
372 When an event has a occured for one of the connections, this function
373 returns a positive integer <literal>n</literal> denoting that an event
374 occurred for connection <literal>cs[n-1]</literal>.
375 When no events are pending for the connections, a value of zero is
377 To make sure all outstanding requests are performed call this function
378 repeatedly until zero is returned.
383 <!-- Keep this comment at the end of the file
388 sgml-minimize-attributes:nil
389 sgml-always-quote-attributes:t
392 sgml-parent-document: "yaz.xml"
393 sgml-local-catalogs: "../../docbook/docbook.cat"
394 sgml-namecase-general:t