1 <chapter id="introduction"><title>Introduction</title>
4 &yaz; is a C/C++ library for information retrieval applications
5 using the Z39.50/SRU/Solr protocols for information retrieval.
13 <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
14 Amendments and Z39.50-2002 revision is supported.
18 <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
19 version 1.2 (over HTTP and HTTPS).
22 Includes BER encoders/decoders for the
23 <ulink url="&url.ill;">ISO ILL</ulink>
28 <ulink url="&url.solr;">Solr</ulink> Web Service version 1.4.x
32 Supports the following transports: BER over TCP/IP
33 (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
34 BER over unix local socket, and
35 <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
38 Secure Socket Layer support using
39 <ulink url="&url.gnutls;">GNU TLS</ulink> or
40 <ulink url="&url.openssl;">OpenSSL</ulink>.
41 If enabled, &yaz; uses HTTPS transport (for SOAP) or
42 "Secure BER" (for Z39.50).
46 <ulink url="&url.zoom;">ZOOM</ulink> C API implementing
47 Z39.50, SRU and Solr Web Service.
50 The &yaz; library offers a set of useful utilities
51 related to the protocols, such as MARC (ISO2709) parser,
53 <ulink url="&url.cql;">CQL</ulink>
54 parser, memory management routines, character set conversion.
57 Portable code. &yaz; compiles out-of-the box on most Unixes and
58 on Windows using Microsoft Visual C++.
61 Fast operation. The C based BER encoders/decoders as well
62 as the server component of &yaz; is very fast.
65 Liberal license that allows for commercial use of &yaz;.
70 <sect1 id="introduction.reading"><title>Reading this Manual</title>
71 <para>Most implementors only need to read a fraction of the
72 material in thie manual, so a quick walkthrough of the chapters
78 <xref linkend="installation"/> contains installation
79 instructions for &yaz;. You don't need reading this
80 if you expect to download &yaz; binaries.
81 However, the chapter contains information about how
82 to make <emphasis>your</emphasis> application link
89 <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
90 This is definitely worth a read if you wish to develop a Z39.50/SRU
97 <xref linkend="server"/> describes the generic frontend server
98 and explains how to develop server Z39.50/SRU applications for &yaz;.
99 Obviously worth reading if you're to develop a server.
105 <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
106 client. If you're developer and wish to test your server
107 or a server from another party, you might find this chapter
114 <xref linkend="asn"/> documents the most commonly used Z39.50
115 C data structures offered by the &yaz; API. Client
116 developers using ZOOM and non-Z39.50 implementors may skip this.
122 <xref linkend="soap"/> describes how SRU and SOAP is used
123 in &yaz;. Only if you're developing SRU applications
124 this section is a must.
130 <xref linkend="tools"/> contains sections for the various
131 tools offered by &yaz;. Scan through the material quickly
132 and see what's relevant to you! SRU implementors
133 might find the <link linkend="cql">CQL</link> section
140 <xref linkend="odr"/> goes through the details of the
141 ODR module which is the work horse that encodes and decodes
142 BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
144 Most other Z39.50 implementors only need to read the first two
145 sections (<xref linkend="odr.introduction"/> and
146 <xref linkend="odr.use"/>).
152 <xref linkend="comstack"/> describes the network layer module
153 COMSTACK. Implementors using ZOOM or the generic frontend server
154 may skip this. Others, presumably, handling client/server
155 communication on their own should read this.
161 <sect1 id="introduction.api"><title>The API</title>
164 The <ulink url="&url.yaz;">&yaz;</ulink>
165 toolkit offers several different levels of access to the
166 <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
167 <ulink url="&url.ill;">ILL</ulink> and
168 <ulink url="&url.sru;">SRU</ulink>
170 The level that you need to use depends on your requirements, and
171 the role (server or client) that you want to implement.
172 If you're developing a client application you should consider the
173 <link linkend="zoom">ZOOM</link> API.
174 It is, by far, the easiest way to develop clients in C.
175 Server implementers should consider the
176 <link linkend="server">generic frontend server</link>.
177 None of those high-level APIs support the whole protocol, but
178 they do include most facilities used in existing Z39.50 applications.
181 If you're using 'exotic' functionality (meaning anything not included in
182 the high-level APIs), developing non-standard extensions to Z39.50 or
183 you're going to develop an ILL application you'll have to learn the lower
187 The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
189 <figure id="yaz.layer">
190 <title>YAZ layers</title>
193 <imagedata fileref="apilayer.png" format="PNG"/>
196 <imagedata fileref="apilayer.eps" format="EPS"/>
201 There are four layers.
204 <para>A client or server application (or both).
205 This layer includes ZOOM and the generic frontend server.
210 The second layer provides a C represenation of the
211 protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
217 The third layer encodes and decodes protocol data units to
218 simple packages (buffer with certain length). The &odr; module
219 encodes and decodes BER whereas the HTTP modules encodes and
220 decodes HTTP ruquests/responses.
225 The lowest layer is &comstack; which exchanges the encoded packages
226 with a peer process over a network.
232 The &asn; module represents the ASN.1 definition of
233 the Z39.50 protocol. It establishes a set of type and
234 structure definitions, with one structure for each of the top-level
235 PDUs, and one structure or type for each of the contained ASN.1 types.
236 For primitive types, or other types that are defined by the ASN.1
237 standard itself (such as the EXTERNAL type), the C representation is
238 provided by the &odr; (Open Data Representation) subsystem.
241 &odr; is a basic mechanism for representing an
242 ASN.1 type in the C programming language, and for implementing BER
243 encoders and decoders for values of that type. The types defined in
244 the &asn; module generally have the prefix <literal>Z_</literal>, and
245 a suffix corresponding to the name of the type in the ASN.1
246 specification of the protocol (generally Z39.50-1995). In the case of
247 base types (those originating in the ASN.1 standard itself), the prefix
248 <literal>Odr_</literal> is sometimes seen. Either way, look for
249 the actual definition in either <filename>z-core.h</filename> (for the types
250 from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
252 The &asn; library also provides functions (which are, in turn,
253 defined using &odr; primitives) for encoding and decoding data values.
254 Their general form is
257 <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
258 <paramdef>ODR <parameter>o</parameter></paramdef>
259 <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
260 <paramdef>int <parameter>optional</parameter></paramdef>
261 <paramdef>const char *<parameter>name</parameter></paramdef>
264 (note the lower-case "z" in the function name)
269 If you are using the premade definitions of the &asn; module, and you
270 are not adding new protocol of your own, the only parts of &odr; that you
271 need to worry about are documented in
272 <xref linkend="odr.use"/>.
277 When you have created a BER-encoded buffer, you can use the &comstack;
278 subsystem to transmit (or receive) data over the network. The &comstack;
279 module provides simple functions for establishing a connection
280 (passively or actively, depending on the role of your application),
281 and for exchanging BER-encoded PDUs over that connection. When you
282 create a connection endpoint, you need to specify what transport to
283 use (TCP/IP, SSL or UNIX sockets).
284 For the remainder of the connection's lifetime, you don't have
285 to worry about the underlying transport protocol at all - the &comstack;
286 will ensure that the correct mechanism is used.
289 We call the combined interfaces to &odr;, &asn;, and &comstack; the service
290 level API. It's the API that most closely models the Z39.50
291 service/protocol definition, and it provides unlimited access to all
292 fields and facilities of the protocol definitions.
295 The reason that the &yaz; service-level API is a conglomerate of the
296 APIs from three different submodules is twofold. First, we wanted to allow
297 the user a choice of different options for each major task. For instance,
298 if you don't like the protocol API provided by &odr;/&asn;, you
299 can use SNACC or BERUtils instead, and still have the benefits of the
300 transparent transport approach of the &comstack; module. Secondly,
301 we realize that you may have to fit the toolkit into an existing
302 event-processing structure, in a way that is incompatible with
303 the &comstack; interface or some other part of &yaz;.
308 <!-- Keep this comment at the end of the file
313 sgml-minimize-attributes:nil
314 sgml-always-quote-attributes:t
317 sgml-parent-document:"yaz.xml"
318 sgml-local-catalogs: nil
319 sgml-namecase-general:t