1 <!-- $Id: introduction.xml,v 1.5 2001-10-24 20:12:36 adam Exp $ -->
2 <chapter id="introduction"><title>Introduction</title>
5 The <ulink url="http://www.indexdata.dk/yaz/">&yaz;</ulink>
6 toolkit offers several different levels of access to the
7 <ulink url="http://www.loc.gov/z3950/agency/">ISO23950/Z39.50</ulink>
8 and <ulink url="http://www.nlc-bnc.ca/iso/ill/">ILL</ulink> protocols.
9 The level that you need to use depends on your requirements, and
10 the role (server or client) that you want to implement.
11 If you're developing a client application you should consider the
12 <link linkend="zoom">ZOOM</link> API.
13 It is, by far, the easiest way to develop clients in C.
14 Server implementers should consider the
15 <link linkend="server">generic frontend server</link>.
16 None of those high-level API's support the whole protocol, but
17 they support most facilities used in existing Z39.50
21 If you're developing non-standard extensions to Z39.50 or you're
22 going to develop an ILL application you'll have to learn the lower
26 The basic low level modules, which is independent of the role,
27 consists of three primary interfaces:
30 <listitem><para>&asn;, which provides a C representation of the Z39.50
31 protocol packages (PDUs).
33 <listitem><para>&odr;, which encodes and decodes the packages according
34 to the BER specification.
36 <listitem><para>&comstack;, which exchanges the encoded packages with
37 a peer process over a network.
41 The &asn; module represents the ASN.1 definition of
42 the Z39.50 protocol. It establishes a set of type and
43 structure definitions, with one structure for each of the top-level
44 PDUs, and one structure or type for each of the contained ASN.1 types.
45 For primitive types, or other types that are defined by the ASN.1
46 standard itself (such as the EXTERNAL type), the C representation is
47 provided by the &odr; (Open Data Representation) subsystem.
50 &odr; is a basic mechanism for representing an
51 ASN.1 type in the C programming language, and for implementing BER
52 encoders and decoders for values of that type. The types defined in
53 the &asn; module generally have the prefix <literal>Z_</literal>, and
54 a suffix corresponding to the name of the type in the ASN.1
55 specification of the protocol (generally Z39.50-1995). In the case of
56 base types (those originating in the ASN.1 standard itself), the prefix
57 <literal>Odr_</literal> is sometimes seen. Either way, look for
58 the actual definition in either <filename>proto.h</filename> (for the types
59 from the protocol), <filename>odr.h</filename> (for the primitive ASN.1
60 types, or <filename>odr_use.h</filename> (for the ASN.1
61 <emphasis>useful</emphasis> types). The &asn; library also
62 provides functions (which are, in turn, defined using &odr;
63 primitives) for encoding and decoding data values. Their general form is
66 int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
68 (note the lower-case "z" in the function name)
73 If you are using the premade definitions of the &asn; module, and you
74 are not adding new protocol of your own, the only parts of &odr; that you
75 need to worry about are documented in section
76 <link linkend="odr-use">Using ODR</link>.
81 When you have created a BER-encoded buffer, you can use the &comstack;
82 subsystem to transmit (or receive) data over the network. The &comstack;
83 module provides simple functions for establishing a connection
84 (passively or actively, depending on the role of your application),
85 and for exchanging BER-encoded PDUs over that connection. When you
86 create a connection endpoint, you need to specify what transport to
88 For the remainder of the connection's lifetime, you don't have
89 to worry about the underlying transport protocol at all - the &comstack;
90 will ensure that the correct mechanism is used.
93 We call the combined interfaces to &odr;, &asn;, and &comstack; the service
94 level API. It's the API that most closely models the Z39.50
95 service/protocol definition, and it provides unlimited access to all
96 fields and facilities of the protocol definitions.
99 The reason that the &yaz; service-level API is a conglomerate of the
100 APIs from three different submodules is twofold. First, we wanted to allow
101 the user a choice of different options for each major task. For instance,
102 if you don't like the protocol API provided by &odr;/&asn;, you
103 can use SNACC or BERUtils instead, and still have the benefits of the
104 transparent transport approach of the &comstack; module. Secondly,
105 we realize that you may have to fit the toolkit into an existing
106 event-processing structure, in a way that
107 is incompatible with the &comstack; interface or some other part of &yaz;.
111 <!-- Keep this comment at the end of the file
116 sgml-minimize-attributes:nil
117 sgml-always-quote-attributes:t
120 sgml-parent-document:"yaz.xml"
121 sgml-local-catalogs: "../../docbook/docbook.cat"
122 sgml-namecase-general:t