ZOOM_options_get_bool(opt, name, defa)
ZOOM_options_get_int(opt, name, defa)
ZOOM_options_set_int(opt, name, value)
+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.44 2005-11-16 16:04:19 mike Exp $ -->
+<!-- $Id: zoom.xml,v 1.55 2006-12-06 11:12:14 mike 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>
- for the hostname for a connection.
+ 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. The dialect of SRU used is
+ specified by the value of the connection's <literal>sru</literal>
+ option, which may be SRU over HTTP GET (<literal>get</literal>),
+ SRU over HTTP POST (<literal>post</literal>) or SRW (SRU over
+ SOAP) (<literal>soap</literal>).
</para>
</note>
There are other language bindings available for &yaz;, and still
more
are in active development. See the
- <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
+ <ulink url="&url.zoom;">ZOOM web-site</ulink> for
more information.
</para>
protocol behavior, that describes how the API maps to the Z39.50
protocol.
</para>
- <sect1 id="zoom.connections"><title>Connections</title>
+ <sect1 id="zoom-connections"><title>Connections</title>
<para>The Connection object is a session with a target.
</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.
+ The scheme <literal>http</literal> selects SRU over HTTP.
+ </para>
+ <para>
+ You can prefix the scheme-qualified host-string with one or more
+ comma-separated
+ <literal><parameter>key</parameter>=<parameter>value</parameter></literal>
+ sequences, each of which represents an option to be set into the
+ connection structure <emphasis>before</emphasis> the
+ protocol-level connection is forged and the initialisation
+ handshake takes place. This facility can be used to provide
+ authentication credentials, as in host-strings such as:
+ <literal>user=admin,password=halfAm4n,tcp:localhost:8017/db</literal>
</para>
<para>
Connection objects should be destroyed using the function
<function>ZOOM_connection_option_getl</function> returns
the value for an option given by <parameter>key</parameter>.
</para>
- <table frame="top"><title>ZOOM Connection Options</title>
+ <table id="zoom-connection-options" frame="top">
+ <title>ZOOM Connection Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
mediumSetElementSetName</entry><entry>
The element set name to be for medium-sized result sets.
</entry><entry>none</entry></row>
+ <row><entry>
+ init_opt_search, init_opt_present, init_opt_delSet, etc.</entry><entry>
+ After a successful Init, these options may be interrogated to
+ discover whether the server claims to support the specified
+ operations.
+ </entry><entry>none</entry></row>
</tbody>
</tgroup>
</table>
<para>
If either option <literal>lang</literal> or <literal>charset</literal>
is set, then
- <ulink url="http://lcweb.loc.gov/z3950/agency/defns/charneg-3.html">
+ <ulink url="&url.z39.50.charneg;">
Character Set and Language Negotiation</ulink> is in effect.
</para>
<synopsis>
of <function>ZOOM_connection_error</function> that is capable of
returning name of diagnostic set in <parameter>dset</parameter>.
</para>
- <sect2><title>Z39.50 Protocol behavior</title>
+ <sect2 id="zoom-connection-z39.50">
+ <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>
+ <sect2 id="zoom.sru.init.behavior">
+ <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>
sort criteria using the same string notation for sort as offered by
the <link linkend="sortspec">YAZ client</link>.
</para>
- <sect2><title>Protocol behavior</title>
+ <sect2 id="zoom.sort.behavior"><title>Protocol behavior</title>
<para>
The query object is just an interface for the member Query
in the SearchRequest. The sortby-function is an interface to the
The number of hits also called result-count is returned by
function <function>ZOOM_resultset_size</function>.
</para>
- <table frame="top"><title>ZOOM Result set Options</title>
+ <table id="zoom.resultset.options"
+ frame="top"><title>ZOOM Result set Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
Read <literal>searchresult.size</literal> to determine the
number of items.
</para>
- <table frame="top"><title>Search Info Report options</title>
+ <table id="zoom.search.info.report.options"
+ frame="top"><title>Search Info Report Options</title>
<tgroup cols="2">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</tbody>
</tgroup>
</table>
- <sect2>
+ <sect2 id="zoom.z3950.resultset.behavior">
<title>Z39.50 Protocol behavior</title>
<para>
The creation of a result set involves at least a SearchRequest
to specify one elementSetName option rather than three.
</para>
</sect2>
- <sect2>
- <title>SRW Protocol behavior</title>
+ <sect2 id="zoom.sru.resultset.behavior">
+ <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>
created from result sets.
</para>
<synopsis>
- void ZOOM_resultset_records (ZOOM_resultset r,
- ZOOM_record *recs,
- size_t start, size_t count);
- ZOOM_record ZOOM_resultset_record (ZOOM_resultset s, size_t pos);
+ void ZOOM_resultset_records(ZOOM_resultset r,
+ ZOOM_record *recs,
+ size_t start, size_t count);
+ ZOOM_record ZOOM_resultset_record(ZOOM_resultset s, size_t pos);
- const char *ZOOM_record_get (ZOOM_record rec, const char *type,
- size_t *len);
+ const char *ZOOM_record_get(ZOOM_record rec, const char *type,
+ size_t *len);
+
+ int ZOOM_record_error(ZOOM_record rec, const char **msg,
+ const char **addinfo, const char **diagset);
ZOOM_record ZOOM_record_clone (ZOOM_record rec);
If no record could be obtained <literal>NULL</literal> is returned.
</para>
<para>
+ Error information for a record can be checked with
+ <function>ZOOM_record_error</function> which returns non-zero
+ (error code) if record is in error, called <emphasis>Surrogate
+ Diagnostics</emphasis> in Z39.50.
+ </para>
+ <para>
Function <function>ZOOM_resultset_records</function> retrieves
a number of records from a result set. Parameter <literal>start</literal>
and <literal>count</literal> specifies the range of records to
</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="http://www.loc.gov/standards/marcxml/">
+ <ulink url="&url.marcxml;">
MARCXML
</ulink>
(converted from ISO2709 to MARCXML by YAZ).
</para>
<para>
Most
- <ulink url="http://www.loc.gov/marc/">
- MARC21
- </ulink>
+ <ulink url="&url.marc21;">MARC21</ulink>
records uses the
- <ulink url="http://www.loc.gov/marc/specifications/speccharmarc8.html">
- MARC-8
- </ulink>
+ <ulink url="&url.marc8;">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>
+ <sect2 id="zoom.z3950.record.behavior">
+ <title>Z39.50 Protocol behavior</title>
<para>
The functions <function>ZOOM_resultset_record</function> and
<function>ZOOM_resultset_records</function> inspects the client-side
<emphasis>now</emphasis>.
</para>
</sect2>
- <sect2><title>SRW Protocol behavior</title>
+ <sect2 id="zoom.sru.record.behavior">
+ <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>
</literallayout>
</para>
- <table frame="top"><title>ZOOM Scan Set Options</title>
+ <table frame="top" id="zoom.scanset.options">
+ <title>ZOOM Scan Set Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</table>
</sect1>
- <sect1 id="zoom.ext"><title>Extended Services</title>
+ <sect1 id="zoom.extendedservices"><title>Extended Services</title>
<para>
ZOOM offers an interface to a subset of the Z39.50 extended services
as well as a few privately defined ones:
<listitem>
<para>
Z39.50 Item Order (ILL).
- See <xref linkend="zoom.ext.itemorder"/>.
+ See <xref linkend="zoom.item.order"/>.
</para>
</listitem>
<listitem>
<para>
Record Update. This allows a client to insert, modify or delete
records.
- See <xref linkend="zoom.ext.update"/>.
+ See <xref linkend="zoom.record.update"/>.
</para>
</listitem>
<listitem>
<para>
Database Create. This a non-standard feature. Allows a client
to create a database.
- See <xref linkend="zoom.ext.dbcreate"/>.
+ See <xref linkend="zoom.database.create"/>.
</para>
</listitem>
<listitem>
<para>
Database Drop. This a non-standard feature. Allows a client
to delete/drop a database.
- See <xref linkend="zoom.ext.dbdrop"/>.
+ See <xref linkend="zoom.database.drop"/>.
</para>
</listitem>
<listitem>
<para>
Commit operation. This a non-standard feature. Allows a client
to commit operations.
- See <xref linkend="zoom.ext.commit"/>.
+ See <xref linkend="zoom.commit"/>.
</para>
</listitem>
<!-- all the ILL PDU options should go here too -->
package type to be sent.
</para>
- <table frame="top"><title>Extended Service Common Options</title>
+ <table frame="top" id="zoom.extendedservices.options">
+ <title>Extended Service Common Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</tgroup>
</table>
- <sect2 id="zoom.ext.itemorder"><title>Item Order</title>
+ <sect2 id="zoom.item.order"><title>Item Order</title>
<para>
For Item Order, type must be set to <literal>itemorder</literal> in
<function>ZOOM_package_send</function>.
</para>
- <table frame="top"><title>Item Order Options</title>
+ <table frame="top" id="zoom.item.order.options">
+ <title>Item Order Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</sect2>
- <sect2 id="zoom.ext.update"><title>Record Update</title>
+ <sect2 id="zoom.record.update"><title>Record Update</title>
<para>
For Record Update, type must be set to <literal>update</literal> in
<function>ZOOM_package_send</function>.
</para>
- <table frame="top"><title>Record Update Options</title>
+ <table frame="top" id="zoom.record.update.options">
+ <title>Record Update Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</sect2>
- <sect2 id="zoom.ext.dbcreate"><title>Database Create</title>
+ <sect2 id="zoom.database.create"><title>Database Create</title>
<para>
For Database Create, type must be set to <literal>create</literal> in
<function>ZOOM_package_send</function>.
</para>
- <table frame="top"><title>Database Create Options</title>
+ <table frame="top" id="zoom.database.create.options">
+ <title>Database Create Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</table>
</sect2>
- <sect2 id="zoom.ext.dbdrop"><title>Database Drop</title>
+ <sect2 id="zoom.database.drop"><title>Database Drop</title>
<para>
For Database Drop, type must be set to <literal>drop</literal> in
<function>ZOOM_package_send</function>.
</para>
- <table frame="top"><title>Database Create Options</title>
+ <table frame="top" id="zoom.database.drop.options">
+ <title>Database Drop Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>
</table>
</sect2>
- <sect2 id="zoom.ext.commit"><title>Commit Operation</title>
+ <sect2 id="zoom.commit"><title>Commit Operation</title>
<para>
For Commit, type must be set to <literal>commit</literal> in
<function>ZOOM_package_send</function>.
</para>
</sect2>
- <sect2><title>Protocol behavior</title>
+ <sect2 id="zoom.extended.services.behavior">
+ <title>Protocol behavior</title>
<para>
All the extended services are Z39.50-only.
</para>
(integer) for the last event.
</para>
- <table frame="top"><title>ZOOM Event IDs</title>
+ <table frame="top" id="zoom.event.ids">
+ <title>ZOOM Event IDs</title>
<tgroup cols="2">
<colspec colwidth="4*" colname="name"></colspec>
<colspec colwidth="7*" colname="description"></colspec>