-<!-- $Id: client.xml,v 1.18 2006-04-25 11:25:08 marc Exp $ -->
+<!-- $Id: client.xml,v 1.19 2006-06-13 16:01:51 adam Exp $ -->
<chapter id="client"><title>The YAZ client</title>
<sect1 id="client.introduction"><title>Introduction</title>
<para>
- yaz-client is a line-mode Z39.50/SRW client. It supports a fair amount
+ yaz-client is a line-mode Z39.50/SRU client. It supports a fair amount
of the functionality of the Z39.50v3 standard.
Its primary purpose is to exercise the package, and verify that
the protocol works OK.
<simpara>
in a UNIX shell / WIN32 console. The <replaceable>zurl</replaceable>,
- specifies a Z39.50/SRW host and, if specified, the client first tries to
- establish connection with the Z39.50/SRW target.
+ specifies a Z39.50/SRU host and, if specified, the client first tries to
+ establish connection with the Z39.50/SRU target.
</simpara>
<simpara>
Options are prefixed by <literal>-</literal> followed by a
</screen>
</para>
<para>
- The same server is also a SOAP SRW service. Connect to it via HTTP
+ The same server is also a SRU service. Connect to it via HTTP
as follows:
<screen>
yaz-client http://bagel.indexdata.dk:210/marc
-<!-- $Id: frontend.xml,v 1.29 2006-04-25 11:25:08 marc Exp $ -->
+<!-- $Id: frontend.xml,v 1.30 2006-06-13 16:01:51 adam Exp $ -->
<chapter id="server"><title>Generic server</title>
<sect1><title>Introduction</title>
<para>
If you have a database system that you would like to make available by
- means of Z39.50, SRW o SRU, &yaz; basically offers your two options. You
+ means of Z39.50 or SRU, &yaz; basically offers your two options. You
can use the APIs provided by the &asn;, &odr;, and &comstack;
modules to
create and decode PDUs, and exchange them with a client.
</para></listitem>
<listitem><para>
- Return Explain for SRW/SRU (optional).
+ Return Explain for SRU (optional).
</para></listitem>
</itemizedlist>
</para>
<para>
- This handler is also called when operating in SRW/SRU mode - when
- a connection has been made (even though SRW/SRU does not offer
+ This handler is also called when operating in SRU mode - when
+ a connection has been made (even though SRU does not offer
this service).
</para>
<para>
The <function>bend_search</function> handler is also called when
- the frontend server receives a SRW/SRU SearchRetrieveRequest.
- For SRW/SRU, a CQL query is usually provided by the client.
+ the frontend server receives a SRU SearchRetrieveRequest.
+ For SRU, a CQL query is usually provided by the client.
The CQL query is available as part of <literal>Z_Query</literal>
structure (note that CQL is now part of Z39.50 via an external).
To support CQL in existing implementations that only do Type-1,
<para>
To maintain backwards compatibility, the frontend server
of yaz always assume that error codes are BIB-1 diagnostics.
- For SRW/SRU operation, a Bib-1 diagnostic code is mapped to
- SRW/SRU diagnostic.
+ For SRU operation, a Bib-1 diagnostic code is mapped to
+ SRU diagnostic.
</para>
<synopsis>
<para>
The frontend server calls the <function>bend_fetch</function> handler
when it needs database records to fulfill a Z39.50 Search Request, a
- Z39.50 Present Request or a SRW SearchRetrieveRequest.
+ Z39.50 Present Request or a SRU SearchRetrieveRequest.
The <literal>setname</literal> is simply the name of the result set
that holds the reference to the desired record.
The <literal>number</literal> is the offset into the set (with 1
</para>
<para>
- If a SRW/SRU SearchRetrieveRequest is received by the frontend server,
+ If a SRU SearchRetrieveRequest is received by the frontend server,
the <literal>referenceId</literal> is NULL and the
<literal>request_format</literal> (transfer syntax) is XML (OID name
<literal>VAL_TEXT_XML</literal>).
- The schema for SRW/SRU is stored in both the
+ The schema for SRU is stored in both the
<literal>Z_RecordComposition</literal>
structure and <literal>schema</literal> (simple string).
</para>
</synopsis>
<para>
This backend server handles both Z39.50 scan
- and SRW/SRU scan. In order for a
- handler to distinguish between SRW/SRU (CQL) scan
+ and SRU scan. In order for a handler to distinguish between SRU (CQL) scan
Z39.50 Scan , it must check for a non-NULL value of
<literal>scanClause</literal>.
</para>
</screen>
</para>
<para>
- The server will accept Z39.50 requests and offer SRW/SRU service
- on port 210.
+ The server will accept Z39.50 requests and offer SRU service on port 210.
</para>
</example>
- <example><title>Setting up Apache as SRW/SRU Frontend</title>
+ <example><title>Setting up Apache as SRU Frontend</title>
<para>
If you use <ulink url="&url.apache;">Apache</ulink>
as your public web server and want to offer HTTP port 80
-<!-- $Id: introduction.xml,v 1.23 2006-04-25 11:25:08 marc Exp $ -->
+<!-- $Id: introduction.xml,v 1.24 2006-06-13 16:01:51 adam Exp $ -->
<chapter id="introduction"><title>Introduction</title>
<para>
&yaz; is a C/C++ library for information retrieval applications
- using the Z39.50/SRW/SRU protocols for information retrieval.
+ using the Z39.50/SRU protocols for information retrieval.
</para>
<para>
</para></listitem>
<listitem><para>
Supports
- <ulink url="&url.sru;">SRW/SRU</ulink>
+ <ulink url="&url.sru;">SRU GET/POST/SOAP</ulink>
version 1.1 (over HTTP and HTTPS).
</para></listitem>
<listitem><para>
<listitem><para>
Offers
<ulink url="&url.zoom;">ZOOM</ulink> C API implementing both
- Z39.50 and SRW.
+ Z39.50 and SRU.
</para></listitem>
<listitem><para>
The &yaz; library offers a set of useful utilities
<listitem>
<para>
<xref linkend="zoom"/> describes the ZOOM API of &yaz;.
- This is definitely worth a read if you wish to develop a Z39.50/SRW
- client.
- </para>
+ This is definitely worth a read if you wish to develop a Z39.50/SRU
+ client.
+ </para>
</listitem>
<listitem>
<para>
<xref linkend="server"/> 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.
+ and explains how to develop server Z39.50/SRU applications for &yaz;.
+ Obviously worth reading if you're to develop a server.
</para>
</listitem>
<listitem>
<para>
- <xref linkend="soap"/> describes how SRW and SOAP is used
- in &yaz;. Only if you're developing SOAP/SRW applications
+ <xref linkend="soap"/> describes how SRU and SOAP is used
+ in &yaz;. Only if you're developing SRU applications
this section is a must.
</para>
</listitem>
<para>
<xref linkend="tools"/> contains sections for the various
tools offered by &yaz;. Scan through the material quickly
- and see what's relevant to you! SRW/SRU implementors
+ and see what's relevant to you! SRU implementors
might find the <link linkend="tools.cql">CQL</link> section
particularly useful.
</para>
<para>
The second layer provides a C represenation of the
protocol units (packages) for Z39.50 ASN.1, ILL ASN.1,
- SRW SOAP.
+ SRU.
</para>
</listitem>
<listitem>
-<!-- $Id: soap.xml,v 1.6 2006-04-24 09:21:35 adam Exp $ -->
-<chapter id="soap"><title>SOAP and SRW</title>
+<!-- $Id: soap.xml,v 1.7 2006-06-13 16:01:51 adam Exp $ -->
+<chapter id="soap"><title>SOAP and SRU</title>
<sect1 id="soap.introduction"><title>Introduction</title>
<para>
&yaz; uses a very simple implementation of
<ulink url="&url.soap;">SOAP</ulink> that only,
- currenly, supports what is sufficient to offer SRW functionality.
+ currenly, supports what is sufficient to offer SRU SOAP functionality.
The implementation uses the
<ulink url="&url.libxml2.api.tree;">tree API</ulink> of
libxml2 to encode and decode SOAP packages.
</para>
<para>
- Like the Z39.50 ASN.1 module, the &yaz; SRW implementation uses
+ Like the Z39.50 ASN.1 module, the &yaz; SRU implementation uses
simple C structs to represent SOAP packages as well as
HTTP packages.
</para>
</para>
<para>
The <literal>handlers</literal> is a list of SOAP codec
- handlers - one handler for each service namespace. For SRW, the
+ handlers - one handler for each service namespace. For SRU SOAP, the
namespace would be <literal>http://www.loc.gov/zing/srw/v1.0/</literal>.
</para>
<para>
Finally, <parameter>ns</parameter> the service namespace.
</para>
</sect1>
- <sect1 id="soap.srw"><title>SRW</title>
+ <sect1 id="soap.srw"><title>SRU</title>
<para>
- SRW is just one implementation of a SOAP handler as described
+ SRU SOAP is just one implementation of a SOAP handler as described
in the previous section.
- The encoder/decoder handler for SRW is defined as
+ The encoder/decoder handler for SRU is defined as
follows:
<synopsis>
#include <yaz/srw.h>
-<!-- $Id: tools.xml,v 1.49 2006-04-25 11:25:08 marc Exp $ -->
+<!-- $Id: tools.xml,v 1.50 2006-06-13 16:01:51 adam Exp $ -->
<chapter id="tools"><title>Supporting Tools</title>
<para>
<para>
<ulink url="&url.cql;">CQL</ulink>
- Common Query Language - was defined for the
- <ulink url="&url.srw;">SRW</ulink> protocol.
+ <ulink url="&url.sru;">SRU</ulink> protocol.
In many ways CQL has a similar syntax to CCL.
The objective of CQL is different. Where CCL aims to be
an end-user language, CQL is <emphasis>the</emphasis> protocol
- query language for SRW.
+ query language for SRU.
</para>
<tip>
<para>
<listitem>
<para>
The parser converts a valid CQL query to PQF, thus providing a
- way to use CQL for both SRW/SRU servers and Z39.50 targets at the
+ way to use CQL for both SRU servers and Z39.50 targets at the
same time.
</para>
</listitem>
The parser converts CQL to
<ulink url="&url.xcql;">XCQL</ulink>.
XCQL is an XML representation of CQL.
- XCQL is part of the SRW specification. However, since SRU
+ XCQL is part of the SRU specification. However, since SRU
supports CQL only, we don't expect XCQL to be widely used.
Furthermore, CQL has the advantage over XCQL that it is
easy to read.
Conversion to PQF (and Z39.50 RPN) is tricky by the fact
that the resulting RPN depends on the Z39.50 target
capabilities (combinations of supported attributes).
- In addition, the CQL and SRW operates on index prefixes
+ In addition, the CQL and SRU operates on index prefixes
(URI or strings), whereas the RPN uses Object Identifiers
for attribute sets.
</para>
</para>
<para>
If conversion failed, <function>cql_transform_buf</function>
- returns a non-zero SRW error code; otherwise zero is returned
+ returns a non-zero SRU error code; otherwise zero is returned
(conversion successful). The meanings of the numeric error
- codes are listed in the SRW specifications at
+ codes are listed in the SRU specifications at
<ulink url="&url.sru.diagnostics.list;"/>
</para>
<para>
context set that was not recognised.
</para>
<para>
- The SRW error-codes may be translated into brief human-readable
+ The SRU error-codes may be translated into brief human-readable
error messages using
<synopsis>
const char *cql_strerror(int code);
<!--
- $Id: yaz-client-commands.xml,v 1.15 2006-06-02 13:12:54 adam Exp $
+ $Id: yaz-client-commands.xml,v 1.16 2006-06-13 16:01:51 adam Exp $
Commands for YAZ client.
Included in both manual and man page for yaz-client.
-->
<listitem>
<para>Specifies schema for retrieval.
Schema may be specified as an OID for Z39.50.
- For SRW, schema is a simple string URI.
+ For SRU, schema is a simple string URI.
</para>
</listitem>
</varlistentry>
</term>
<listitem>
<para>Specifies character set (encoding) for Z39.50
- negotiation / SRW encoding and/or character set for output (terminal).
+ negotiation / SRU encoding and/or character set for output (terminal).
</para>
<para>
<replaceable>negotiationcharset</replaceable> is the name
<!ENTITY % common SYSTEM "common/common.ent">
%common;
]>
-<!-- $Id: yaz-client-man.xml,v 1.10 2006-05-28 19:56:25 adam Exp $ -->
+<!-- $Id: yaz-client-man.xml,v 1.11 2006-06-13 16:01:51 adam Exp $ -->
<refentry id="yaz-client">
<refmeta>
<refnamediv>
<refname>yaz-client</refname>
- <refpurpose>Z39.50/SRW client for implementors</refpurpose>
+ <refpurpose>Z39.50/SRU client for implementors</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsect1><title>DESCRIPTION</title>
<para>
- <command>yaz-client</command> is a Z39.50/SRW client (origin) with a
+ <command>yaz-client</command> is a Z39.50/SRU client (origin) with a
simple command line interface that allows you to test behavior and
- performance of Z39.50 targets and SRW servers.
+ performance of Z39.50 targets and SRU servers.
</para>
<para>
If the <replaceable>addr</replaceable> is specified, the client creates
- a connection to the Z39.50/SRW target at the address given.
+ a connection to the Z39.50/SRU target at the address given.
</para>
<para>
When <command>yaz-client</command> is invoked it attemps to read the
<!ENTITY % common SYSTEM "common/common.ent">
%common;
]>
-<!-- $Id: yaz-man.xml,v 1.9 2006-05-28 19:56:25 adam Exp $ -->
+<!-- $Id: yaz-man.xml,v 1.10 2006-06-13 16:01:51 adam Exp $ -->
<refentry id="yaz">
<refmeta>
<refentrytitle>yaz</refentrytitle>
<para>
YAZ is a C/C++ programmer's toolkit supporting the development
of Z39.50v3 clients and servers. The YAZ toolkit offers
- several different levels of access to the ISO23950/Z39.50, SRW/SRU
+ several different levels of access to the ISO23950/Z39.50, SRU
and ILL protocols. The level that you need to use depends
on your requirements, and the role (server of client) that you want
to implement.
ZOOM_connection_scan1 (ZOOM_connection c, ZOOM_query startterm)
ZOOM_query_cql2rpn(ZOOM_query s, const char *str, ZOOM_connection conn)
-->
-<!-- $Id: zoom.xml,v 1.49 2006-04-25 11:25:08 marc Exp $ -->
+<!-- $Id: zoom.xml,v 1.50 2006-06-13 16:01:51 adam Exp $ -->
<chapter id="zoom"><title>ZOOM</title>
<para>
&zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
<note>
<para>
- A recent addition to &yaz; is SRW support. You can now make
- SRW ZOOM connections by specifying scheme <literal>http://</literal>
+ A recent addition to &yaz; is SRU support. You can now make
+ SRU ZOOM connections by specifying scheme <literal>http://</literal>
for the hostname for a connection.
</para>
</note>
<para>
You can prefix the host with a scheme followed by colon. The
default scheme is <literal>tcp</literal> (Z39.50 protocol).
- The scheme <literal>http</literal> selects SRW over HTTP.
+ The scheme <literal>http</literal> selects SRU over HTTP.
</para>
<para>
You can prefix the scheme-qualified host-string with one or more
API cannot tell the outcome (yet).
</para>
</sect2>
- <sect2><title>SRW Protocol behavior</title>
+ <sect2><title>SRU Protocol behavior</title>
<para>
- The SRW protocol doesn't feature an Inititialize Request, so
+ The SRU protocol doesn't feature an Inititialize Request, so
the connection phase merely establishes a TCP/IP connection
with the SOAP service.
</para>
<para>Most of the ZOOM connection options do not
- affect SRW and they are ignored. However, future versions
+ affect SRU and they are ignored. However, future versions
of &yaz; might honor <literal>implementationName</literal> and
put that as part of User-Agent header for HTTP requests.
</para>
</para>
</sect2>
<sect2>
- <title>SRW Protocol behavior</title>
+ <title>SRU Protocol behavior</title>
<para>
Current version of &yaz; does not take advantage of a result set id
- returned by the SRW server. Future versions might do, however.
+ returned by the SRU 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
+ present (retrieval) is transformed to a SRU SearchRetrieveRequest
with same query but, possibly, different offsets.
</para>
<para>
- Option <literal>schema</literal> specifies SRW schema
+ Option <literal>schema</literal> specifies SRU schema
for retrieval. However, options <literal>elementSetName</literal> and
<literal>preferredRecordSyntax</literal> are ignored.
</para>
<para>
Options <literal>start</literal> and <literal>count</literal>
- are supported by SRW.
+ are supported by SRU.
The remaining options
<literal>piggyback</literal>,
<literal>smallSetUpperBound</literal>,
unsupported.
</para>
<para>
- SRW supports CQL queries, <emphasis>not</emphasis> PQF.
+ SRU supports CQL queries, <emphasis>not</emphasis> PQF.
If PQF is used, however, the PQF query is transferred anyway
using non-standard element <literal>pQuery</literal> in
- SRW SearchRetrieveRequest.
+ SRU SearchRetrieveRequest.
</para>
<para>
- Unfortunately, SRW does not define a database setting. Hence,
+ Unfortunately, SRU does not define a database setting. Hence,
<literal>databaseName</literal> is unsupported and ignored.
However, the path part in host parameter for functions
<function>ZOOM_connecton_new</function> and
<function>ZOOM_connection_connect</function> acts as a
- database (at least for the &yaz; SRW server).
+ database (at least for the &yaz; SRU server).
</para>
</sect2>
</sect1>
</varlistentry>
<varlistentry><term><literal>xml</literal></term>
<listitem><para>The record is returned in XML if possible.
- SRW/SRU and Z39.50 records with transfer syntax XML are
+ SRU and Z39.50 records with transfer syntax XML are
returned verbatim. MARC records are returned in
<ulink url="&url.marcxml;">
MARCXML
<emphasis>now</emphasis>.
</para>
</sect2>
- <sect2><title>SRW Protocol behavior</title>
+ <sect2><title>SRU Protocol behavior</title>
<para>
- The ZOOM driver for SRW treats records returned by a SRW server
+ The ZOOM driver for SRU treats records returned by a SRU server
as if they where Z39.50 records with transfer syntax XML and
no element set name or database name.
</para>
projects / yaz-moved-to-github.git / commitdiff