doc/introduction.xml

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