Added break in reverse/'r' option check, or it would scan for iteration number.
[yaz-moved-to-github.git] / doc / introduction.xml
1  <chapter id="introduction"><title>Introduction</title>
2
3   <para>
4    &yaz; is a C/C++ library for information retrieval applications
5    using the Z39.50/SRU protocols for information retrieval.
6   </para>
7   
8   <para>
9    Properties of &yaz;:
10    <itemizedlist>
11     <listitem><para>
12       Complete 
13       <ulink url="&url.z39.50;">Z39.50</ulink> version 3 support.
14       Amendments and Z39.50-2002 revision is supported.
15      </para></listitem>
16     <listitem><para>
17       Supports 
18       <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
19       version 1.1 (over HTTP and HTTPS).
20      </para></listitem>
21     <listitem><para>
22       Includes BER encoders/decoders for the 
23       <ulink url="&url.ill;">ISO ILL</ulink>
24       protocol.
25      </para></listitem>
26     <listitem><para>
27       Supports the following transports: BER over TCP/IP
28       (<ulink url="&url.ber.over.tcpip;">RFC1729</ulink>),
29       BER over unix local socket, and 
30       <ulink url="&url.http.1.1;">HTTP 1.1</ulink>.
31      </para></listitem>
32     <listitem><para>
33       Secure Socket Layer support using
34       <ulink url="&url.gnutls;">GNU TLS</ulink> or
35       <ulink url="&url.openssl;">OpenSSL</ulink>.
36       If enabled, &yaz; uses HTTPS transport (for SOAP) or
37       "Secure BER" (for Z39.50).
38      </para></listitem>
39     <listitem><para>
40       Offers 
41       <ulink url="&url.zoom;">ZOOM</ulink> C API implementing both
42       Z39.50 and SRU.
43      </para></listitem>
44     <listitem><para>
45       The &yaz; library offers a set of useful utilities
46       related to the protocols, such as MARC (ISO2709) parser,
47       CCL (ISO8777) parser, 
48       <ulink url="&url.cql;">CQL</ulink>
49       parser, memory management routines, character set conversion.
50      </para></listitem>
51     <listitem><para>
52       Portable code. &yaz; compiles out-of-the box on most Unixes and
53       on Windows using Microsoft Visual C++.
54      </para></listitem>
55     <listitem><para>
56       Fast operation. The C based BER encoders/decoders as well
57       as the server component of &yaz; is very fast.
58      </para></listitem>
59     <listitem><para>
60       Liberal license that allows for commercial use of &yaz;.
61      </para></listitem>
62    </itemizedlist>
63   </para>
64
65   <sect1 id="introduction.reading"><title>Reading this Manual</title>
66    <para>Most implementors only need to read a fraction of the
67     material in thie manual, so a quick walkthrough of the chapters
68     is in order.
69    </para>
70    <itemizedlist>
71     <listitem>
72      <para>
73       <xref linkend="installation"/> contains installation 
74       instructions for &yaz;. You don't need reading this
75       if you expect to download &yaz; binaries.
76       However, the chapter contains information about how
77       to make <emphasis>your</emphasis> application link
78       with &yaz;.
79      </para>
80     </listitem>
81
82     <listitem>
83      <para>
84       <xref linkend="zoom"/> describes the ZOOM API of &yaz;.
85       This is definitely worth a read if you wish to develop a Z39.50/SRU
86       client.
87      </para>
88     </listitem>
89     
90     <listitem>
91      <para>
92       <xref linkend="server"/> describes the generic frontend server
93       and explains how to develop server Z39.50/SRU applications for &yaz;.
94       Obviously worth reading if you're to develop a server.
95     </para>
96     </listitem>
97
98     <listitem>
99      <para>
100       <xref linkend="yaz-client"/> describes how to use the &yaz; Z39.50
101       client. If you're developer and wish to test your server
102       or a server from another party, you might find this chapter
103       useful.
104     </para>
105     </listitem>
106
107     <listitem>
108      <para>
109       <xref linkend="asn"/> documents the most commonly used Z39.50
110       C data structures offered by the &yaz; API. Client
111       developers using ZOOM and non-Z39.50 implementors may skip this.
112      </para>
113     </listitem>
114
115     <listitem>
116      <para>
117       <xref linkend="soap"/> describes how SRU and SOAP is used 
118       in &yaz;. Only if you're developing SRU applications
119       this section is a must.
120      </para>
121     </listitem>
122
123     <listitem>
124      <para>
125       <xref linkend="tools"/> contains sections for the various
126       tools offered by &yaz;. Scan through the material quickly
127       and see what's relevant to you! SRU implementors
128       might find the <link linkend="cql">CQL</link> section
129       particularly useful.
130      </para>
131     </listitem>
132
133     <listitem>
134      <para>
135       <xref linkend="odr"/> goes through the details of the
136       ODR module which is the work horse that encodes and decodes
137       BER packages. Implementors using ZOOM only, do <emphasis>not</emphasis>
138       need reading this.
139       Most other Z39.50 implementors only need to read the first two
140       sections (<xref linkend="odr.introduction"/> and
141       <xref linkend="odr.use"/>).
142      </para>
143     </listitem>
144
145     <listitem>
146      <para>
147       <xref linkend="comstack"/> describes the network layer module
148       COMSTACK. Implementors using ZOOM or the generic frontend server
149       may skip this. Others, presumably, handling client/server
150      communication on their own should read this.
151      </para>
152     </listitem>
153
154    </itemizedlist>
155   </sect1>
156   <sect1 id="introduction.api"><title>The API</title>
157    
158    <para>
159     The <ulink url="&url.yaz;">&yaz;</ulink>
160     toolkit offers several different levels of access to the
161     <ulink url="&url.z39.50;">ISO23950/Z39.50</ulink>,
162     <ulink url="&url.ill;">ILL</ulink> and
163     <ulink url="&url.sru;">SRU</ulink>
164     protocols.
165     The level that you need to use depends on your requirements, and
166     the role (server or client) that you want to implement.
167     If you're developing a client application you should consider the
168     <link linkend="zoom">ZOOM</link> API.
169     It is, by far, the easiest way to develop clients in C.
170     Server implementers should consider the 
171     <link linkend="server">generic frontend server</link>.
172     None of those high-level APIs support the whole protocol, but
173     they do include most facilities used in existing Z39.50 applications.
174    </para>
175    <para>
176     If you're using 'exotic' functionality (meaning anything not included in
177     the high-level APIs), developing non-standard extensions to Z39.50 or
178     you're going to develop an ILL application you'll have to learn the lower
179     level APIs of &yaz;.
180    </para>
181    <para>
182     The YAZ toolkit modules is shown in figure <xref linkend="yaz.layer"/>.
183    </para>
184    <figure id="yaz.layer">
185     <title>YAZ layers</title>
186     <mediaobject>
187      <imageobject>
188       <imagedata fileref="apilayer.png" format="PNG"/>
189      </imageobject>
190      <imageobject>
191       <imagedata fileref="apilayer.eps" format="EPS"/>
192      </imageobject>
193     </mediaobject>
194    </figure>
195    <para>
196     There are four layers.
197     <itemizedlist>
198      <listitem>
199       <para>A client or server application (or both).
200        This layer includes ZOOM and the generic frontend server.
201       </para>
202      </listitem>
203      <listitem>
204       <para>
205        The second layer provides a C represenation of the 
206        protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
207        SRU.
208       </para>
209      </listitem>
210      <listitem>
211       <para>
212        The third layer encodes and decodes protocol data units to
213        simple packages (buffer with certain length). The &odr; module
214        encodes and decodes BER whereas the HTTP modules encodes and
215        decodes HTTP ruquests/responses.
216       </para>
217      </listitem>
218      <listitem>
219       <para>
220        The lowest layer is &comstack; which exchanges the encoded packages
221        with a peer process over a network.
222       </para>
223      </listitem>
224     </itemizedlist>
225    </para>
226    <para>
227     The &asn; module represents the ASN.1 definition of
228     the Z39.50 protocol. It establishes a set of type and
229     structure definitions, with one structure for each of the top-level
230     PDUs, and one structure or type for each of the contained ASN.1 types.
231     For primitive types, or other types that are defined by the ASN.1
232     standard itself (such as the EXTERNAL type), the C representation is
233     provided by the &odr; (Open Data Representation) subsystem.
234   </para>
235    <para>
236      &odr; is a basic mechanism for representing an
237     ASN.1 type in the C programming language, and for implementing BER
238     encoders and decoders for values of that type. The types defined in
239     the &asn; module generally have the prefix <literal>Z_</literal>, and
240     a suffix corresponding to the name of the type in the ASN.1
241     specification of the protocol (generally Z39.50-1995). In the case of
242     base types (those originating in the ASN.1 standard itself), the prefix
243     <literal>Odr_</literal> is sometimes seen. Either way, look for
244     the actual definition in either <filename>z-core.h</filename> (for the types
245     from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
246     types).
247     The &asn; library also provides functions (which are, in turn,
248     defined using &odr; primitives) for encoding and decoding data values.
249     Their general form is
250     
251     <funcsynopsis>
252      <funcprototype><funcdef>int <function>z_<replaceable>xxx</replaceable></function></funcdef>
253       <paramdef>ODR <parameter>o</parameter></paramdef>
254       <paramdef>Z_<replaceable>xxx</replaceable> **<parameter>p</parameter></paramdef>
255       <paramdef>int <parameter>optional</parameter></paramdef>
256       <paramdef>const char *<parameter>name</parameter></paramdef>
257      </funcprototype>
258     </funcsynopsis>
259     (note the lower-case &quot;z&quot; in the function name)
260    </para>
261    
262    <note>
263     <para>
264      If you are using the premade definitions of the &asn; module, and you
265      are not adding new protocol of your own, the only parts of &odr; that you
266      need to worry about are documented in
267      <xref linkend="odr.use"/>.
268     </para>
269    </note>
270    
271   <para>
272     When you have created a BER-encoded buffer, you can use the &comstack;
273     subsystem to transmit (or receive) data over the network. The &comstack;
274     module provides simple functions for establishing a connection
275     (passively or actively, depending on the role of your application),
276     and for exchanging BER-encoded PDUs over that connection. When you
277     create a connection endpoint, you need to specify what transport to
278     use (TCP/IP, SSL or UNIX sockets).
279     For the remainder of the connection's lifetime, you don't have
280     to worry about the underlying transport protocol at all - the &comstack;
281     will ensure that the correct mechanism is used.
282    </para>
283    <para>
284     We call the combined interfaces to &odr;, &asn;, and &comstack; the service
285     level API. It's the API that most closely models the Z39.50
286    service/protocol definition, and it provides unlimited access to all
287     fields and facilities of the protocol definitions.
288    </para>
289    <para>
290     The reason that the &yaz; service-level API is a conglomerate of the
291     APIs from three different submodules is twofold. First, we wanted to allow
292     the user a choice of different options for each major task. For instance,
293     if you don't like the protocol API provided by &odr;/&asn;, you
294     can use SNACC or BERUtils instead, and still have the benefits of the
295     transparent transport approach of the &comstack; module. Secondly,
296     we realize that you may have to fit the toolkit into an existing
297     event-processing structure, in a way that is incompatible with
298     the &comstack; interface or some other part of &yaz;.
299    </para>
300   </sect1>
301  </chapter>
302
303  <!-- Keep this comment at the end of the file
304  Local variables:
305  mode: sgml
306  sgml-omittag:t
307  sgml-shorttag:t
308  sgml-minimize-attributes:nil
309  sgml-always-quote-attributes:t
310  sgml-indent-step:1
311  sgml-indent-data:t
312  sgml-parent-document:"yaz.xml"
313  sgml-local-catalogs: nil
314  sgml-namecase-general:t
315  End:
316  -->