-<!-- $Id: zoom.xml,v 1.8 2001-11-13 23:00:42 adam Exp $ -->
+<!-- $Id: zoom.xml,v 1.11 2001-11-16 09:52:39 adam Exp $ -->
<chapter id="zoom"><title>Building clients with ZOOM</title>
<para>
</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
+ 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 futher, 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 website</ulink> for
more information.
</para>
<function>Z3950_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 Z3950_connection_option_set (Z3950_connection c,
+ const char *key,
+ const char *val);
+
+ const char *Z3950_connection_option_get (Z3950_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 (new) value of the option.
+ The <function>Z3950_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>Z3950_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">
pass</entry><entry>Authentication password
</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>
<row><entry>
</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.
- </para>
<synopsis>
int Z3950_connection_error (Z3950_connection c, const char **cp,
const char **addinfo);
creating query objects is not necessary.
</para>
<synopsis>
- const char *Z3950_resultset_option (Z3950_resultset r,
- const char *key,
- const char *val);
+ void Z3950_resultset_option_set (Z3950_resultset r,
+ const char *key,
+ const char *val);
- int Z3950_resultset_size (Z3950_resultset r);
+ const char *Z3950_resultset_option_get (Z3950_resultset r,
+ const char *key);
- void *Z3950_resultset_get (Z3950_resultset s, size_t pos,
- const char *type, size_t *len);
+ size_t Z3950_resultset_size (Z3950_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>Z3950_resultset_options_set</function> and
+ <function>Z3950_resultset_get</function> sets and gets an option
+ for a result set similar to <function>Z3950_connection_option_get</function>
+ and <function>Z3950_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.
- </para>
<table frame="top"><title>ZOOM Result set Options</title>
<tgroup cols="3">
<colspec colwidth="4*" colname="name"></colspec>
void *Z3950_record_get (Z3950_record rec, const char *type,
size_t *len);
+ Z3950_record Z3950_record_dup (Z3950_record rec);
+
void Z3950_record_destroy (Z3950_record rec);
</synopsis>
<para>
- Records are created by functions
+ References to temporary records are returned by functions
<function>Z3950_resultset_records</function> or
- <function>Z3950_resultset_record</function>
- and destroyed by <function>Z3950_record_destroy</function>.
+ <function>Z3950_resultset_record</function>.
+ </para>
+ <para>
+ If a persistent reference to a record is desired
+ <function>Z3950_record_dup</function> should be used.
+ It returns a record reference that at any
+ later stage should be destroyed by
+ <function>Z3950_record_destroy</function>.
</para>
<para>
- A single record is created and returned by function
+ A single record is returned by function
<function>Z3950_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.
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>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 <literal>char *</literal>.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>render</literal></term>
<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
+ <literal>Z_External *</literal> which is just the type for
the member <literal>retrievalRecord</literal> in
type <literal>NamePlusRecord</literal>.
</para></listitem>
<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.
+ 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>Z3950_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>
</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);
projects / yaz-moved-to-github.git / blobdiff