X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fintroduction.xml;h=6710302fa11cb203453feafa2d193e463faaef63;hp=3ef6a0bf10baf07aa467aad10e979f7df61d797e;hb=0718fd63660899964512631d1e246ded8e3d18d6;hpb=a040a2caa54445509bb70c14b57dffe3bbd0fcf4 diff --git a/doc/introduction.xml b/doc/introduction.xml index 3ef6a0b..6710302 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,117 +1,270 @@ - + Introduction - - - The &yaz; - toolkit offers several different levels of access to the - ISO23950/Z39.50 - and ILL 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;. + &yaz; is a C/C++ library for information retrieval applications + using the Z39.50/SRW protocols for information retrieval. + - The basic low level modules, which are independent of the role - (client or server), consist of three primary interfaces: - + Properties of &yaz;: - &asn;, which provides a C representation of the Z39.50 - protocol packages (PDUs). + + Fast operation. The C based BER encoders/decoders as well + as the server component of &yaz; is very fast. + + + Complete + Z39.50 + version 3 support. All newer extensions + including Z39.50-2000 have been incorporated. + + + Supports + SRW + version 1.0 (over HTTP and HTTPS). + + + Includes BER encoders/decoders for the + ISO ILL + protocol. + + + Supports the following transports: BER over TCP/IP + (RFC1729), + BER over unix local socket, and + HTTP + 1.1. + + + Secure Socket Layer support using + OpenSSL. + If enabled, &yaz; uses HTTPS transport (for SOAP) or + "Secure BER" (for Z39.50). + + + Offers + ZOOM + C API implementing both Z39.50 and SRW. - &odr;, which encodes and decodes the packages according - to the BER specification. + + 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. - &comstack;, which exchanges the encoded packages with - a peer process over a network. + + Portable code. &yaz; compiles out-of-the box on most Unixes and + on Windows using Microsoft Visual C++. + + + Liberal license that allows for commercial use of &yaz;. - - 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) - + 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/SRW + client. + + + + + + describes the generic frontend server + and explains how to develop server Z39.50/SRW 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 you do not need reading this. + For the remaining client developers (not using ZOOM), + reading this chapter is a must. + Z39.50 server implementors should read this, unless you're + developing a simple server (or SRW only). + + + + + + contains sections for the various + tools offered by &yaz;. Scan through the material quickly + and see what's relevant to you! SRW 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 Introduction, + Using ODR. + + + + + + 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 + - 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. + The &yaz; + toolkit offers several different levels of access to the + ISO23950/Z39.50, + ILL and + SRW 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;. - - - 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. + The basic low level modules, which are independent of the role + (client or server), consist of three primary interfaces: + + + &asn;, which provides a C representation of the Z39.50 + 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 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 section + Using ODR. + + + - 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 + 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 + 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;. - + 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;. + +