1 <!-- $Id: zoom.xml,v 1.3 2001-10-24 20:12:36 adam Exp $ -->
2 <chapter id="zoom"><title>Building clients with ZOOM</title>
5 &zoom; is an acronym for Z39.50 Object Oriented Model and is
6 an initiative started by Mike Taylor. The goal of &zoom; is to
7 provide a common Z39.50 client API not bound to a particular
8 programming language or toolkit.
11 The lack of a simple Z39.50 client API for &yaz; was more apparent
12 than ever. So, when the first ZOOM specification was available
13 an implementation for &yaz; was developed. For the first time, it is
14 now easier to develop clients than servers with &yaz;. This
15 chapter describes the ZOOM C binding. Before going futher
16 reconsider whether C is still the programming language of your
17 choice. There are other language bindings available and others
18 are in active development. See the ZOOM website at
19 <ulink url="http://zoom.z3950.org/">zoom.z3950.org</ulink> for
24 In order to fully understand this chapter you should read and
25 try the example programs <literal>zoomtst1.c</literal>,
26 <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
31 The C language misses many features found in object oriented languages
32 such as C++, Java, etc. For example, you'll have to, manually,
33 destroy all objects you create, even though you may think of them as
34 temporary. Most objects has a <literal>_create</literal> - and a
35 <literal>_destroy</literal> variant.
36 All objects are in fact pointers to internal stuff, but you don't see
37 that because of typedefs. All destroy methods should gracefully ignore a
38 <literal>NULL</literal> pointer.
40 <sect1 id="zoom.connections"><title>Connections</title>
42 <para>The Connection object is a session with a target.
45 #include <yaz/zoom.h>
47 Z3950_connection Z3950_connection_new (const char *host, int portnum);
49 Z3950_connection Z3950_connection_create (Z3950_options options);
51 void Z3950_connection_connect(Z3950_connection c, const char *host,
53 void Z3950_connection_destroy (Z3950_connection c);
56 Connection objects are created with either function
57 <function>Z3950_connection_new</function> or
58 <function>Z3950_connection_create</function>.
59 The former both creates and attempts to establishes a network
60 connection with the target. The latter doesn't establishes
61 a connection immediately, thus allowing you to set specify options
62 before establishing network connection using function
63 <function>Z3950_connection_connect</function>.
64 If the portnumber, <literal>portnum</literal>, is zero, the
65 <literal>host</literal> is consulted for a port specification.
66 If no port is given, 210 is used. A colon denotes the beginning of
67 a port number in the host string. If the host string includes a
68 slash that specifies a database for the connection.
71 Connection objects should be destroyed using function
72 <function>Z3950_connection_destroy</function>.
75 const char *Z3950_connection_option (Z3950_connection c,
78 const char *Z3950_connection_host (Z3950_connection c);
81 The <function>Z3950_connection_option</function> allows you to
82 inspect or set an option given by <parameter>key</parameter>
84 If <parameter>val</parameter> is non-<literal>NULL</literal> that
85 holds the new value for option.
86 Otherwise, if <parameter>val</parameter> is <literal>NULL</literal>
87 the option is unchanged.
88 The function returns the previous value of the option.
90 <table frame="top"><title>ZOOM Connection Options</title>
92 <colspec colwidth="4*" colname="name"></colspec>
93 <colspec colwidth="7*" colname="description"></colspec>
94 <colspec colwidth="3*" colname="default"></colspec>
98 <entry>Description</entry>
99 <entry>Default</entry>
104 implementationName</entry><entry>Name of Your client
105 </entry><entry>none</entry></row>
107 user</entry><entry>Authentication user name
108 </entry><entry>none</entry></row>
110 group</entry><entry>Authentication group name
111 </entry><entry>none</entry></row>
113 pass</entry><entry>Authentication password
114 </entry><entry>none</entry></row>
116 proxy</entry><entry>Proxy host
117 </entry><entry>none</entry></row>
119 async</entry><entry>If true (1) the connection operates in
120 asynchronous operatio which means that all calls are non-blocking
121 except <function>Z3950_event</function>.
122 </entry><entry>0</entry></row>
124 maximumRecordSize</entry><entry> Maximum size of single record.
125 </entry><entry>1 MB</entry></row>
127 preferredMessageSize</entry><entry> Maximum size of multiple records.
128 </entry><entry>1 MB</entry></row>
133 Function <function>Z3950_connection_host</function> returns
134 the host for the connection as specified in a call to
135 <function>Z3950_connection_new</function> or
136 <function>Z3950_connection_connect</function>.
137 This function returns <literal>NULL</literal> if host isn't
138 set for the connection.
141 int Z3950_connection_error (Z3950_connection c, const char **cp,
142 const char **addinfo);
145 Use <function>Z3950_connection_error</function> to check for
146 errors for the last operation(s) performed. The function returns
147 zero if no errors occurred; non-zero otherwise indicating the error.
148 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
149 holds messages for the error and additional-info if passed as
150 non-<literal>NULL</literal>.
153 <sect1 id="zoom.search"><title>Search objects</title>
155 Search objects defines how result sets are obtained. They
159 Z3950_search Z3950_search_create(void);
161 void Z3950_search_destroy(Z3950_search s);
163 int Z3950_search_prefix(Z3950_search s, const char *str);
165 int Z3950_search_sortby(Z3950_search s, const char *criteria);
168 Create search objects using <function>Z3950_search_create</function>
169 and destroy them by calling <function>Z3950_search_destroy</function>.
170 RPN-queries can be specified in <link linkend="PQF">PQF</link>
171 notation by using the
172 function <function>Z3950_search_prefix</function>. More
173 query types will be added later, such as
174 <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
175 etc. In addition to a search, a sort critieria may be set. Function
176 <function>Z3950_search_sortby</function> specifies a
177 sort criteria using the same string notation for sort as offered by
178 the <link linkend="sortspec">YAZ client</link>.
181 <sect1 id="zoom.resultsets"><title>Result sets</title>
183 The result set object is a container for records returned from
188 Z3950_resultset Z3950_connection_search(Z3950_connection,
191 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
194 void Z3950_resultset_destroy(Z3950_resultset r);
197 Function <function>Z3950_connection_search</function> creates
198 a result set given a connection - and search object.
199 Destroy a result set by calling
200 <function>Z3950_resultset_destroy</function>.
201 Simple clients using PQF only may use function
202 <function>Z3950_connection_search_pqf</function> instead.
205 const char *Z3950_resultset_option (Z3950_resultset r,
209 int Z3950_resultset_size (Z3950_resultset r);
211 void *Z3950_resultset_get (Z3950_resultset s, int pos,
212 const char *type, int *len);
215 Function <function>X3950_resultset_options</function> sets or
216 modifies an option for a result set similar to
217 <function>Z3950_connection_option</function>.
220 The number of hits also called result-count is returned by
221 function <function>Z3950_resultset_size</function>.
224 Function <function>Z3950_resultset_get</function> is similar to
225 <link linkend="zoom.record.get">
226 <function>Z3950_record_get</function></link> but
227 instead of operating on a record object it operates on a record on
228 a given offset within a result set.
230 <table frame="top"><title>ZOOM Result set Options</title>
232 <colspec colwidth="4*" colname="name"></colspec>
233 <colspec colwidth="7*" colname="description"></colspec>
234 <colspec colwidth="2*" colname="default"></colspec>
237 <entry>Option</entry>
238 <entry>Description</entry>
239 <entry>Default</entry>
244 piggyback</entry><entry>True (1) if piggyback should be
245 used in searches; false (0) if not.
246 </entry><entry>1</entry></row>
248 start</entry><entry>Offset of first record we wish to
249 retrieve from the target. Note first record has offset 0
250 unlike the protocol specifications where first record has position
252 </entry><entry>0</entry></row>
254 count</entry><entry>Number of records to be retrieved.
255 </entry><entry>0</entry></row>
257 elementSetName</entry><entry>Element-Set name of records.
258 Most targets should honor element set name <literal>B</literal>
259 and <literal>F</literal> for brief and full respectively.
260 </entry><entry>none</entry></row>
262 preferredRecordSyntax</entry><entry>Preferred Syntax, such as
263 <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
264 </entry><entry>none</entry></row>
266 databaseName</entry><entry>One or more database names
267 separated by character plus (<literal>+</literal>).
268 </entry><entry>Default</entry></row>
273 <sect1 id="zoom.records"><title>Records</title>
275 A record object is a retrival record on the client side -
276 created from result sets.
279 void Z3950_resultset_records (Z3950_resultset r,
282 Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
284 void *Z3950_record_get (Z3950_record rec, const char *type,
287 void Z3950_record_destroy (Z3950_record rec);
290 Records are created by functions
291 <function>Z3950_resultset_records</function> or
292 <function>Z3950_resultset_record</function>
293 and destroyed by <function>Z3950_record_destroy</function>.
296 A single record is created and returned by function
297 <function>Z3950_resultset_record</function> that takes a
298 position as argument. First record has position zero.
299 If no record could be obtained <literal>NULL</literal> is returned.
302 Function <function>Z39_resultset_records</function> retrieves
303 a number of records from a result set. Options <literal>start</literal>
304 and <literal>count</literal> specifies the range of records to
305 be returned. Upon completion <literal>recs[0], ..recs[*cnt]</literal>
306 holds record objects for the records. These array of records
307 <literal>recs</literal> should be allocate prior to calling
308 <function>Z3950_resultset_records</function>. Note that for
309 records that couldn't be retrieved from the target
310 <literal>recs[ ..]</literal> is <literal>NULL</literal>.
312 <para id="zoom.record.get">
313 In order to extract information about a single record,
314 <function>Z3950_record_get</function> is provided. The
315 function returns a pointer to certain record information. The
316 nature (type) of the pointer depends on the <function>type</function>
317 given. In addition for certain types, the length
318 <literal>len</literal> passed will be set to the size in bytes of
319 the returned information. The types <literal>database</literal>,
320 <literal>syntax</literal> and <literal>render</literal> are
321 supported. More will be added later.
324 <sect1 id="zoom.options"><title>Options</title>
326 Most objects in &zoom; allows you to specify options to change
327 behaviour. From an implementation point of view a set of options
328 is just like an associate array / hash array, etc.
331 Z3950_options Z3950_options_create (void);
333 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
335 void Z3950_options_destroy (Z3950_options opt);
338 const char *Z3950_options_get (Z3950_options opt, const char *name);
340 void Z3950_options_set (Z3950_options opt, const char *name,
344 typedef const char *(*Z3950_options_callback)
345 (void *handle, const char *name);
347 Z3950_options_callback
348 Z3950_options_set_callback (Z3950_options opt,
349 Z3950_options_callback c,
353 <sect1 id="zoom.events"><title>Events</title>
355 If you're developing non-blocking applications you have to deal
359 int Z3950_event (int no, Z3950_connection *cs);
362 The <function>Z3950_event</function> executes pending events for
363 a number of connections. Supply the number of connections in
364 <literal>no</literal> and an array of connections in
365 <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
366 A pending event could be a sending a search, receiving a response,
368 When an event has a occured for one of the connections this function
369 returns a positive integer <literal>n</literal> denoting that an event
370 occurred for connection <literal>cs[n-1]</literal>.
371 When no events are pending for the connections a value of zero is
373 To make sure all outstanding requests are performed call this function
374 repeatedly until zero is returned.
379 <!-- Keep this comment at the end of the file
384 sgml-minimize-attributes:nil
385 sgml-always-quote-attributes:t
388 sgml-parent-document: "yaz.xml"
389 sgml-local-catalogs: "../../docbook/docbook.cat"
390 sgml-namecase-general:t