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 $ -->
<chapter id="zoom"><title>ZOOM</title>
<para>
&zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
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>
+ From YAZ version 2.1.12, <ulink url="&url.sru;">SRU</ulink> is supported.
+ You can 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>), (SRU over
+ SOAP) (<literal>soap</literal>) or <literal>SOLR</literal>
+ (<ulink url="&url.solr;">SOLR</ulink> Web Service).
+ Using the facility for embedding options in target strings, a
+ connection can be forced to use SRU rather the SRW (the default) by
+ prefixing the target string with <literal>sru=get,</literal>, like this:
+ <literal>sru=get,http://sru.miketaylor.org.uk:80/sru.pl</literal>
+ </para>
+ <para>
+ <ulink url="&url.solr;">SOLR</ulink> protocol support was added to YAZ in version 4.1.0,
+ as a dialect of a SRU protocol, since both are HTTP based protocols.
+ </para>
<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
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>
void ZOOM_connection_connect(ZOOM_connection c, const char *host,
int portnum);
- void ZOOM_connection_destroy (ZOOM_connection c);
+ void ZOOM_connection_destroy(ZOOM_connection c);
</synopsis>
<para>
Connection objects are created with either function
<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/get over HTTP by default,
+ but can overridded to use SRU/post, SRW and the SOLR protocol.
+ </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 initialization
+ 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>
It's automatically set internally when connecting to a target.
</entry><entry>none</entry></row>
<row><entry>
- proxy</entry><entry>Proxy host
+ proxy</entry><entry>Proxy host. If set, the logical host
+ is encoded in the otherInfo area of the Z39.50 Init PDU
+ with OID 1.2.840.10003.10.1000.81.1.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ clientIP</entry><entry>Client IP. If set, is
+ encoded in the otherInfo area of a Z39.50 PDU with OID
+ 1.2.840.10003.10.1000.81.3. Holds the original IP addreses
+ of a client. Is used of ZOOM is used in a gateway of some sort.
</entry><entry>none</entry></row>
<row><entry>
async</entry><entry>If true (1) the connection operates in
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>
+ <row>
+ <entry>sru</entry><entry>
+ SRU/SOLR transport type. Must be either <literal>soap</literal>,
+ <literal>get</literal>, <literal>post</literal>, or
+ <literal>solr</literal>.
+ </entry><entry>soap</entry></row>
+ <row><entry>
+ sru_version</entry><entry>
+ SRU/SRW version. Should be <literal>1.1</literal>, or
+ <literal>1.2</literal>. This is , prior to connect, the version
+ to offer (highest version). And following connect (in fact
+ first operation), holds the negotiated version with the server
+ (same or lower version).
+ </entry><entry>1.2</entry></row>
+ <row><entry>
+ facets</entry><entry>
+ A FacetList is comma-separated list of facet, which is defined
+ as <literal>AttributeList</literal> and a optional FacetTerm
+ (a Term and a frequency). On request the terms is missing.
+ On response the the list contains the terms that the target
+ could collect.
+ </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>
- int ZOOM_connection_error (ZOOM_connection c, const char **cp,
- const char **addinfo);
- int ZOOM_connection_error_x (ZOOM_connection c, const char **cp,
- const char **addinfo, const char **dset);
+ int ZOOM_connection_error(ZOOM_connection c, const char **cp,
+ const char **addinfo);
+ int ZOOM_connection_error_x(ZOOM_connection c, const char **cp,
+ const char **addinfo, const char **dset);
</synopsis>
<para>
Function <function>ZOOM_connection_error</function> checks for
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/SOLR Protocol behavior</title>
<para>
- The SRW protocol doesn't feature an Inititialize Request, so
+ The HTTP based protocols (SRU, SRW, SOLR) 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/SOLR 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
a target.
</para>
<synopsis>
- ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
- ZOOM_query q);
+ ZOOM_resultset ZOOM_connection_search(ZOOM_connection, ZOOM_query q);
ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
const char *q);
-
void ZOOM_resultset_destroy(ZOOM_resultset r);
</synopsis>
<para>
Function <function>ZOOM_connection_search</function> creates
- a result set given a connection and query.
+ a result set given a connection and query.
Destroy a result set by calling
<function>ZOOM_resultset_destroy</function>.
Simple clients may using PQF only may use function
creating query objects is not necessary.
</para>
<synopsis>
- void ZOOM_resultset_option_set (ZOOM_resultset r,
- const char *key,
- const char *val);
+ void ZOOM_resultset_option_set(ZOOM_resultset r,
+ const char *key, const char *val);
- const char *ZOOM_resultset_option_get (ZOOM_resultset r,
- const char *key);
+ const char *ZOOM_resultset_option_get(ZOOM_resultset r, const char *key);
- size_t ZOOM_resultset_size (ZOOM_resultset r);
+ size_t ZOOM_resultset_size(ZOOM_resultset r);
</synopsis>
<para>
Functions <function>ZOOM_resultset_options_set</function> and
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>
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.
+ This option affects ZOOM_resultset_search and
+ ZOOM_resultset_search_pqf and must be set before any of
+ these functions are invoked. If a range of
+ records must be fetched manually after search,
+ function ZOOM_resultset_records should be used.
</entry><entry>0</entry></row>
<row><entry>
- count</entry><entry>Number of records to be retrieved.
+ count</entry><entry>Number of records to be retrieved.
+ This option affects ZOOM_resultset_search and
+ ZOOM_resultset_search_pqf and must be set before any of
+ these functions are invoked.
</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
+ requested from the server in each chunk (present request). 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.)
If this option isn't set, the ZOOM module will automatically
allocate a result set name.
</entry><entry>default</entry></row>
+ <row><entry>
+ rpnCharset</entry><entry>Character set for RPN terms.
+ If this is set, ZOOM C will assume that the ZOOM application is
+ running UTF-8. Terms in RPN queries are then converted to the
+ rpnCharset. If this is unset, ZOOM C will not assume any encoding
+ of RPN terms and no conversion is performed.
+ </entry><entry>none</entry></row>
</tbody>
</tgroup>
</table>
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,
+ SOLR queries has to be done in SOLR query format.
+ </para>
+ <para>
+ Unfortunately, SRU or SOLR 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);
+ ZOOM_record ZOOM_record_clone(ZOOM_record rec);
- void ZOOM_record_destroy (ZOOM_record rec);
+ void ZOOM_record_destroy(ZOOM_record rec);
</synopsis>
<para>
References to temporary records are returned by functions
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
The <parameter>type</parameter> is a string of the format:
</para>
<para>
- <replaceable>form</replaceable>[; charset=<replaceable>from</replaceable>[,<replaceable>to</replaceable>]]
+ <replaceable>format</replaceable>[;charset=<replaceable>from</replaceable>[/<replaceable>opacfrom</replaceable>][,<replaceable>to</replaceable>]][;format=<replaceable>v</replaceable>]
</para>
<para>
- where <replaceable>form</replaceable> specifies the format of the
+ where <replaceable>format</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.
+ If charset is not given, then no character set conversion takes place.
+ </para>
+
+ <para>OPAC records may be returned in a different
+ set from the bibliographic MARC record. If this is this the case,
+ <replaceable>opacfrom</replaceable> should be set to the character set
+ of the OPAC record part.
+ </para>
+ <note>
+ <para>
+ Specifying the OPAC record character set requires YAZ 4.1.5 or later.
+ </para>
+ </note>
+ <para>
+ The format argument controls whether record data should be XML
+ pretty-printed (post process operation).
+ It is enabled only if format value <replaceable>v</replaceable> is
+ <literal>1</literal> and the record content is XML well-formed.
</para>
<para>
In addition, for certain types, the length
<literal>const char *</literal>.
</para></listitem>
</varlistentry>
+ <varlistentry><term><literal>schema</literal></term>
+ <listitem><para>The schema of the record is returned
+ as a C null-terminated string. Return type is
+ <literal>const char *</literal>.
+ </para></listitem>
+ </varlistentry>
<varlistentry><term><literal>render</literal></term>
<listitem><para>The record is returned in a display friendly
format. Upon completion buffer is returned
</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, SOLR 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).
- GRS-1 and OPAC records are not supported for this form.
+ OPAC records are also converted to XML and the
+ bibliographic record is converted to MARCXML (when possible).
+ GRS-1 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.
+ <listitem><para>OPAC information for record is returned in XML
+ if an OPAC record is present at the position given. If no
+ OPAC record is present, a NULL pointer is returned.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>txml</literal></term>
+ <listitem><para>The record is returned in TurboMARC if possible.
+ SRU and Z39.50 records with transfer syntax XML are
+ returned verbatim. MARC records are returned in
+ <link linkend="tools.turbomarc">
+ TurboMARC
+ </link>
+ (converted from ISO2709 to TurboMARC by YAZ).
+ Upon completion, the XML buffer is returned
+ (type <literal>const char *</literal>) and length is stored in
+ <literal>*len</literal>.
</para></listitem>
</varlistentry>
</variablelist>
</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/SOLR Protocol behavior</title>
<para>
- The ZOOM driver for SRW treats records returned by a SRW server
+ The ZOOM driver for SRU/SOLR treats records returned by a SRU/SOLR 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.facets"><title>Facets</title>
+ <para>
+ Facets operations is not part of the official ZOOM specification, but is an Index Data extension
+ for YAZ-based Z39.50 targets or <ulink url="&url.solr;">SOLR</ulink> targets.
+ In case the target can and is requested to return facets, using a result set the ZOOM client
+ can request one or all facet fields. Using a facet field the client can request the term count and
+ then interate over the terms.
+ </para>
+ <synopsis>
+ ZOOM_facet_field *ZOOM_resultset_facets(ZOOM_resultset r);
+ const char ** ZOOM_resultset_facets_names(ZOOM_resultset r);
+ ZOOM_facet_field ZOOM_resultset_get_facet_field(ZOOM_resultset r, const char *facet_name);
+ ZOOM_facet_field ZOOM_resultset_get_facet_field_by_index(ZOOM_resultset r, int pos);
+ size_t ZOOM_resultset_facets_size(ZOOM_resultset r);
+
+ const char *ZOOM_facet_field_name(ZOOM_facet_field facet_field);
+ size_t ZOOM_facet_field_term_count(ZOOM_facet_field facet_field);
+ const char *ZOOM_facet_field_get_term(ZOOM_facet_field facet_field, size_t idx, int *freq);
+ </synopsis>
+ <para>
+ References to temporary structures are returned by all functions. They are only valid as long the Result set is valid.
+ <function>ZOOM_resultset_get_facet_field</function> or
+ <function>ZOOM_resultset_get_facet_field_by_index</function>.
+ <function>ZOOM_resultset_facets</function>.
+ <function>ZOOM_resultset_facets_names</function>.
+ <function>ZOOM_facet_field_name</function>.
+ <function>ZOOM_facet_field_get_term</function>.
+ </para>
+ <para id="zoom.resultset.get_facet_field">
+ A single Facet field is returned by function
+ <function>ZOOM_resultset_get_facet_field</function> or <function>ZOOM_resultset_get_facet_field_by_index</function> that takes a
+ result set and facet name or positive index respectively. First facet has position zero.
+ If no facet could be obtained (invalid name or index out of bounds) <literal>NULL</literal> is returned.
+ </para>
+ <para id="zoom.resultset.facets">
+ An array of facets field can be returned by <function>ZOOM_resultset_facets</function>. The length of the array is
+ given by <function>ZOOM_resultset_facets_size</function>. The array is zero-based and last entry will be at
+ <function>ZOOM_resultset_facets_size(result_set)</function>-1.
+ </para>
+ <para id="zoom.resultset.facets_names">
+ It is possible to interate over facets by name, by calling <function>ZOOM_resultset_facets_names</function>.
+ This will return an const array of char * where each string can be used as parameter for
+ <function>ZOOM_resultset_get_facet_field</function>.
+ </para>
+ <para>
+ Function <function>ZOOM_facet_field_name</function> gets the request facet name from a returned facet field.
+ </para>
+ <para>
+ Function <function>ZOOM_facet_field_get_term</function> returns the idx'th term and term count for a facet field.
+ Idx must between 0 and <function>ZOOM_facet_field_term_count</function>-1, otherwise the returned reference will be
+ <literal>NULL</literal>. On a valid idx, the value of the freq reference will be the term count.
+ The *freq parameter must be valid pointer to integer.
+ </para>
+ </sect1>
<sect1 id="zoom.scan"><title>Scan</title>
<para>
This section describes an interface for Scan. Scan is not an
</para>
<para>
- The Scan interface is Z39.50 only. SRW version 1.0 does not
- support this.
+ The Scan interface is supported for both Z39.50, SRU (and SOLR?).
</para>
<synopsis>
ZOOM_scanset ZOOM_connection_scan(ZOOM_connection c,
const char *startpqf);
+ ZOOM_scanset ZOOM_connection_scan1(ZOOM_connection c,
+ ZOOM_query q);
+
size_t ZOOM_scanset_size(ZOOM_scanset scan);
- const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
- int *occ, size_t *len);
+ const char *ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
+ size_t *occ, size_t *len);
- const char * ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
- int *occ, size_t *len);
+ const char *ZOOM_scanset_display_term(ZOOM_scanset scan, size_t pos,
+ size_t *occ, size_t *len);
- void ZOOM_scanset_destroy (ZOOM_scanset scan);
+ void ZOOM_scanset_destroy(ZOOM_scanset scan);
const char *ZOOM_scanset_option_get(ZOOM_scanset scan,
- const char *key);
+ const char *key);
void ZOOM_scanset_option_set(ZOOM_scanset scan, const char *key,
const char *val);
@attr 1=4 @attr 6=2 "science o"
</literallayout>
</para>
+
+ <para>
+ The <function>ZOOM_connecton_scan1</function> is a newer and
+ more generic alternative to <function>ZOOM_connection_scan</function>
+ which allows to use both CQL and PQF for Scan.
+ </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>
<row><entry>
number</entry><entry>Number of Scan Terms requested in next scan.
After scan it holds the actual number of terms returned.
- </entry><entry>10</entry></row>
+ </entry><entry>20</entry></row>
<row><entry>
position</entry><entry>Preferred Position of term in response
in next scan; actual position after completion of scan.
scanStatus</entry><entry>An integer indicating the Scan Status
of last scan.
</entry><entry>0</entry></row>
+ <row><entry>
+ rpnCharset</entry><entry>Character set for RPN terms.
+ If this is set, ZOOM C will assume that the ZOOM application is
+ running UTF-8. Terms in RPN queries are then converted to the
+ rpnCharset. If this is unset, ZOOM C will not assume any encoding
+ of RPN terms and no conversion is performed.
+ </entry><entry>none</entry></row>
</tbody>
</tgroup>
</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>
<entry><literal>create</literal></entry>
</row>
<row>
+ <entry>waitAction</entry>
+ <entry>
+ Wait action for package. Possible values:
+ <literal>wait</literal>, <literal>waitIfPossible</literal>,
+ <literal>dontWait</literal> or <literal>dontReturnPackage</literal>.
+ </entry>
+ <entry><literal>waitIfPossible</literal></entry>
+ </row>
+ <row>
<entry>targetReference</entry>
<entry>
Target Reference. This is part of the response as returned
- by the server. Read it after a succesful operation.
+ by the server. Read it after a successful operation.
</entry>
<entry><literal>none</literal></entry>
</row>
</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>
<literal>recordDelete</literal>,
<literal>elementUpdate</literal>.
</entry>
- <entry><literal>specialUpdate</literal></entry>
+ <entry><literal>specialUpdate (recordInsert for updateVersion=1 which does not support specialUpdate)</literal></entry>
</row>
<row>
<entry>recordIdOpaque</entry>
<entry>none</entry>
</row>
<row>
+ <entry>recordOpaque</entry>
+ <entry>Specifies an opaque record which is
+ encoded as an ASN.1 ANY type with the OID as tiven by option
+ <literal>syntax</literal> (see below).
+ Option <literal>recordOpaque</literal> is an alternative
+ to record - and <literal>record</literal> option (above) is
+ ignored if recordOpaque is set. This option is only available in
+ YAZ 3.0.35 and later and is meant to facilitate Updates with
+ servers from OCLC.
+ </entry>
+ <entry>none</entry>
+ </row>
+ <row>
<entry>syntax</entry>
<entry>The record syntax (transfer syntax). Is a string that
is a known record syntax.
<entry>Database from connection object</entry>
<entry>Default</entry>
</row>
+ <row>
+ <entry>correlationInfo.note</entry>
+ <entry>Correlation Info Note (string)</entry>
+ <entry>none</entry>
+ </row>
+ <row>
+ <entry>correlationInfo.id</entry>
+ <entry>Correlation Info ID (integer)</entry>
+ <entry>none</entry>
+ </row>
+ <row>
+ <entry>elementSetName</entry>
+ <entry>Element Set for Record</entry>
+ <entry>none</entry>
+ </row>
+ <row>
+ <entry>updateVersion</entry>
+ <entry>Record Update version which holds one of the values
+ 1, 2 or 3. Each version has a distinct OID:
+ 1.2.840.10003.9.5
+ (<ulink url="&url.z39.50.extupdate1;">first version</ulink>) ,
+ 1.2.840.10003.9.5.1
+ (second version) and
+ 1.2.840.10003.9.5.1.1
+ (<ulink url="&url.z39.50.extupdate3;">third and
+ newest version</ulink>).
+ </entry>
+ <entry>3</entry>
+ </row>
</tbody>
</tgroup>
</table>
</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>
an associative array / hash.
</para>
<synopsis>
- ZOOM_options ZOOM_options_create (void);
+ ZOOM_options ZOOM_options_create(void);
- ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
+ ZOOM_options ZOOM_options_create_with_parent(ZOOM_options parent);
- void ZOOM_options_destroy (ZOOM_options opt);
+ void ZOOM_options_destroy(ZOOM_options opt);
</synopsis>
<synopsis>
- const char *ZOOM_options_get (ZOOM_options opt, const char *name);
+ const char *ZOOM_options_get(ZOOM_options opt, const char *name);
- void ZOOM_options_set (ZOOM_options opt, const char *name,
- const char *v);
+ void ZOOM_options_set(ZOOM_options opt, const char *name,
+ const char *v);
</synopsis>
<synopsis>
typedef const char *(*ZOOM_options_callback)
- (void *handle, const char *name);
+ (void *handle, const char *name);
ZOOM_options_callback
- ZOOM_options_set_callback (ZOOM_options opt,
- ZOOM_options_callback c,
- void *handle);
+ ZOOM_options_set_callback(ZOOM_options opt,
+ ZOOM_options_callback c,
+ void *handle);
</synopsis>
</sect1>
<sect1 id="zoom.events"><title>Events</title>
with events.
</para>
<synopsis>
- int ZOOM_event (int no, ZOOM_connection *cs);
+ int ZOOM_event(int no, ZOOM_connection *cs);
</synopsis>
<para>
The <function>ZOOM_event</function> executes pending events for
(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>
projects / yaz-moved-to-github.git / blobdiff