X-Git-Url: http://jsfdemo.indexdata.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fintroduction.xml;h=7b2baae8bb24186baaa6966ee3bc5f9396ced4f6;hb=8e4840a9a7b6117d92d9d97fdb4048a7f8b9ce09;hp=5cc082ea46e71879827bfa8fdeb88f5d122dc059;hpb=0f72f09a46621eb0aa9960b990dd35c221333e4d;p=yaz-moved-to-github.git
diff --git a/doc/introduction.xml b/doc/introduction.xml
index 5cc082e..7b2baae 100644
--- a/doc/introduction.xml
+++ b/doc/introduction.xml
@@ -1,93 +1,320 @@
-
-Introduction
-
-
-The &yaz; toolkit offers several different levels of access to the
-Z39.50 and SR protocols. The level that you need to use depends on
-your requirements, and the role (server or client) that you
-want to implement.
-
-The basic level, which is independent of the role, consists of three
-primary interfaces:
-
-
-&asn;, which provides a C representation of the Z39.50/SR
-protocol packages (PDUs).
-
-&odr;, which encodes and decodes the packages according
-to the BER specification.
-
-&comstack;, which exchanges the encoded packages with
-a peer process over a network.
-
-
-
-The &asn; module represents the ASN.1 definition of
-the SR/Z39.50 protocol. It establishes a set of type and
-structure definitions, with one structure for each of the top-level
-PDUs, and one structure or type for each of the contained ASN.1 types.
-For primitive types, or other types that are defined by the ASN.1
-standard itself (such as the EXTERNAL type), the C representation is provided
-by the &odr; (Open Data Representation) subsystem.
-
-
-&odr; is a basic mechanism for representing an
-ASN.1 type in the C programming language, and for implementing BER
-encoders and decoders for values of that type. The types defined in
-the &asn; module generally have the prefix Z_, and a suffix
-corresponding to the name of the type in the ASN.1
-specification of the protocol (generally Z39.50-1995). In the case of
-base types (those originating in the ASN.1 standard itself), the prefix
-Odr_ is sometimes seen. Either way, look for
-the actual definition in either proto.h (for the types
-from the protocol), odr.h (for the primitive ASN.1
-types, or odr_use.h (for the ASN.1
-useful types). The &asn; library also
-provides functions (which are, in turn, defined using &odr;
-primitives) for encoding and decoding data values. Their general form is
-
-
-int z_xxx(ODR o, Z_xxx **p, int optional, const char *name);
-
-(note the lower-case "z" in the function name)
-
-
-
-
-If you are using the premade definitions of the &asn; module, and you
-are not adding new protocol of your own, the only parts of &odr; that you
-need to worry about are documented in section
-Using ODR.
-
-
-
-
-When you have created a BER-encoded buffer, you can use the &comstack;
-subsystem to transmit (or receive) data over the network. The &comstack;
-module provides simple functions for establishing a connection
-(passively or actively, depending on the role of your application),
-and for exchanging BER-encoded PDUs over that connection. When you
-create a connection endpoint, you need to specify what transport to
-use (OSI or TCP/IP), and which protocol you want to use (SR or
-Z39.50). For the remainer of the connection's lifetime, you don't have
-to worry about the underlying transport protocol at all - the &comstack;
-will ensure that the correct mechanism is used.
-
-
-We call the combined interfaces to &odr;, &asn;, and &comstack; the service
-level API. It's the API that most closely models the Z39.50/SR
-service/protocol definition, and it provides unlimited access to all
-fields and facilities of the protocol definitions.
-
-
-The reason that the &yaz; service-level API is a conglomerate of the
-APIs from three different submodules is twofold. First, we wanted to allow the
-user a choice of different options for each major task. For instance,
-if you don't like the protocol API provided by &odr;/&asn;, you
-can use SNACC or BERUtils instead, and still have the benefits of the
-transparent transport approach of the &comstack; module. Secondly,
-we realise that you may have to fit the toolkit into an existing
-event-processing structure, in a way that
-is incompatible with the &comstack; interface or some other part of &yaz;.
-
-
\ No newline at end of file
+ Introduction
+
+
+ &yaz; is a C/C++ library for information retrieval applications
+ using the Z39.50/SRU/SOLR protocols for information retrieval.
+
+
+
+ Properties of &yaz;:
+
+
+ Complete
+ Z39.50 version 3 support.
+ Amendments and Z39.50-2002 revision is supported.
+
+
+ Supports
+ SRU GET/POST/SOAP
+ version 1.2 (over HTTP and HTTPS).
+
+
+ Includes BER encoders/decoders for the
+ ISO ILL
+ protocol.
+
+
+ Supports
+ SOLR Web Service version 1.4.x (client side only)
+
+
+ Supports the following transports: BER over TCP/IP
+ (RFC1729),
+ BER over unix local socket, and
+ HTTP 1.1.
+
+
+ Secure Socket Layer support using
+ GNU TLS or
+ OpenSSL.
+ If enabled, &yaz; uses HTTPS transport (for SOAP) or
+ "Secure BER" (for Z39.50).
+
+
+ Offers
+ ZOOM C API implementing
+ Z39.50, SRU and SOLR Web Service.
+
+
+ The &yaz; library offers a set of useful utilities
+ related to the protocols, such as MARC (ISO2709) parser,
+ CCL (ISO8777) parser,
+ CQL
+ parser, memory management routines, character set conversion.
+
+
+ Portable code. &yaz; compiles out-of-the box on most Unixes and
+ on Windows using Microsoft Visual C++.
+
+
+ Fast operation. The C based BER encoders/decoders as well
+ as the server component of &yaz; is very fast.
+
+
+ Liberal license that allows for commercial use of &yaz;.
+
+
+
+
+ Reading this Manual
+ Most implementors only need to read a fraction of the
+ material in thie manual, so a quick walkthrough of the chapters
+ is in order.
+
+
+
+
+ contains installation
+ instructions for &yaz;. You don't need reading this
+ if you expect to download &yaz; binaries.
+ However, the chapter contains information about how
+ to make your application link
+ with &yaz;.
+
+
+
+
+
+ describes the ZOOM API of &yaz;.
+ This is definitely worth a read if you wish to develop a Z39.50/SRU
+ client.
+
+
+
+
+
+ describes the generic frontend server
+ and explains how to develop server Z39.50/SRU applications for &yaz;.
+ Obviously worth reading if you're to develop a server.
+
+
+
+
+
+ describes how to use the &yaz; Z39.50
+ client. If you're developer and wish to test your server
+ or a server from another party, you might find this chapter
+ useful.
+
+
+
+
+
+ documents the most commonly used Z39.50
+ C data structures offered by the &yaz; API. Client
+ developers using ZOOM and non-Z39.50 implementors may skip this.
+
+
+
+
+
+ describes how SRU and SOAP is used
+ in &yaz;. Only if you're developing SRU applications
+ this section is a must.
+
+
+
+
+
+ contains sections for the various
+ tools offered by &yaz;. Scan through the material quickly
+ and see what's relevant to you! SRU implementors
+ might find the CQL section
+ particularly useful.
+
+
+
+
+
+ goes through the details of the
+ ODR module which is the work horse that encodes and decodes
+ BER packages. Implementors using ZOOM only, do not
+ need reading this.
+ Most other Z39.50 implementors only need to read the first two
+ sections ( and
+ ).
+
+
+
+
+
+ describes the network layer module
+ COMSTACK. Implementors using ZOOM or the generic frontend server
+ may skip this. Others, presumably, handling client/server
+ communication on their own should read this.
+
+
+
+
+
+ The API
+
+
+ The &yaz;
+ toolkit offers several different levels of access to the
+ ISO23950/Z39.50,
+ ILL and
+ SRU
+ protocols.
+ The level that you need to use depends on your requirements, and
+ the role (server or client) that you want to implement.
+ If you're developing a client application you should consider the
+ ZOOM API.
+ It is, by far, the easiest way to develop clients in C.
+ Server implementers should consider the
+ generic frontend server.
+ None of those high-level APIs support the whole protocol, but
+ they do include most facilities used in existing Z39.50 applications.
+
+
+ If you're using 'exotic' functionality (meaning anything not included in
+ the high-level APIs), developing non-standard extensions to Z39.50 or
+ you're going to develop an ILL application you'll have to learn the lower
+ level APIs of &yaz;.
+
+
+ The YAZ toolkit modules is shown in figure .
+
+
+
+ There are four layers.
+
+
+ A client or server application (or both).
+ This layer includes ZOOM and the generic frontend server.
+
+
+
+
+ The second layer provides a C represenation of the
+ protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
+ SRU.
+
+
+
+
+ The third layer encodes and decodes protocol data units to
+ simple packages (buffer with certain length). The &odr; module
+ encodes and decodes BER whereas the HTTP modules encodes and
+ decodes HTTP ruquests/responses.
+
+
+
+
+ The lowest layer is &comstack; which exchanges the encoded packages
+ with a peer process over a network.
+
+
+
+
+
+ The &asn; module represents the ASN.1 definition of
+ the Z39.50 protocol. It establishes a set of type and
+ structure definitions, with one structure for each of the top-level
+ PDUs, and one structure or type for each of the contained ASN.1 types.
+ For primitive types, or other types that are defined by the ASN.1
+ standard itself (such as the EXTERNAL type), the C representation is
+ provided by the &odr; (Open Data Representation) subsystem.
+
+
+ &odr; is a basic mechanism for representing an
+ ASN.1 type in the C programming language, and for implementing BER
+ encoders and decoders for values of that type. The types defined in
+ the &asn; module generally have the prefix Z_, and
+ a suffix corresponding to the name of the type in the ASN.1
+ specification of the protocol (generally Z39.50-1995). In the case of
+ base types (those originating in the ASN.1 standard itself), the prefix
+ Odr_ is sometimes seen. Either way, look for
+ the actual definition in either z-core.h (for the types
+ from the protocol), odr.h (for the primitive ASN.1
+ types).
+ The &asn; library also provides functions (which are, in turn,
+ defined using &odr; primitives) for encoding and decoding data values.
+ Their general form is
+
+
+ int z_xxx
+ ODR o
+ Z_xxx **p
+ int optional
+ const char *name
+
+
+ (note the lower-case "z" in the function name)
+
+
+
+
+ If you are using the premade definitions of the &asn; module, and you
+ are not adding new protocol of your own, the only parts of &odr; that you
+ need to worry about are documented in
+ .
+
+
+
+
+ When you have created a BER-encoded buffer, you can use the &comstack;
+ subsystem to transmit (or receive) data over the network. The &comstack;
+ module provides simple functions for establishing a connection
+ (passively or actively, depending on the role of your application),
+ and for exchanging BER-encoded PDUs over that connection. When you
+ create a connection endpoint, you need to specify what transport to
+ use (TCP/IP, SSL or UNIX sockets).
+ For the remainder of the connection's lifetime, you don't have
+ to worry about the underlying transport protocol at all - the &comstack;
+ will ensure that the correct mechanism is used.
+
+
+ We call the combined interfaces to &odr;, &asn;, and &comstack; the service
+ level API. It's the API that most closely models the Z39.50
+ service/protocol definition, and it provides unlimited access to all
+ fields and facilities of the protocol definitions.
+
+
+ The reason that the &yaz; service-level API is a conglomerate of the
+ APIs from three different submodules is twofold. First, we wanted to allow
+ the user a choice of different options for each major task. For instance,
+ if you don't like the protocol API provided by &odr;/&asn;, you
+ can use SNACC or BERUtils instead, and still have the benefits of the
+ transparent transport approach of the &comstack; module. Secondly,
+ we realize that you may have to fit the toolkit into an existing
+ event-processing structure, in a way that is incompatible with
+ the &comstack; interface or some other part of &yaz;.
+
+
+
+
+