X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fintroduction.xml;h=dd93b10c54046af9d02a7b014896c10b95f131f6;hp=3ef6a0bf10baf07aa467aad10e979f7df61d797e;hb=4466c3fb3ec5053427237ca4523ed4ed9f7e9425;hpb=d82eeac05d2899fa30704e2c40e9dd603ff2c581 diff --git a/doc/introduction.xml b/doc/introduction.xml index 3ef6a0b..dd93b10 100644 --- a/doc/introduction.xml +++ b/doc/introduction.xml @@ -1,117 +1,308 @@ - 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/SRU/Solr 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). + + Complete + Z39.50 version 3 support. + Amendments and Z39.50-2002 revision is supported. + + + Supports + SRU GET/POST/SOAP + version 1.1, 1.2 and 2.0 (over HTTP and HTTPS). + + + Includes BER encoders/decoders for the + ISO ILL + protocol. + + + Supports + Solr Web Service version 1.4.x + (client side only) - &odr;, which encodes and decodes the packages according - to the BER specification. + + Supports the following transports: BER over TCP/IP + (RFC1729), + BER over unix local socket, and + HTTP 1.1. - &comstack;, which exchanges the encoded packages with - a peer process over a network. + + 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;. - - 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. + 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;. + + - - 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. + + + 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 . + +
+ YAZ layers + + + + + + + + +
+ + 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 + . + + + - 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 - 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;. - + 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;. + +