-<!-- $Id: zoom.xml,v 1.21 2002-12-09 23:32:29 adam Exp $ -->
- <chapter id="zoom"><title>Building clients with ZOOM</title>
+<!-- $Id: zoom.xml,v 1.36 2003-11-25 09:55:20 mike Exp $ -->
+ <chapter id="zoom"><title>ZOOM</title>
<para>
&zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
an initiative started by Mike Taylor (Mike is from the UK, which
provide a common Z39.50 client API not bound to a particular
programming language or toolkit.
</para>
+
+ <note>
+ <para>
+ A recent addition to &yaz; is SRW support. You can now make
+ SRW ZOOM connections by specifying scheme <literal>http://</literal>
+ for the hostname for a connection.
+ </para>
+ </note>
+
<para>
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
slash, the following part specifies a database for the connection.
</para>
<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.
+ </para>
+ <para>
Connection objects should be destroyed using the function
<function>ZOOM_connection_destroy</function>.
</para>
charset</entry><entry> Character set for negotiation.
</entry><entry>none</entry></row>
<row><entry>
- targetImplementationId</entry><entry> Implementation ID of target.
+ serverImplementationId</entry><entry>
+ Implementation ID of server. (The old targetImplementationId
+ option is also supported for the benefit of old applications.)
+ </entry><entry>none</entry></row>
+ <row><entry>
+ targetImplementationName</entry><entry>
+ Implementation Name of server. (The old
+ targetImplementationName option is also supported for the
+ benefit of old applications.)
+ </entry><entry>none</entry></row>
+ <row><entry>
+ serverImplementationVersion</entry><entry>
+ Implementation Version of server. (the old
+ targetImplementationVersion option is also supported for the
+ benefit of old applications.)
</entry><entry>none</entry></row>
<row><entry>
- targetImplementationName</entry><entry> Implementation Name of target.
+ databaseName</entry><entry>One or more database names
+ separated by character plus (<literal>+</literal>), which to
+ be used by subsequent search requests on this Connection.
+ </entry><entry>Default</entry></row>
+ <row><entry>
+ piggyback</entry><entry>True (1) if piggyback should be
+ used in searches; false (0) if not.
+ </entry><entry>1</entry></row>
+ <row><entry>
+ smallSetUpperBound</entry><entry>If hits is less than or equal to this
+ value, then target will return all records using small element set name
+ </entry><entry>0</entry></row>
+ <row><entry>
+ largeSetLowerBound</entry><entry>If hits is greater than this
+ value, the target will return no records.
+ </entry><entry>1</entry></row>
+ <row><entry>
+ mediumSetPresentNumber</entry><entry>This value represents
+ the number of records to be returned as part of a search when when
+ hits is less than or equal to large set lower bound and if hits
+ is greater than small set upper bound.
+ </entry><entry>0</entry></row>
+ <row><entry>
+ smallSetElementSetName</entry><entry>
+ The element set name to be used for small result sets.
</entry><entry>none</entry></row>
<row><entry>
- targetImplementationVersion</entry><entry> Implementation Version
- of target.
+ mediumSetElementSetName</entry><entry>
+ The element set name to be for medium-sized result sets.
</entry><entry>none</entry></row>
</tbody>
</tgroup>
of <function>ZOOM_connection_error</function> that is capable of
returning name of diagnostic set in <parameter>dset</parameter>.
</para>
- <sect2><title>Protocol behavior</title>
+ <sect2><title>Z39.50 Protocol behavior</title>
<para>
The calls <function>ZOOM_connection_new</function> and
<function>ZOOM_connection_connect</function> establishes a TCP/IP
API cannot tell the outcome (yet).
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ The SRW 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
+ of &yaz; might honor <literal>implementationName</literal> and
+ put that as part of User-Agent header for HTTP requests.
+ </para>
+ <para>
+ The <literal>charset</literal> is used in the Content-Type header
+ of HTTP requests.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.query"><title>Queries</title>
<para>
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);
</synopsis>
<para>
and destroy them by calling <function>ZOOM_query_destroy</function>.
RPN-queries can be specified in <link linkend="PQF">PQF</link>
notation by using the
- function <function>ZOOM_query_prefix</function>. More
- query types will be added later, such as
+ function <function>ZOOM_query_prefix</function>.
+ The <function>ZOOM_query_cql</function> specifies a CQL
+ query to be sent to the server/target.
+ More query types will be added in future versions of &yaz;, such as
<link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
etc. In addition to a search, a sort criteria may be set. Function
<function>ZOOM_query_sortby</function> specifies a
</thead>
<tbody>
<row><entry>
- piggyback</entry><entry>True (1) if piggyback should be
- used in searches; false (0) if not.
- </entry><entry>1</entry></row>
- <row><entry>
start</entry><entry>Offset of first record to be
retrieved from target. First record has offset 0 unlike the
protocol specifications where first record has position 1.
count</entry><entry>Number of records to be retrieved.
</entry><entry>0</entry></row>
<row><entry>
+ presentChunk</entry><entry>The number of records to be
+ requested from the server in each chunk (present requst). The
+ value 0 means to request all the records in a single chunk.
+ (The old <literal>step</literal>
+ option is also supported for the benefit of old applications.)
+ </entry><entry>0</entry></row>
+ <row><entry>
elementSetName</entry><entry>Element-Set name of records.
Most targets should honor element set name <literal>B</literal>
and <literal>F</literal> for brief and full respectively.
<literal>Gils-schema</literal>, <literal>Geo-schema</literal>, etc.
</entry><entry>none</entry></row>
<row><entry>
- smallSetUpperBound</entry><entry>If hits is less than or equal to this
- value, then target will return all records using small element set name
- </entry><entry>0</entry></row>
- <row><entry>
- largeSetLowerBound</entry><entry>If hits is greater than this
- value, the target will return no records.
- </entry><entry>1</entry></row>
- <row><entry>
- mediumSetPresentNumber</entry><entry>This value represents
- the number of records to be returned as part of a search when when
- hits is less than or equal to large set lower bound and if hits
- is greater than small set upper bound.
- </entry><entry>0</entry></row>
- <row><entry>
- smallSetElementSetName</entry><entry>
- The element set name to be used for small result sets.
- </entry><entry>none</entry></row>
- <row><entry>
- mediumSetElementSetName</entry><entry>
- The element set name to be for medium-sized result sets.
- </entry><entry>none</entry></row>
- <row><entry>
- databaseName</entry><entry>One or more database names
- separated by character plus (<literal>+</literal>).
- </entry><entry>Default</entry></row>
- <row><entry>
setname</entry><entry>Name of Result Set (Result Set ID).
If this option isn't set, the ZOOM module will automatically
allocate a result set name.
</tgroup>
</table>
<sect2>
- <title>Protocol behavior</title>
+ <title>Z39.50 Protocol behavior</title>
<para>
The creation of a result set involves at least a SearchRequest
- SearchResponse protocol handshake. Following that, if a sort
perform sorting before any retrieval takes place, so no records will
be returned from the target as part of the SearchResponse because these
would be unsorted. Hence, piggyback is disabled when sort criteria
- is set. Following Search - and a Possible sort, Retrieval takes
- place - as one or more Present Requests - Present Response being
+ are set. Following Search - and a possible sort - Retrieval takes
+ place - as one or more Present Requests/Response pairs being
transferred.
</para>
<para>
The API allows for two different modes for retrieval. A high level
mode which is somewhat more powerful and a low level one.
- The low level is "enabled" when the settings
+ The low level is enabled when searching on a Connection object
+ for which the settings
<literal>smallSetUpperBound</literal>,
<literal>mediumSetPresentNumber</literal> and
<literal>largeSetLowerBound</literal> are set. The low level mode
to specify one elementSetName option rather than three.
</para>
</sect2>
+ <sect2>
+ <title>SRW 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.
+ 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.
+ </para>
+ <para>
+ Option <literal>schema</literal> specifies SRW 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.
+ The remaining options
+ <literal>piggyback</literal>,
+ <literal>smallSetUpperBound</literal>,
+ <literal>largeSetLowerBound</literal>,
+ <literal>mediumSetPresentNumber</literal>,
+ <literal>mediumSetElementSetName</literal>,
+ <literal>smallSetElementSetName</literal> are
+ unsupported.
+ </para>
+ <para>
+ SRW 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.
+ </para>
+ <para>
+ Unfortunately, SRW 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).
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.records"><title>Records</title>
<para>
<function>ZOOM_record_get</function> is provided. The
function returns a pointer to certain record information. The
nature (type) of the pointer depends on the parameter,
- <function>type</function>.
+ <parameter>type</parameter>.
+ </para>
+ <para>
+ The <parameter>type</parameter> is a string of the format:
+ </para>
+ <para>
+ <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
+ </para>
+ <para>
+ where <replaceable>form</replaceable> specifies the format of the
+ returned record, <replaceable>from</replaceable>
+ specifies the character set of the record in its original form
+ (as returned by the server), <replaceable>to</replaceable> specifies
+ the output (returned)
+ character set encoding.
+ If charset is not given, then no character set conversion takes place.
+ If <replaceable>to</replaceable> is omitted UTF-8 is assumed.
+ </para>
+ <para>
In addition, for certain types, the length
<literal>len</literal> passed will be set to the size in bytes of
- the returned information.
+ the returned information.
+ </para>
+ <para>
+ The following are the supported values for <replaceable>form</replaceable>.
<variablelist>
<varlistentry><term><literal>database</literal></term>
<listitem><para>Database of record is returned
as a C null-terminated string. Return type
<literal>const char *</literal>.
</para></listitem>
- </varlistentry>
+ </varlistentry>
<varlistentry><term><literal>syntax</literal></term>
- <listitem><para>The transfer syntax (OID) of the record is returned
- as a C null-terminated string. Return type is
+ <listitem><para>The transfer syntax of the record is returned
+ as a C null-terminated string containing the symbolic name of
+ the record syntax, e.g. <literal>Usmarc</literal>. Return type
+ is
<literal>const char *</literal>.
</para></listitem>
- </varlistentry>
+ </varlistentry>
<varlistentry><term><literal>render</literal></term>
<listitem><para>The record is returned in a display friendly
format. Upon completion buffer is returned
(type <literal>const char *</literal>) and length is stored in
<literal>*len</literal>.
</para></listitem>
- </varlistentry>
+ </varlistentry>
<varlistentry><term><literal>raw</literal></term>
<listitem><para>The record is returned in the internal
YAZ specific format. For GRS-1, Explain, and others, the
For SUTRS and octet aligned record (including all MARCs) the
octet buffer is returned and the length of the buffer.
</para></listitem>
- </varlistentry>
+ </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
+ returned verbatim. MARC records are returned in
+ <ulink url="http://www.loc.gov/standards/marcxml/">
+ MARCXML
+ </ulink>
+ (converted from ISO2709 to MARCXML by YAZ).
+ GRS-1 and OPAC records are not supported for this form.
+ Upon completion, the XML buffer is returned
+ (type <literal>const char *</literal>) and length is stored in
+ <literal>*len</literal>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>opac</literal></term>
+ <listitem><para>OPAC for record is returned in XML.
+ </para></listitem>
+ </varlistentry>
</variablelist>
</para>
- <sect2><title>Protocol behavior</title>
+ <para>
+ Most
+ <ulink url="http://www.loc.gov/marc/">
+ MARC21
+ </ulink>
+ records uses the
+ <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
+ MARC-8
+ </ulink>
+ character set encoding.
+ An application that wishes to display in Latin-1 would use
+ <screen>
+ render; charset=marc8,iso-8859-1
+ </screen>
+ </para>
+ <sect2><title>Z39.50 Protocol behavior</title>
<para>
The functions <function>ZOOM_resultset_record</function> and
<function>ZOOM_resultset_records</function> inspects the client-side
<para>
There is a trick, however, in the usage of function
<function>ZOOM_resultset_records</function> that allows for
- delayed retrieval (and makes it non-blocking). By passing
+ delayed retrieval (and makes it non-blocking). By using
a null pointer for <parameter>recs</parameter> you're indicating
you're not interested in getting records objects
<emphasis>now</emphasis>.
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ 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.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.scan"><title>Scan</title>
<para>
is the <literal>ZOOM_scanset</literal> which is a set of terms
returned by a target.
</para>
+
+ <para>
+ The Scan interface is Z39.50 only. SRW version 1.0 does not
+ support this.
+ </para>
+
<synopsis>
ZOOM_scanset ZOOM_connection_scan (ZOOM_connection c,
const char *startterm);
const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
int *occ, size_t *len);
+ const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
+ int *occ, size_t *len);
void ZOOM_scanset_destroy (ZOOM_scanset scan);
<para>
The scan set is created by function
<function>ZOOM_connection_scan</function> which performs a scan
- operation on the connection and start term given.
+ operation on the connection using the specified startterm.
If the operation was successful, the size of the scan set can be
retrieved by a call to <function>ZOOM_scanset_size</function>.
Like result sets, the items are numbered 0,..size-1.
To obtain information about a particular scan term, call function
<function>ZOOM_scanset_term</function>. This function takes
a scan set offset <literal>pos</literal> and returns a pointer
- to an actual term or <literal>NULL</literal> if non-present.
+ to a <emphasis>raw term</emphasis> or <literal>NULL</literal> if
+ non-present.
If present, the <literal>occ</literal> and <literal>len</literal>
are set to the number of occurrences and the length
of the actual term respectively.
+ <function>ZOOM_scanset_display_term</function> is similar to
+ <function>ZOOM_scanset_term</function> except that it returns
+ the <emphasis>display term</emphasis> rather than the raw term.
+ In a few cases, the term is different from display term. Always
+ use the display term for display and the raw term for subsequent
+ scan operations (to get more terms, next scan result, etc).
+ </para>
+ <para>
A scan set may be freed by a call to function
<function>ZOOM_scanset_destroy</function>.
Functions <function>ZOOM_scanset_option_get</function> and
projects / yaz-moved-to-github.git / blobdiff