[yaz-moved-to-github.git] / doc / zoom.xml

<!-- $Id: zoom.xml,v 1.10 2001-11-15 21:58:50 adam Exp $ -->
 <chapter id="zoom"><title>Building clients with 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
   explains the peculiar name of the model). The goal of &zoom; is to
   provide a common Z39.50 client API not bound to a particular
   programming language or toolkit.
  </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
   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
   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
   <ulink url="http://zoom.z3950.org/">ZOOM website</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
   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
   <literal>_destroy</literal> variant.
   All objects are in fact pointers to internal stuff, but you don't see
   that because of typedefs. All destroy methods should gracefully ignore a
   <literal>NULL</literal> pointer.
  </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.
  </para>
  <sect1 id="zoom.connections"><title>Connections</title>
   
   <para>The Connection object is a session with a target.
   </para>
   <synopsis>
   #include &lt;yaz/zoom.h>
    
   Z3950_connection Z3950_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,
                                 int portnum);
   void Z3950_connection_destroy (Z3950_connection c);
   </synopsis>
   <para>
    Connection objects are created with either function
    <function>Z3950_connection_new</function> or 
    <function>Z3950_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
    <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>
    Connection objects should be destroyed using the function
    <function>Z3950_connection_destroy</function>.
   </para>
   <synopsis>
    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);

    const char *Z3950_connection_host (Z3950_connection c);
   </synopsis>
   <para>
    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">
     <colspec colwidth="4*" colname="name"></colspec>
     <colspec colwidth="7*" colname="description"></colspec>
     <colspec colwidth="3*" colname="default"></colspec>
     <thead>
      <row>
       <entry>Option</entry>
       <entry>Description</entry>
       <entry>Default</entry>
      </row>
     </thead>
     <tbody>
      <row><entry>
        implementationName</entry><entry>Name of Your client
       </entry><entry>none</entry></row>
      <row><entry>
        user</entry><entry>Authentication user name
       </entry><entry>none</entry></row>
      <row><entry>
        group</entry><entry>Authentication group name
       </entry><entry>none</entry></row>
      <row><entry>
        pass</entry><entry>Authentication password
      </entry><entry>none</entry></row>
      <row><entry>
        proxy</entry><entry>Proxy host
       </entry><entry>none</entry></row>
      <row><entry>
        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>.
       </entry><entry>0</entry></row>
      <row><entry>
        maximumRecordSize</entry><entry> Maximum size of single record.
       </entry><entry>1 MB</entry></row>
      <row><entry>
        preferredMessageSize</entry><entry> Maximum size of multiple records.
       </entry><entry>1 MB</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.
   </para>
   <synopsis>
     int Z3950_connection_error (Z3950_connection c, const char **cp,
                                 const char **addinfo);
   </synopsis>
   <para>
    Use <function>Z3950_connection_error</function> to check 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>.
   </para>
   <sect2><title>Protocol behavior</title>
    <para>
     The calls <function>Z3950_connection_new</function> and
     <function>Z3950_connection_connect</function> establises 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>
    <para>
     If <literal>proxy</literal> is set then the client will establish
     a TCP/IP connection with the peer as specified by the
     <literal>proxy</literal> host and the hostname as part of the
     connect calls will be set as part of the Initialize Request.
     The proxy server will then "forward" the PDU's transparently
     to the target behind the proxy.
    </para>
    <para>
     For the authentication parameters, if option <literal>user</literal>
     is set and both options <literal>group</literal> and
     <literal>pass</literal> are unset, then Open style
     authentication is used (Version 2/3) in which case the username
     is usually followed by a slash, then by a password.
     If either <literal>group</literal>
     or <literal>pass</literal> is set then idPass authentication
     (Version 3 only) is used. If none of the options are set, no
     authentication parameters are set as part of the Initialize Request
     (obviously).
    </para>
    <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
     it doesn't make sense to check for errors after
     <literal>Z3950_connection_new</literal> is called since that
     operation "connecting - and init" is still incomplete and the
     API cannot tell the outcome (yet).
    </para>
    </sect2>
  </sect1>
  <sect1 id="zoom.query"><title>Queries</title>
   <para>
    Query objects represents queries.
   </para>
   <synopsis>
     Z3950_query Z3950_query_create(void);

     void Z3950_query_destroy(Z3950_query q);

     int Z3950_query_prefix(Z3950_query q, const char *str);

     int Z3950_query_sortby(Z3950_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>.
    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
    <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 
    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>
    <para>
     The query object is just an interface for the member Query
     in the SearchRequest. The sortby-function is an interface to the
     sortSequence member of the SortRequest.
    </para>
   </sect2>
  </sect1>
  <sect1 id="zoom.resultsets"><title>Result sets</title>
   <para>
    The result set object is a container for records returned from
    a target.
   </para>
   <synopsis>
     Z3950_resultset Z3950_connection_search(Z3950_connection,
                                             Z3950_query q);

     Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
                                                 const char *q);

     void Z3950_resultset_destroy(Z3950_resultset r);
   </synopsis>
   <para>
    Function <function>Z3950_connection_search</function> creates
     a result set given a connection and query.
    Destroy a result set by calling
    <function>Z3950_resultset_destroy</function>.
    Simple clients may using PQF only may use function
    <function>Z3950_connection_search_pqf</function> in which case
    creating query objects is not necessary.
   </para>
   <synopsis>
     void Z3950_resultset_option_set (Z3950_resultset r,
                                      const char *key,
                                      const char *val);

     const char *Z3950_resultset_option_get (Z3950_resultset r,
                                             const char *key);

     size_t Z3950_resultset_size (Z3950_resultset r);
   </synopsis>
   <para>
    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>
   <table frame="top"><title>ZOOM Result 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>
        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.
       </entry><entry>0</entry></row>
      <row><entry>
        count</entry><entry>Number of records to be retrieved.
       </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.
       </entry><entry>none</entry></row>
      <row><entry>
        preferredRecordSyntax</entry><entry>Preferred Syntax, such as
        <literal>USMARC</literal>, <literal>SUTRS</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
        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.
       </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>
     </tbody>
    </tgroup>
   </table>
   <sect2>
    <title>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 -
     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
     is set. Following Search - and a Possible sort, Retrieval takes
     place - as one or more Present Requests - Present Response 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
     <literal>smallSetUpperBound</literal>,
     <literal>mediumSetPresentNumber</literal> and
     <literal>largeSetLowerBound</literal> are set. The low level mode
     thus allows you to precisely set how records are returned as part
     of a search response as offered by the Z39.50 protocol.
     Since the client may be retrieving records as part of the
     search response, this mode doesn't work well if sorting is used.
     </para>
    <para>
     The high-level mode allows you to fetch a range of records from
     the result set with a given start offset. When you use this mode
     the client will automatically use piggyback if that is possible
     with the target and perform one or more present requests as needed.
     Even if the target returns fewer records as part of a present response
     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
     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
     a sorting criteria is set, or if <literal>piggyback</literal>
     is 0, then the client will not perform piggyback but send Present
     Requests instead.
    </para>
    <para>
     If either of the options <literal>mediumSetElementSetName</literal> and
     <literal>smallSetElementSetName</literal> are unset, the value
     of option <literal>elementSetName</literal> is used for piggyback
     searches. This means that for the high-level mode you only have
     to specify one elementSetName option rather than three.
     </para>
   </sect2>
  </sect1>
  <sect1 id="zoom.records"><title>Records</title>
   <para>
    A record object is a retrival 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 *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>
    References to temporary records are returned by functions 
    <function>Z3950_resultset_records</function> or
    <function>Z3950_resultset_record</function>.
    </para>
   <para>
    If a persistent pointer 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 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.
   </para>
   <para>
    Function <function>Z3950_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
    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 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
    <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>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 null-terminated string. Return type <literal>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
        <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> which is just the type for
        the member <literal>retrievalRecord</literal> in
        type <literal>NamePlusRecord</literal>.
       </para></listitem>
      </varlistentry>
    </variablelist>
   </para>
   <sect2><title>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.
    </para>
   </sect2>
  </sect1>
  <sect1 id="zoom.options"><title>Options</title>
   <para>
    Most &zoom; objects provide a way to specify options to default behavior.
    From an implementation point of view a set of options is just like
    an associate array / hash array, etc.
   </para>
   <synopsis>
     Z3950_options Z3950_options_create (void);

     Z3950_options Z3950_options_create_with_parent (Z3950_options parent);

     void Z3950_options_destroy (Z3950_options opt);
   </synopsis>
   <synopsis>
     const char *Z3950_options_get (Z3950_options opt, const char *name);

     void Z3950_options_set (Z3950_options opt, const char *name,
                             const char *v);
   </synopsis>
   <synopsis>
     typedef const char *(*Z3950_options_callback)
                                     (void *handle, const char *name);

     Z3950_options_callback
             Z3950_options_set_callback (Z3950_options opt,
                                         Z3950_options_callback c,
                                         void *handle);
   </synopsis>
  </sect1>
  <sect1 id="zoom.events"><title>Events</title>
   <para>
    If you're developing non-blocking applications, you have to deal 
    with events.
   </para>
   <synopsis>
    int Z3950_event (int no, Z3950_connection *cs);
   </synopsis>
   <para>
    The <function>Z3950_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
    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
    returned.
    To ensure that all outstanding requests are performed call this function
    repeatedly until zero is returned.
   </para>
  </sect1>
 </chapter>
 
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-omittag:t
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
 sgml-indent-step:1
 sgml-indent-data:t
 sgml-parent-document: "yaz.xml"
 sgml-local-catalogs: nil
 sgml-namecase-general:t
 End:
 -->