1 <!-- $Id: introduction.xml,v 1.9 2003-02-21 00:24:26 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 protocols for information retrieval.
13 Fast operation. The C based BER encoders/decoders as well
14 as the server component of &yaz; is very fast.
18 <ulink url="http://www.loc.gov/z3950/agency/">Z39.50</ulink>
19 version 3 support. All newer extensions
20 including Z39.50-2000 have been incorporated.
24 <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
25 version 1.0 (over HTTP and HTTPS).
28 Includes BER encoders/decoders for the
29 <ulink url="http://www.nlc-bnc.ca/iso/ill/">ISO ILL</ulink>
33 Supports the following transports: BER over TCP/IP
34 (<ulink url="http://www.faqs.org/rfcs/rfc1729.html">RFC1729</ulink>),
35 BER over unix local socket, and
36 <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616.html">HTTP
40 Secure Socket Layer support using
41 <ulink url="http://www.openssl.org/">OpenSSL</ulink>.
42 If enabled, &yaz; uses HTTPS transport (for SOAP) or
43 "Secure BER" (for Z39.50).
47 <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
48 C API implementing both Z39.50 and SRW.
51 The &yaz; library offers a set of useful utilities
52 related to the protocols, such as MARC (ISO2709) parser,
54 <ulink url="http://www.loc.gov/z3950/agency/zing/cql/">CQL</ulink>
55 parser, memory management routines, character set conversion.
58 Portable code. &yaz; compiles out-of-the box on most Unixes and
59 on Windows using Microsoft Visual C++.
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="zoom"/> 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 you do not need reading this.
114 For the remaining client developers (not using ZOOM),
115 reading this chapter is a must.
116 Z39.50 server implementors should read this, unless you're
117 developing a simple server (or SRW only).
123 <xref linkend="tools"/> contains sections for the various
124 tools offered by &yaz;. Scan through the material quickly
125 and see what's relevant to you! SRW implementors
126 might find the <link linkend="tools.cql">CQL</link> section
133 <xref linkend="odr"/> goes through the details of the
134 ODR module which is the work horse that encodes and decodes
135 BER packages. Implementors using ZOOM only do not need reading this.
136 Most other Z39.50 implementors only need to read the first two
137 sections <link linkend="odr.introduction">Introduction</link>,
138 <link linkend="odr.use">Using ODR</link>.
144 <xref linkend="comstack"/> describes the network layer module
145 COMSTACK. Implementors using ZOOM or the generic frontend server
146 may skip this. Others, presumably, handling client/server
147 communication on their own should read this.
153 <sect1 id="introduction.api"><title>The API</title>
156 The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
157 toolkit offers several different levels of access to the
158 <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>,
159 <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> and
161 The level that you need to use depends on your requirements, and
162 the role (server or client) that you want to implement.
163 If you're developing a client application you should consider the
164 <link linkend="zoom">ZOOM</link> API.
165 It is, by far, the easiest way to develop clients in C.
166 Server implementers should consider the
167 <link linkend="server">generic frontend server</link>.
168 None of those high-level APIs support the whole protocol, but
169 they do include most facilities used in existing Z39.50
173 If you're using 'exotic' functionality (meaning anything not included in
174 the high-level APIs), developing non-standard extensions to Z39.50 or
175 you're going to develop an ILL application you'll have to learn the lower
179 The basic low level modules, which are independent of the role
180 (client or server), consist of three primary interfaces:
183 <listitem><para>&asn;, which provides a C representation of the Z39.50
184 protocol packages (PDUs).
186 <listitem><para>&odr;, which encodes and decodes the packages according
187 to the BER specification.
189 <listitem><para>&comstack;, which exchanges the encoded packages with
190 a peer process over a network.
194 The &asn; module represents the ASN.1 definition of
195 the Z39.50 protocol. It establishes a set of type and
196 structure definitions, with one structure for each of the top-level
197 PDUs, and one structure or type for each of the contained ASN.1 types.
198 For primitive types, or other types that are defined by the ASN.1
199 standard itself (such as the EXTERNAL type), the C representation is
200 provided by the &odr; (Open Data Representation) subsystem.
203 &odr; is a basic mechanism for representing an
204 ASN.1 type in the C programming language, and for implementing BER
205 encoders and decoders for values of that type. The types defined in
206 the &asn; module generally have the prefix <literal>Z_</literal>, and
207 a suffix corresponding to the name of the type in the ASN.1
208 specification of the protocol (generally Z39.50-1995). In the case of
209 base types (those originating in the ASN.1 standard itself), the prefix
210 <literal>Odr_</literal> is sometimes seen. Either way, look for
211 the actual definition in either <filename>z-core.h</filename> (for the types
212 from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
214 The &asn; library also provides functions (which are, in turn,
215 defined using &odr; primitives) for encoding and decoding data values.
216 Their general form is
219 <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
220 <paramdef>ODR <parameter>o</parameter></paramdef>
221 <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
222 <paramdef>int <parameter>optional</parameter></paramdef>
223 <paramdef>const char *<parameter>name</parameter></paramdef>
226 (note the lower-case "z" in the function name)
231 If you are using the premade definitions of the &asn; module, and you
232 are not adding new protocol of your own, the only parts of &odr; that you
233 need to worry about are documented in section
234 <link linkend="odr-use">Using ODR</link>.
239 When you have created a BER-encoded buffer, you can use the &comstack;
240 subsystem to transmit (or receive) data over the network. The &comstack;
241 module provides simple functions for establishing a connection
242 (passively or actively, depending on the role of your application),
243 and for exchanging BER-encoded PDUs over that connection. When you
244 create a connection endpoint, you need to specify what transport to
245 use (TCP/IP, SSL or UNIX sockets).
246 For the remainder of the connection's lifetime, you don't have
247 to worry about the underlying transport protocol at all - the &comstack;
248 will ensure that the correct mechanism is used.
251 We call the combined interfaces to &odr;, &asn;, and &comstack; the service
252 level API. It's the API that most closely models the Z39.50
253 service/protocol definition, and it provides unlimited access to all
254 fields and facilities of the protocol definitions.
257 The reason that the &yaz; service-level API is a conglomerate of the
258 APIs from three different submodules is twofold. First, we wanted to allow
259 the user a choice of different options for each major task. For instance,
260 if you don't like the protocol API provided by &odr;/&asn;, you
261 can use SNACC or BERUtils instead, and still have the benefits of the
262 transparent transport approach of the &comstack; module. Secondly,
263 we realize that you may have to fit the toolkit into an existing
264 event-processing structure, in a way that is incompatible with
265 the &comstack; interface or some other part of &yaz;.
270 <!-- Keep this comment at the end of the file
275 sgml-minimize-attributes:nil
276 sgml-always-quote-attributes:t
279 sgml-parent-document:"yaz.xml"
280 sgml-local-catalogs: nil
281 sgml-namecase-general:t