From 0718fd63660899964512631d1e246ded8e3d18d6 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Fri, 21 Feb 2003 00:24:26 +0000 Subject: [PATCH] Stuff on SRW --- doc/Makefile.am | 62 +++------ doc/introduction.xml | 343 ++++++++++++++++++++++++++++++++++++-------------- doc/yaz.xml.in | 5 +- doc/zoom.xml | 100 +++++++++++++-- 4 files changed, 358 insertions(+), 152 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index cc736db..44d6dd9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,4 +1,4 @@ -## $Id: Makefile.am,v 1.37 2003-02-18 10:37:08 adam Exp $ +## $Id: Makefile.am,v 1.38 2003-02-21 00:24:26 adam Exp $ docdir=$(datadir)/doc/@PACKAGE@ @@ -8,53 +8,19 @@ XMLFILES=yaz.xml.in introduction.xml installation.xml indexdata.xml \ yaz-client-commands.xml HTMLFILES = \ -asn.external.html \ -asn.html \ -asn.oid.html \ -asn.pdu.html \ -asn.preparing.html \ -client.commands.html \ -client.html \ -client.invoking.html \ -client.searching.html \ -comstack.addresses.html \ -comstack.client.html \ -comstack.common.html \ -comstack.diagnostics.html \ -comstack.html \ -comstack.introduction.html \ -comstack.server.html \ -comstack.summary.html \ -credits.html \ -future.html \ -indexdata.html \ -installation.html \ -installation.unix.html \ -installation.win32.html \ -introduction.html \ -license.html \ -license.other.html \ -odr.debugging.html \ -odr.html \ -odr.programming.html \ -odr.use.html \ -server.backendfunctions.html \ -server.backend.html \ -server.frontend.html \ -server.html \ -server.invocation.html \ -server.main.html \ -tools.html \ -tools.nmem.html \ -tools.oid.html \ -yaz.html \ -zoom.events.html \ -zoom.html \ -zoom.options.html \ -zoom.query.html \ -zoom.records.html \ -zoom.resultsets.html \ -zoom.scan.html + asn.external.html asn.html asn.oid.html asn.pdu.html asn.preparing.html \ + client.commands.html client.html client.invoking.html client.searching.html \ + comstack.addresses.html comstack.client.html comstack.common.html \ + comstack.diagnostics.html comstack.html comstack.introduction.html \ + comstack.server.html comstack.summary.html credits.html future.html \ + indexdata.html installation.html installation.unix.html \ + installation.win32.html introduction.api.html introduction.html \ + license.html license.other.html odr.debugging.html odr.html \ + odr.programming.html odr.use.html server.backendfunctions.html \ + server.backend.html server.frontend.html server.html server.invocation.html \ + server.main.html tools.html tools.nmem.html tools.oid.html yaz.html \ + zoom.events.html zoom.html zoom.options.html zoom.query.html \ + zoom.records.html zoom.resultsets.html zoom.scan.html MANFILES=yaz-client.1 yaz-client-ssl.1 yaz-ztest.8 \ yaz-ztest-ssl.8 yaz-config.1 yaz.7 zoomsh.1 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;. + + + YAZ User's Guide and Reference SebastianHammer + AdamDickmeiss AdamDickmeiss 1995-2003 @@ -37,7 +38,7 @@ This document is the programmer's guide and reference to the &yaz; package version @VERSION@. &yaz; is a compact toolkit that provides - access to the Z39.50 protocol, as well as a set of higher-level + access to the Z39.50 and SRW protocols, as well as a set of higher-level tools for implementing the server and client roles, respectively. The documentation can be used on its own, or as a reference when looking at the example applications provided with the package. diff --git a/doc/zoom.xml b/doc/zoom.xml index 549e16d..a9d97ae 100644 --- a/doc/zoom.xml +++ b/doc/zoom.xml @@ -1,5 +1,5 @@ - - Building clients with ZOOM + + ZOOM &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is an initiative started by Mike Taylor (Mike is from the UK, which @@ -7,6 +7,15 @@ provide a common Z39.50 client API not bound to a particular programming language or toolkit. + + + + A recent addition to &yaz; is SRW support. You can now make + SRW ZOOM connections by specifying a new scheme for the + host name for a connection. + + + The lack of a simple Z39.50 client API for &yaz; has become more and more apparent over time. So when the first &zoom; specification @@ -75,6 +84,11 @@ slash, the following part specifies a database for the connection. + You can prefix the host with a scheme followed by colon. The + default scheme is tcp (Z39.50 protocol). + The scheme http selects SRW over HTTP. + + Connection objects should be destroyed using the function ZOOM_connection_destroy. @@ -179,7 +193,7 @@ of ZOOM_connection_error that is capable of returning name of diagnostic set in dset. - Protocol behavior + Z39.50 Protocol behavior The calls ZOOM_connection_new and ZOOM_connection_connect establishes a TCP/IP @@ -217,6 +231,20 @@ API cannot tell the outcome (yet). + SRW Protocol behavior + + The SRW protocol doesn't feature an Init Request, so + the connection phase merely establishes a TCP/IP connection + with the SOAP service. + + None of the ZOOM connection options + affect SRW and they are ignored. However, future versions + of &yaz; might honor implementationName and + put that as part of User-Agent header for HTTP requests. + The charset, and lang + might also affect HTTP headers in future releases. + + Queries @@ -229,6 +257,8 @@ int ZOOM_query_prefix(ZOOM_query q, const char *str); + int ZOOM_query_cql(ZOOM_query s, const char *str); + int ZOOM_query_sortby(ZOOM_query q, const char *criteria); @@ -236,8 +266,10 @@ and destroy them by calling ZOOM_query_destroy. RPN-queries can be specified in PQF notation by using the - function ZOOM_query_prefix. More - query types will be added later, such as + function ZOOM_query_prefix. + The ZOOM_query_cql specifies a CQL + query to be sent to the server/target. + More query types will be added in future versions of &yaz;, such as CCL to RPN-mapping, native CCL query, etc. In addition to a search, a sort criteria may be set. Function ZOOM_query_sortby specifies a @@ -368,7 +400,7 @@ - Protocol behavior + Z39.50 Protocol behavior The creation of a result set involves at least a SearchRequest - SearchResponse protocol handshake. Following that, if a sort @@ -418,6 +450,47 @@ to specify one elementSetName option rather than three. + + SRW Protocol behavior + + Current version of &yaz; does not take advantage of a result set id + returned by the SRW server. Future versions might do, however. + Since, the ZOOM driver does not save result set IDs any + present (retrieval) is transformed to a SRW SearchRetrieveRequest + with same query but, possibly, different offsets. + + + Option schema specifies SRW schema + for retrieval. However, options elementSetName and + preferredRecordSyntax are ignored. + + + Options start and count + are supported by SRW. + The remaining options + piggyback, + smallSetUpperBound, + largeSetLowerBound, + mediumSetPresentNumber, + mediumSetElementSetName, + smallSetElementSetName are + unsupported. + + + SRW supports CQL queries, not PQF. + If PQF is used, however, the PQF query is transferred anyway + using non-standard element pQuery in + SRW SearchRetrieveRequest. + + + Unfortunately, SRW does not define a database setting. Hence, + databaseName is unsupported and ignored. + However, the path part in host parameter for functions + ZOOM_connecton_new and + ZOOM_connection_connect acts as a + database (at least for the &yaz; SRW server). + + Records @@ -508,7 +581,7 @@ - Protocol behavior + Z39.50 Protocol behavior The functions ZOOM_resultset_record and ZOOM_resultset_records inspects the client-side @@ -527,6 +600,13 @@ now. + SRW Protocol behavior + + The ZOOM driver for SRW treats records returned by a SRW server + as if they where Z39.50 records with transfer syntax XML and + no element set name or database name. + + Scan @@ -535,6 +615,12 @@ is the ZOOM_scanset which is a set of terms returned by a target. + + + The Scan interface is Z39.50 only. SRW version 1.0 does not + support this. + + ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c, const char *startterm); -- 1.7.10.4