-<!-- $Id: zoom.xml,v 1.7 2001-11-11 22:25:25 adam Exp $ -->
- <chapter id="zoom"><title>Building clients with ZOOM</title>
-
+<!-- $Id: zoom.xml,v 1.24 2003-05-12 13:34:00 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 another scheme 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
+ and more apparent over time. So when the first &zoom; specification
became available,
an implementation for &yaz; was quickly developed. For the first time, it is
now as easy (or easier!) to develop clients than servers with &yaz;. This
- chapter describes the ZOOM C binding. Before going futher, please
+ chapter describes the &zoom; C binding. Before going further, please
reconsider whether C is the right programming language for the job.
There are other language bindings available for &yaz;, and still
more
- are in active development. See the ZOOM website at
- <ulink url="http://zoom.z3950.org/">zoom.z3950.org</ulink> for
+ are in active development. See the
+ <ulink url="http://zoom.z3950.org/">ZOOM web-site</ulink> for
more information.
</para>
-
+
<para>
In order to fully understand this chapter you should read and
try the example programs <literal>zoomtst1.c</literal>,
<literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
directory.
</para>
-
+
<para>
- The C language misses many features found in object oriented languages
+ The C language misses features found in object oriented languages
such as C++, Java, etc. For example, you'll have to manually,
destroy all objects you create, even though you may think of them as
temporary. Most objects has a <literal>_create</literal> - and a
</para>
<para>
In each of the sections below you'll find a sub section called
- protocol behavior, that descries how the API maps to the Z39.50
+ protocol behavior, that describes how the API maps to the Z39.50
protocol.
</para>
<sect1 id="zoom.connections"><title>Connections</title>
<para>The Connection object is a session with a target.
</para>
<synopsis>
- #include <yaz/zoom.h>
+ #include <yaz/zoom.h>
- Z3950_connection Z3950_connection_new (const char *host, int portnum);
+ ZOOM_connection ZOOM_connection_new (const char *host, int portnum);
- Z3950_connection Z3950_connection_create (Z3950_options options);
-
- void Z3950_connection_connect(Z3950_connection c, const char *host,
+ ZOOM_connection ZOOM_connection_create (ZOOM_options options);
+
+ void ZOOM_connection_connect(ZOOM_connection c, const char *host,
int portnum);
- void Z3950_connection_destroy (Z3950_connection c);
+ void ZOOM_connection_destroy (ZOOM_connection c);
</synopsis>
<para>
Connection objects are created with either function
- <function>Z3950_connection_new</function> or
- <function>Z3950_connection_create</function>.
+ <function>ZOOM_connection_new</function> or
+ <function>ZOOM_connection_create</function>.
The former creates and automatically attempts to establish a network
connection with the target. The latter doesn't establish
a connection immediately, thus allowing you to specify options
before establishing network connection using the function
- <function>Z3950_connection_connect</function>.
- If the portnumber, <literal>portnum</literal>, is zero, the
+ <function>ZOOM_connection_connect</function>.
+ If the port number, <literal>portnum</literal>, is zero, the
<literal>host</literal> is consulted for a port specification.
If no port is given, 210 is used. A colon denotes the beginning of
a port number in the host string. If the host string includes a
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>Z3950_connection_destroy</function>.
+ <function>ZOOM_connection_destroy</function>.
</para>
<synopsis>
- const char *Z3950_connection_option (Z3950_connection c,
- const char *key,
- const char *val);
- const char *Z3950_connection_host (Z3950_connection c);
+ void ZOOM_connection_option_set (ZOOM_connection c,
+ const char *key,
+ const char *val);
+
+ const char *ZOOM_connection_option_get (ZOOM_connection c,
+ const char *key);
</synopsis>
<para>
- The <function>Z3950_connection_option</function> allows you to
- inspect or set an option given by <parameter>key</parameter>
- for the connection.
- If <parameter>val</parameter> is non-<literal>NULL</literal> that
- holds the new value for option.
- Otherwise, if <parameter>val</parameter> is
- <literal>NULL</literal>,
- the option is unchanged.
- The function returns the previous value of the option.
+ The <function>ZOOM_connection_option_set</function> allows you to
+ set an option given by <parameter>key</parameter> to the value
+ <parameter>value</parameter> for the connection.
+ Function <function>ZOOM_connection_option_get</function> returns
+ the value for an option given by <parameter>key</parameter>.
</para>
<table frame="top"><title>ZOOM Connection Options</title>
<tgroup cols="3">
</entry><entry>none</entry></row>
<row><entry>
pass</entry><entry>Authentication password
- </entry><entry>none</entry></row>
+ </entry><entry>none</entry></row>
+ <row><entry>
+ host</entry><entry>Target host. This setting is "read-only".
+ It's automatically set internally when connecting to a target.
+ </entry><entry>none</entry></row>
<row><entry>
proxy</entry><entry>Proxy host
</entry><entry>none</entry></row>
async</entry><entry>If true (1) the connection operates in
asynchronous operation which means that all calls are non-blocking
except
- <link linkend="zoom.events"><function>Z3950_event</function></link>.
+ <link linkend="zoom.events"><function>ZOOM_event</function></link>.
</entry><entry>0</entry></row>
<row><entry>
maximumRecordSize</entry><entry> Maximum size of single record.
<row><entry>
preferredMessageSize</entry><entry> Maximum size of multiple records.
</entry><entry>1 MB</entry></row>
+ <row><entry>
+ lang</entry><entry> Language for negotiation.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ charset</entry><entry> Character set for negotiation.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ targetImplementationId</entry><entry> Implementation ID of target.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ targetImplementationName</entry><entry> Implementation Name of target.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ targetImplementationVersion</entry><entry> Implementation Version
+ of target.
+ </entry><entry>none</entry></row>
+ <row><entry>
+ 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>
</tbody>
</tgroup>
</table>
<para>
- Function <function>Z3950_connection_host</function> returns
- the host for the connection as specified in a call to
- <function>Z3950_connection_new</function> or
- <function>Z3950_connection_connect</function>.
- This function returns <literal>NULL</literal> if host isn't
- set for the connection.
+ 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">
+ Character Set and Language Negotiation</ulink> is in effect.
</para>
<synopsis>
- int Z3950_connection_error (Z3950_connection c, const char **cp,
- const char **addinfo);
+ 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>
- Use <function>Z3950_connection_error</function> to check for
+ Function <function>ZOOM_connection_error</function> checks for
errors for the last operation(s) performed. The function returns
zero if no errors occurred; non-zero otherwise indicating the error.
Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
holds messages for the error and additional-info if passed as
- non-<literal>NULL</literal>.
+ non-<literal>NULL</literal>. Function
+ <function>ZOOM_connection_error_x</function> is an extended version
+ 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>Z3950_connection_new</function> and
- <function>Z3950_connection_connect</function> establises a TCP/IP
+ The calls <function>ZOOM_connection_new</function> and
+ <function>ZOOM_connection_connect</function> establishes a TCP/IP
connection and sends an Initialize Request to the target if
possible. In addition, the calls waits for an Initialize Response
from the target and the result is inspected (OK or rejected).
<para>
When option <literal>async</literal> is 1, it really means that
all network operations are postponed (and queued) until the
- function <literal>Z3950_event</literal> is invoked. When doing so
+ function <literal>ZOOM_event</literal> is invoked. When doing so
it doesn't make sense to check for errors after
- <literal>Z3950_connection_new</literal> is called since that
+ <literal>ZOOM_connection_new</literal> is called since that
operation "connecting - and init" is still incomplete and the
API cannot tell the outcome (yet).
</para>
</sect2>
+ <sect2><title>SRW Protocol behavior</title>
+ <para>
+ The SRW protocol doesn't feature an Init Request, so
+ the connection phase merely establishes a TCP/IP connection
+ with the SOAP service.
+ </para>
+ <para>None of the ZOOM connection options
+ 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.
+ The <literal>charset</literal>, and <literal>lang</literal>
+ might also affect HTTP headers in future releases.
+ </para>
+ </sect2>
</sect1>
<sect1 id="zoom.query"><title>Queries</title>
<para>
Query objects represents queries.
</para>
<synopsis>
- Z3950_query Z3950_query_create(void);
+ ZOOM_query ZOOM_query_create(void);
+
+ void ZOOM_query_destroy(ZOOM_query q);
- void Z3950_query_destroy(Z3950_query q);
+ int ZOOM_query_prefix(ZOOM_query q, const char *str);
- int Z3950_query_prefix(Z3950_query q, const char *str);
+ int ZOOM_query_cql(ZOOM_query s, const char *str);
- int Z3950_query_sortby(Z3950_query q, const char *criteria);
+ int ZOOM_query_sortby(ZOOM_query q, const char *criteria);
</synopsis>
<para>
- Create query objects using <function>Z3950_query_create</function>
- and destroy them by calling <function>Z3950_query_destroy</function>.
+ Create query objects using <function>ZOOM_query_create</function>
+ 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>Z3950_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>Z3950_query_sortby</function> specifies a
+ <function>ZOOM_query_sortby</function> specifies a
sort criteria using the same string notation for sort as offered by
the <link linkend="sortspec">YAZ client</link>.
</para>
a target.
</para>
<synopsis>
- Z3950_resultset Z3950_connection_search(Z3950_connection,
- Z3950_query q);
+ ZOOM_resultset ZOOM_connection_search(ZOOM_connection,
+ ZOOM_query q);
- Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
- const char *q);
+ ZOOM_resultset ZOOM_connection_search_pqf(ZOOM_connection c,
+ const char *q);
- void Z3950_resultset_destroy(Z3950_resultset r);
+ void ZOOM_resultset_destroy(ZOOM_resultset r);
</synopsis>
<para>
- Function <function>Z3950_connection_search</function> creates
+ Function <function>ZOOM_connection_search</function> creates
a result set given a connection and query.
Destroy a result set by calling
- <function>Z3950_resultset_destroy</function>.
+ <function>ZOOM_resultset_destroy</function>.
Simple clients may using PQF only may use function
- <function>Z3950_connection_search_pqf</function> in which case
+ <function>ZOOM_connection_search_pqf</function> in which case
creating query objects is not necessary.
</para>
<synopsis>
- const char *Z3950_resultset_option (Z3950_resultset r,
- const char *key,
- const char *val);
+ void ZOOM_resultset_option_set (ZOOM_resultset r,
+ const char *key,
+ const char *val);
- int Z3950_resultset_size (Z3950_resultset r);
+ const char *ZOOM_resultset_option_get (ZOOM_resultset r,
+ const char *key);
- void *Z3950_resultset_get (Z3950_resultset s, size_t pos,
- const char *type, size_t *len);
+ size_t ZOOM_resultset_size (ZOOM_resultset r);
</synopsis>
<para>
- Function <function>Z3950_resultset_options</function> sets or
- modifies an option for a result set similar to
- <function>Z3950_connection_option</function>.
+ Functions <function>ZOOM_resultset_options_set</function> and
+ <function>ZOOM_resultset_get</function> sets and gets an option
+ for a result set similar to <function>ZOOM_connection_option_get</function>
+ and <function>ZOOM_connection_option_set</function>.
</para>
<para>
The number of hits also called result-count is returned by
- function <function>Z3950_resultset_size</function>.
- </para>
- <para>
- Function <function>Z3950_resultset_get</function> is similar to
- <link linkend="zoom.record.get">
- <function>Z3950_record_get</function></link> but
- instead of operating on a record object, it operates on a record on
- a given offset within a result set.
+ function <function>ZOOM_resultset_size</function>.
</para>
<table frame="top"><title>ZOOM Result set Options</title>
<tgroup cols="3">
<literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
</entry><entry>none</entry></row>
<row><entry>
+ schema</entry><entry>Schema for retrieval, such as
+ <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 greator than this
+ 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 greator than small set upper bound.
+ is greater than small set upper bound.
</entry><entry>0</entry></row>
<row><entry>
smallSetElementSetName</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>
+ 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.
+ </entry><entry>default</entry></row>
</tbody>
</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
- critieria was specified as part of the query, a sortRequest -
+ criteria was specified as part of the query, a SortRequest -
SortResponse handshake takes place. Note that it is necessary to
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 critieria
+ 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
transferred.
because of a record size limit, etc. the client will repeat sending
present requests. As an example, if option <literal>start</literal>
is 0 (default) and <literal>count</literal> is 4, and
- <literal>piggyback</literal> is 1 (default) and no sorting critieria
+ <literal>piggyback</literal> is 1 (default) and no sorting criteria
is specified, then the client will attempt to retrieve the 4
records as part the search response (using piggyback). On the other
hand, if either <literal>start</literal> is positive or if
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>
- A record object is a retrival record on the client side -
+ A record object is a retrieval record on the client side -
created from result sets.
</para>
<synopsis>
- void Z3950_resultset_records (Z3950_resultset r,
- Z3950_record *recs,
- size_t start, size_t count);
- Z3950_record Z3950_resultset_record (Z3950_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);
- void *Z3950_record_get (Z3950_record rec, const char *type,
- size_t *len);
+ const char *ZOOM_record_get (ZOOM_record rec, const char *type,
+ size_t *len);
- void Z3950_record_destroy (Z3950_record rec);
+ ZOOM_record ZOOM_record_clone (ZOOM_record rec);
+
+ void ZOOM_record_destroy (ZOOM_record rec);
</synopsis>
<para>
- Records are created by functions
- <function>Z3950_resultset_records</function> or
- <function>Z3950_resultset_record</function>
- and destroyed by <function>Z3950_record_destroy</function>.
+ References to temporary records are returned by functions
+ <function>ZOOM_resultset_records</function> or
+ <function>ZOOM_resultset_record</function>.
+ </para>
+ <para>
+ If a persistent reference to a record is desired
+ <function>ZOOM_record_clone</function> should be used.
+ It returns a record reference that should be destroyed
+ by a call to <function>ZOOM_record_destroy</function>.
</para>
<para>
- A single record is created and returned by function
- <function>Z3950_resultset_record</function> that takes a
+ A single record is returned by function
+ <function>ZOOM_resultset_record</function> that takes a
position as argument. First record has position zero.
If no record could be obtained <literal>NULL</literal> is returned.
</para>
<para>
- Function <function>Z3950_resultset_records</function> retrieves
+ 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
be returned. Upon completion array
<literal>recs[0], ..recs[count-1]</literal>
holds record objects for the records. The array of records
- <literal>recs</literal> should be allocate prior to calling
- <function>Z3950_resultset_records</function>. Note that for those
+ <literal>recs</literal> should be allocated prior the call
+ <function>ZOOM_resultset_records</function>. Note that for those
records that couldn't be retrieved from the target
<literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
</para>
<para id="zoom.record.get">
In order to extract information about a single record,
- <function>Z3950_record_get</function> is provided. The
+ <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 <function>type</function>
- given. In addition for certain types, the length
+ nature (type) of the pointer depends on the parameter,
+ <function>type</function>.
+ In addition, for certain types, the length
<literal>len</literal> passed will be set to the size in bytes of
the returned information.
<variablelist>
<varlistentry><term><literal>database</literal></term>
- <listitem><para>The database that holds the record is returned
- as a C string. Return type <literal>char *</literal>.
+ <listitem><para>Database of record is returned
+ as a C null-terminated string. Return type
+ <literal>const char *</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>syntax</literal></term>
<listitem><para>The transfer syntax (OID) of the record is returned
- as a C string. Return type <literal>char *</literal>.
+ 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
- (type <literal>char *</literal>) and length is stored in
+ (type <literal>const char *</literal>) and length is stored in
<literal>*len</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>raw</literal></term>
<listitem><para>The record is returned in the internal
- YAZ specific format. The raw data is returned as type
- <literal>Z_External *</literal> is just the type for
+ YAZ specific format. For GRS-1, Explain, and others, the
+ raw data is returned as type
+ <literal>Z_External *</literal> which is just the type for
the member <literal>retrievalRecord</literal> in
type <literal>NamePlusRecord</literal>.
+ For SUTRS and octet aligned record (including all MARCs) the
+ octet buffer is returned and the length of the buffer.
</para></listitem>
</varlistentry>
</variablelist>
</para>
- <sect2><title>Protocol behavior</title>
+ <sect2><title>Z39.50 Protocol behavior</title>
<para>
- The functions <function>Z3950_resultset_record</function> and
- <function>Z3950_resultset_records</function> inspects the client-side
- record cache. If the records(s) were not found, i.e. not yet retrieved
- from, they are fetched using Present Requests.
+ The functions <function>ZOOM_resultset_record</function> and
+ <function>ZOOM_resultset_records</function> inspects the client-side
+ record cache. Records not found in cache are fetched using
+ Present.
+ The functions may block (and perform network I/O) - even though option
+ <literal>async</literal> is 1, because they return records objects.
+ (and there's no way to return records objects without retrieving them!).
+ </para>
+ <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
+ 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>
+ This section describes an interface for Scan. Scan is not an
+ official part of the ZOOM model yet. The result of a scan operation
+ 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);
+
+ size_t ZOOM_scanset_size(ZOOM_scanset scan);
+
+ const char * ZOOM_scanset_term(ZOOM_scanset scan, size_t pos,
+ int *occ, size_t *len);
+
+
+ void ZOOM_scanset_destroy (ZOOM_scanset scan);
+
+ const char *ZOOM_scanset_option_get (ZOOM_scanset scan,
+ const char *key);
+
+ void ZOOM_scanset_option_set (ZOOM_scanset scan, const char *key,
+ const char *val);
+ </synopsis>
+ <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.
+ 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.
+ 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.
+ A scan set may be freed by a call to function
+ <function>ZOOM_scanset_destroy</function>.
+ Functions <function>ZOOM_scanset_option_get</function> and
+ <function>ZOOM_scanset_option_set</function> retrieves and sets
+ an option respectively.
+ </para>
+
+ <table frame="top"><title>ZOOM Scan Set Options</title>
+ <tgroup cols="3">
+ <colspec colwidth="4*" colname="name"></colspec>
+ <colspec colwidth="7*" colname="description"></colspec>
+ <colspec colwidth="2*" colname="default"></colspec>
+ <thead>
+ <row>
+ <entry>Option</entry>
+ <entry>Description</entry>
+ <entry>Default</entry>
+ </row>
+ </thead>
+ <tbody>
+ <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>
+ <row><entry>
+ position</entry><entry>Preferred Position of term in response
+ in next scan; actual position after completion of scan.
+ </entry><entry>1</entry></row>
+ <row><entry>
+ stepSize</entry><entry>Step Size
+ </entry><entry>0</entry></row>
+ <row><entry>
+ scanStatus</entry><entry>An integer indicating the Scan Status
+ of last scan.
+ </entry><entry>0</entry></row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </sect1>
<sect1 id="zoom.options"><title>Options</title>
<para>
- Most &zoom; objects provide a way to specify options to default behavior.
+ Most &zoom; objects provide a way to specify options to change behavior.
From an implementation point of view a set of options is just like
- an associate array / hash array, etc.
+ an associative array / hash array, etc.
</para>
<synopsis>
- Z3950_options Z3950_options_create (void);
+ ZOOM_options ZOOM_options_create (void);
- Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
+ ZOOM_options ZOOM_options_create_with_parent (ZOOM_options parent);
- void Z3950_options_destroy (Z3950_options opt);
+ void ZOOM_options_destroy (ZOOM_options opt);
</synopsis>
<synopsis>
- const char *Z3950_options_get (Z3950_options opt, const char *name);
+ const char *ZOOM_options_get (ZOOM_options opt, const char *name);
- void Z3950_options_set (Z3950_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 *(*Z3950_options_callback)
+ typedef const char *(*ZOOM_options_callback)
(void *handle, const char *name);
- Z3950_options_callback
- Z3950_options_set_callback (Z3950_options opt,
- Z3950_options_callback c,
- void *handle);
+ ZOOM_options_callback
+ 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 Z3950_event (int no, Z3950_connection *cs);
+ int ZOOM_event (int no, ZOOM_connection *cs);
</synopsis>
<para>
- The <function>Z3950_event</function> executes pending events for
+ The <function>ZOOM_event</function> executes pending events for
a number of connections. Supply the number of connections in
<literal>no</literal> and an array of connections in
<literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
A pending event could be a sending a search, receiving a response,
etc.
- When an event has a occured for one of the connections, this function
+ When an event has occurred for one of the connections, this function
returns a positive integer <literal>n</literal> denoting that an event
occurred for connection <literal>cs[n-1]</literal>.
When no events are pending for the connections, a value of zero is
projects / yaz-moved-to-github.git / blobdiff