doc/introduction.xml

   1 <!-- $Id: introduction.xml,v 1.9 2003-02-21 00:24:26 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 protocols for information retrieval.
   7   </para>
   8
   9   <para>
  10    Properties of &yaz;:
  11    <itemizedlist>
  12     <listitem><para>
  13       Fast operation. The C based BER encoders/decoders as well
  14       as the server component of &yaz; is very fast.
  15      </para></listitem>
  16     <listitem><para>
  17       Complete
  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.
  21      </para></listitem>
  22     <listitem><para>
  23       Supports
  24       <ulink url="http://www.loc.gov/z3950/agency/zing/srw/">SRW</ulink>
  25       version 1.0 (over HTTP and HTTPS).
  26      </para></listitem>
  27     <listitem><para>
  28       Includes BER encoders/decoders for the
  29       <ulink url="http://www.nlc-bnc.ca/iso/ill/">ISO ILL</ulink>
  30       protocol.
  31      </para></listitem>
  32     <listitem><para>
  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
  37        1.1</ulink>.
  38      </para></listitem>
  39     <listitem><para>
  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).
  44      </para></listitem>
  45     <listitem><para>
  46       Offers
  47       <ulink url="http://zoom.z3950.org/">ZOOM</ulink>
  48       C API implementing both Z39.50 and SRW.
  49      </para></listitem>
  50     <listitem><para>
  51       The &yaz; library offers a set of useful utilities
  52       related to the protocols, such as MARC (ISO2709) parser,
  53       CCL (ISO8777) parser,
  54       <ulink url="http://www.loc.gov/z3950/agency/zing/cql/">CQL</ulink>
  55       parser, memory management routines, character set conversion.
  56      </para></listitem>
  57     <listitem><para>
  58       Portable code. &yaz; compiles out-of-the box on most Unixes and
  59       on Windows using Microsoft Visual C++.
  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="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.
  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 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).
 118      </para>
 119     </listitem>
 120
 121     <listitem>
 122      <para>
 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
 127       particularly useful.
 128      </para>
 129     </listitem>
 130
 131     <listitem>
 132      <para>
 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>.
 139      </para>
 140     </listitem>
 141
 142     <listitem>
 143      <para>
 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.
 148      </para>
 149     </listitem>
 150
 151    </itemizedlist>
 152   </sect1>
 153   <sect1 id="introduction.api"><title>The API</title>
 154
 155    <para>
 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
 160     SRW protocols.
 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
 170     applications.
 171    </para>
 172    <para>
 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
 176     level APIs of &yaz;.
 177    </para>
 178   <para>
 179     The basic low level modules, which are independent of the role
 180     (client or server), consist of three primary interfaces:
 181
 182     <itemizedlist>
 183      <listitem><para>&asn;, which provides a C representation of the Z39.50
 184        protocol packages (PDUs).
 185       </para></listitem>
 186      <listitem><para>&odr;, which encodes and decodes the packages according
 187        to the BER specification.
 188       </para></listitem>
 189      <listitem><para>&comstack;, which exchanges the encoded packages with
 190        a peer process over a network.
 191       </para></listitem>
 192     </itemizedlist>
 193
 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.
 201   </para>
 202    <para>
 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
 213     types).
 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
 217
 218     <funcsynopsis>
 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>
 224      </funcprototype>
 225     </funcsynopsis>
 226     (note the lower-case &quot;z&quot; in the function name)
 227    </para>
 228
 229    <note>
 230     <para>
 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>.
 235     </para>
 236    </note>
 237
 238   <para>
 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.
 249    </para>
 250    <para>
 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.
 255    </para>
 256    <para>
 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;.
 266    </para>
 267   </sect1>
 268  </chapter>
 269
 270  <!-- Keep this comment at the end of the file
 271  Local variables:
 272  mode: sgml
 273  sgml-omittag:t
 274  sgml-shorttag:t
 275  sgml-minimize-attributes:nil
 276  sgml-always-quote-attributes:t
 277  sgml-indent-step:1
 278  sgml-indent-data:t
 279  sgml-parent-document:"yaz.xml"
 280  sgml-local-catalogs: nil
 281  sgml-namecase-general:t
 282  End:
 283  -->