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