doc/introduction.xml

   1 <!-- $Header: /home/cvsroot/yaz/doc/introduction.xml,v 1.1 2001-01-04 13:36:24 adam Exp $ -->
   2 <chapter><title>Introduction</title>
   3
   4 <para>
   5 The &yaz; toolkit offers several different levels of access to the
   6 Z39.50 and SR protocols. The level that you need to use depends on
   7 your requirements, and the role (server or client) that you
   8 want to implement.
   9 </para><para>
  10 The basic level, which is independent of the role, consists of three
  11 primary interfaces:
  12
  13 <itemizedlist>
  14 <listitem><para>&asn;, which provides a C representation of the Z39.50/SR
  15 protocol packages (PDUs).
  16 </para></listitem>
  17 <listitem><para>&odr;, which encodes and decodes the packages according
  18 to the BER specification.
  19 </para></listitem>
  20 <listitem><para>&comstack;, which exchanges the encoded packages with
  21 a peer process over a network.
  22 </para></listitem>
  23 </itemizedlist>
  24
  25 The &asn; module represents the ASN.1 definition of
  26 the SR/Z39.50 protocol. It establishes a set of type and
  27 structure definitions, with one structure for each of the top-level
  28 PDUs, and one structure or type for each of the contained ASN.1 types.
  29 For primitive types, or other types that are defined by the ASN.1
  30 standard itself (such as the EXTERNAL type), the C representation is provided
  31 by the &odr; (Open Data Representation) subsystem.
  32 </para>
  33 <para>
  34 &odr; is a basic mechanism for representing an
  35 ASN.1 type in the C programming language, and for implementing BER
  36 encoders and decoders for values of that type. The types defined in
  37 the &asn; module generally have the prefix <literal>Z_</literal>, and a suffix
  38 corresponding to the name of the type in the ASN.1
  39 specification of the protocol (generally Z39.50-1995). In the case of
  40 base types (those originating in the ASN.1 standard itself), the prefix
  41 <literal>Odr_</literal> is sometimes seen. Either way, look for
  42 the actual definition in either <filename>proto.h</filename> (for the types
  43 from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
  44 types, or <filename>odr_use.h</filename> (for the ASN.1
  45 <emphasis>useful</emphasis> types). The &asn; library also
  46 provides functions (which are, in turn, defined using &odr;
  47 primitives) for encoding and decoding data values. Their general form is
  48
  49 <synopsis>
  50 int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
  51 </synopsis>
  52 (note the lower-case &quot;z&quot; in the function name)
  53 </para>
  54
  55 <note>
  56 <para>
  57 If you are using the premade definitions of the &asn; module, and you
  58 are not adding new protocol of your own, the only parts of &odr; that you
  59 need to worry about are documented in section
  60 <link linkend="odr-use">Using ODR</link>.
  61 </para>
  62 </note>
  63
  64 <para>
  65 When you have created a BER-encoded buffer, you can use the &comstack;
  66 subsystem to transmit (or receive) data over the network. The &comstack;
  67 module provides simple functions for establishing a connection
  68 (passively or actively, depending on the role of your application),
  69 and for exchanging BER-encoded PDUs over that connection. When you
  70 create a connection endpoint, you need to specify what transport to
  71 use (OSI or TCP/IP), and which protocol you want to use (SR or
  72 Z39.50). For the remainer of the connection's lifetime, you don't have
  73 to worry about the underlying transport protocol at all - the &comstack;
  74 will ensure that the correct mechanism is used.
  75 </para>
  76 <para>
  77 We call the combined interfaces to &odr;, &asn;, and &comstack; the service
  78 level API. It's the API that most closely models the Z39.50/SR
  79 service/protocol definition, and it provides unlimited access to all
  80 fields and facilities of the protocol definitions.
  81 </para>
  82 <para>
  83 The reason that the &yaz; service-level API is a conglomerate of the
  84 APIs from three different submodules is twofold. First, we wanted to allow the
  85 user a choice of different options for each major task. For instance,
  86 if you don't like the protocol API provided by &odr;/&asn;, you
  87 can use SNACC or BERUtils instead, and still have the benefits of the
  88 transparent transport approach of the &comstack; module. Secondly,
  89 we realise that you may have to fit the toolkit into an existing
  90 event-processing structure, in a way that
  91 is incompatible with the &comstack; interface or some other part of &yaz;.
  92 </para>
  93 </chapter>