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