1 <!-- $Id: introduction.xml,v 1.14 2003-04-28 21:02:16 adam Exp $ -->
2 <chapter id="introduction"><title>Introduction</title>
5 &yaz; is a C/C++ library for information retrieval applications
6 using the Z39.50/SRW/SRU protocols for information retrieval.
14 <ulink url="http://www.loc.gov/z3950/agency/">Z39.50</ulink>
15 version 3 support. Amendments and Z39.50-2002 revision is
20 <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW/SRU</ulink>
21 version 1.0 (over HTTP and HTTPS).
24 Includes BER encoders/decoders for the
25 <ulink url="http://www.nlc-bnc.ca/iso/ill/">ISO ILL</ulink>
29 Supports the following transports: BER over TCP/IP
30 (<ulink url="http://www.faqs.org/rfcs/rfc1729.html">RFC1729</ulink>),
31 BER over unix local socket, and
32 <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP
36 Secure Socket Layer support using
37 <ulink url="http://www.openssl.org/">OpenSSL</ulink>.
38 If enabled, &yaz; uses HTTPS transport (for SOAP) or
39 "Secure BER" (for Z39.50).
43 <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
44 C API implementing both Z39.50 and SRW.
47 The &yaz; library offers a set of useful utilities
48 related to the protocols, such as MARC (ISO2709) parser,
50 <ulink url="http://www.loc.gov/z3950/agency/zing/cql/">CQL</ulink>
51 parser, memory management routines, character set conversion.
54 Portable code. &yaz; compiles out-of-the box on most Unixes and
55 on Windows using Microsoft Visual C++.
58 Fast operation. The C based BER encoders/decoders as well
59 as the server component of &yaz; is very fast.
62 Liberal license that allows for commercial use of &yaz;.
67 <sect1 id="introduction.reading"><title>Reading this Manual</title>
68 <para>Most implementors only need to read a fraction of the
69 material in thie manual, so a quick walkthrough of the chapters
75 <xref linkend="installation"/> contains installation
76 instructions for &yaz;. You don't need reading this
77 if you expect to download &yaz; binaries.
78 However, the chapter contains information about how
79 to make <emphasis>your</emphasis> application link
86 <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
87 This is definitely worth a read if you wish to develop a Z39.50/SRW
94 <xref linkend="server"/> describes the generic frontend server
95 and explains how to develop server Z39.50/SRW applications for &yaz;.
96 Obviously worth reading if you're to develop a server.
102 <xref linkend="client"/> describes how to use the &yaz; Z39.50
103 client. If you're developer and wish to test your server
104 or a server from another party, you might find this chapter
111 <xref linkend="asn"/> documents the most commonly used Z39.50
112 C data structures offered by the &yaz; API. Client
113 developers using ZOOM and non-Z39.50 implementors may skip this.
119 <xref linkend="soap"/> describes how SRW and SOAP is used
120 in &yaz;. Only if you're developing SOAP/SRW applications
121 this section is a must.
127 <xref linkend="tools"/> contains sections for the various
128 tools offered by &yaz;. Scan through the material quickly
129 and see what's relevant to you! SRW/SRU implementors
130 might find the <link linkend="tools.cql">CQL</link> section
137 <xref linkend="odr"/> goes through the details of the
138 ODR module which is the work horse that encodes and decodes
139 BER packages. Implementors using ZOOM only do not need reading this.
140 Most other Z39.50 implementors only need to read the first two
141 sections <link linkend="odr.introduction">Introduction</link>,
142 <link linkend="odr.use">Using ODR</link>.
148 <xref linkend="comstack"/> describes the network layer module
149 COMSTACK. Implementors using ZOOM or the generic frontend server
150 may skip this. Others, presumably, handling client/server
151 communication on their own should read this.
157 <sect1 id="introduction.api"><title>The API</title>
160 The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
161 toolkit offers several different levels of access to the
162 <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>,
163 <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
164 <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
166 The level that you need to use depends on your requirements, and
167 the role (server or client) that you want to implement.
168 If you're developing a client application you should consider the
169 <link linkend="zoom">ZOOM</link> API.
170 It is, by far, the easiest way to develop clients in C.
171 Server implementers should consider the
172 <link linkend="server">generic frontend server</link>.
173 None of those high-level APIs support the whole protocol, but
174 they do include most facilities used in existing Z39.50
178 If you're using 'exotic' functionality (meaning anything not included in
179 the high-level APIs), developing non-standard extensions to Z39.50 or
180 you're going to develop an ILL application you'll have to learn the lower
186 The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
188 <figure id="yaz.layer">
189 <title>YAZ layers</title>
192 <imagedata fileref="apilayer.png" format="PNG"/>
195 <imagedata fileref="apilayer.eps" format="EPS"/>
200 There are four layers.
203 <para>A client or server application (or both).
204 This layer includes ZOOM and the generic frontend server.
209 The second layer provides a C represenation of the
210 protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
216 The third layer encodes and decodes protocol data units to
217 simple packages (buffer with certain length). The &odr; module
218 encodes and decodes BER whereas the HTTP modules encodes and
219 decodes HTTP ruquests/responses.
224 The lowest layer is &comstack; which exchanges the encoded packages
225 with a peer process over a network.
231 The &asn; module represents the ASN.1 definition of
232 the Z39.50 protocol. It establishes a set of type and
233 structure definitions, with one structure for each of the top-level
234 PDUs, and one structure or type for each of the contained ASN.1 types.
235 For primitive types, or other types that are defined by the ASN.1
236 standard itself (such as the EXTERNAL type), the C representation is
237 provided by the &odr; (Open Data Representation) subsystem.
240 &odr; is a basic mechanism for representing an
241 ASN.1 type in the C programming language, and for implementing BER
242 encoders and decoders for values of that type. The types defined in
243 the &asn; module generally have the prefix <literal>Z_</literal>, and
244 a suffix corresponding to the name of the type in the ASN.1
245 specification of the protocol (generally Z39.50-1995). In the case of
246 base types (those originating in the ASN.1 standard itself), the prefix
247 <literal>Odr_</literal> is sometimes seen. Either way, look for
248 the actual definition in either <filename>z-core.h</filename> (for the types
249 from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
251 The &asn; library also provides functions (which are, in turn,
252 defined using &odr; primitives) for encoding and decoding data values.
253 Their general form is
256 <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
257 <paramdef>ODR <parameter>o</parameter></paramdef>
258 <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
259 <paramdef>int <parameter>optional</parameter></paramdef>
260 <paramdef>const char *<parameter>name</parameter></paramdef>
263 (note the lower-case "z" in the function name)
268 If you are using the premade definitions of the &asn; module, and you
269 are not adding new protocol of your own, the only parts of &odr; that you
270 need to worry about are documented in section
271 <link linkend="odr-use">Using ODR</link>.
276 When you have created a BER-encoded buffer, you can use the &comstack;
277 subsystem to transmit (or receive) data over the network. The &comstack;
278 module provides simple functions for establishing a connection
279 (passively or actively, depending on the role of your application),
280 and for exchanging BER-encoded PDUs over that connection. When you
281 create a connection endpoint, you need to specify what transport to
282 use (TCP/IP, SSL or UNIX sockets).
283 For the remainder of the connection's lifetime, you don't have
284 to worry about the underlying transport protocol at all - the &comstack;
285 will ensure that the correct mechanism is used.
288 We call the combined interfaces to &odr;, &asn;, and &comstack; the service
289 level API. It's the API that most closely models the Z39.50
290 service/protocol definition, and it provides unlimited access to all
291 fields and facilities of the protocol definitions.
294 The reason that the &yaz; service-level API is a conglomerate of the
295 APIs from three different submodules is twofold. First, we wanted to allow
296 the user a choice of different options for each major task. For instance,
297 if you don't like the protocol API provided by &odr;/&asn;, you
298 can use SNACC or BERUtils instead, and still have the benefits of the
299 transparent transport approach of the &comstack; module. Secondly,
300 we realize that you may have to fit the toolkit into an existing
301 event-processing structure, in a way that is incompatible with
302 the &comstack; interface or some other part of &yaz;.
307 <!-- Keep this comment at the end of the file
312 sgml-minimize-attributes:nil
313 sgml-always-quote-attributes:t
316 sgml-parent-document:"yaz.xml"
317 sgml-local-catalogs: nil
318 sgml-namecase-general:t