1 <!-- $Id: zoom.xml,v 1.1 2001-10-23 21:00:19 adam Exp $ -->
2 <chapter><title>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 apparanet
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><title>Connections</title>
42 <para>The connection object Z3950_connection describes
43 the connection between your client and a server.
46 #include <yaz/zoom.h>
48 Z3950_connection Z3950_connection_new (const char *host, int portnum);
50 Z3950_connection Z3950_connection_create (Z3950_options options);
52 void Z3950_connection_connect(Z3950_connection c, const char *host,
54 void Z3950_connection_destroy (Z3950_connection c);
57 Connection objects are created with either function
58 <function>Z3950_connection_new</function> or
59 <function>Z3950_connection_create</function>.
60 The former both creates and attempts to establishes a network
61 connection with the target. The latter doesn't establishes
62 a connection immediately, thus allowing you to set specify options
63 before establishing network connection using function
64 <function>Z3950_connection_connect</function>.
65 If the portnumber, <literal>portnum</literal>, is zero, the
66 <literal>host</literal> is consulted for a port specification.
67 If no port is given, 210 is used. A colon denotes the beginning of
68 a port number in the host string. If the host string includes a
69 slash that specifies a database for the connection.
72 Connection objects should be destroyed using function
73 <function>Z3950_connection_destroy</function>.
76 const char *Z3950_connection_option (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.
91 const char *Z3950_connection_host (Z3950_connection c);
95 Function <function>Z3950_connection_host</function> returns
96 the host for the connection as specified in either a call to
97 <function>Z3950_connection_new</function> or
98 <function>Z3950_connection_connect</function>.
99 This function returns <literal>NULL</literal> if host isn't
100 set for the connection.
103 int Z3950_connection_error (Z3950_connection c, const char **cp,
104 const char **addinfo);
107 Use <function>Z3950_connection_error</function> to check for
108 errors for the last operation(s) performed. The function returns
109 zero if no errors occurred; non-zero otherwise indicating the error.
110 Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
111 holds messages for the error and additional-info if passed as
112 non-<literal>NULL</literal>.
115 <sect1><title>Search objects</title>
117 Search objects defines how result sets are obtained. They
121 Z3950_search Z3950_search_create(void);
123 void Z3950_search_destroy(Z3950_search s);
125 int Z3950_search_prefix(Z3950_search s, const char *str);
127 int Z3950_search_sortby(Z3950_search s, const char *criteria);
130 Create search objects using <function>Z3950_search_create</function>
131 and destroy them by calling <function>Z3950_search_destroy</function>.
132 RPN-queries can be specified in PQF notation by using the
133 function <function>Z3950_search_prefix</function>. More
134 query types will be added later, such as CCL to RPN-mapping, CCL
136 In addition to a search a sort critieria may be set. Function
137 <function>Z3950_search_sortby</function> specifies a sort
138 criteria using the same string notation for sort as offered by
142 <sect1><title>Result sets</title>
144 The result set describes a collection of records obtained from
148 Z3950_resultset Z3950_connection_search(Z3950_connection,
151 Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
154 void Z3950_resultset_destroy(Z3950_resultset r);
157 Function <function>Z3950_connection_search</function> creates
158 a result set given a connection - and search object.
159 Destroy a result set by calling
160 <function>Z3950_resultset_destroy</function>.
161 Simple clients using YAZ' prefix query format may use
162 function <function>Z3950_connection_search_pqf</function>
166 const char *Z3950_resultset_option (Z3950_resultset r,
170 int Z3950_resultset_size (Z3950_resultset r);
172 void *Z3950_resultset_get (Z3950_resultset s, int pos,
173 const char *type, int *len);
174 void Z3950_resultset_records (Z3950_resultset r,
179 Description of result sets here.
182 <sect1><title>Records</title>
184 A record object is a retrival record on the client side -
185 created from result sets.
188 Z3950_record Z3950_resultset_record (Z3950_resultset s, int pos);
190 Z3950_record Z3950_resultset_record_immediate (Z3950_resultset s,
193 void *Z3950_record_get (Z3950_record rec, const char *type,
196 void Z3950_record_destroy (Z3950_record rec);
199 <sect1><title>Options</title>
201 Most objects in &zoom; allows you to specify options to change
202 behaviour. From an implementation point of view a set of options
203 is just like an associate array / hash array, etc.
206 Z3950_options Z3950_options_create (void);
208 Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
210 void Z3950_options_destroy (Z3950_options opt);
213 const char *Z3950_options_get (Z3950_options opt, const char *name);
215 void Z3950_options_set (Z3950_options opt, const char *name,
219 typedef const char *(*Z3950_options_callback)
220 (void *handle, const char *name);
222 Z3950_options_callback
223 Z3950_options_set_callback (Z3950_options opt,
224 Z3950_options_callback c,
228 <sect1><title>Events</title>
230 If you're developing non-blocking applications you have to deal
234 int Z3950_event (int no, Z3950_connection *cs);
239 <!-- Keep this comment at the end of the file
244 sgml-minimize-attributes:nil
245 sgml-always-quote-attributes:t
248 sgml-parent-document: "yaz.xml"
249 sgml-local-catalogs: "../../docbook/docbook.cat"
250 sgml-namecase-general:t