doc/zoom.xml

   1 <!-- $Id: zoom.xml,v 1.6 2001-11-06 17:05:19 adam Exp $ -->
   2  <chapter id="zoom"><title>Building clients with ZOOM</title>
   3
   4   <para>
   5     &zoom; is an acronym for 'Z39.50 Object-Orientation Model' and is
   6    an initiative started by Mike Taylor (Mike is from the UK, which
   7    explains the peculiar name of the model). The goal of &zoom; is to
   8    provide a common Z39.50 client API not bound to a particular
   9    programming language or toolkit.
  10   </para>
  11   <para>
  12    The lack of a simple Z39.50 client API for &yaz; has become more
  13    and more apparent over time. So when the first ZOOM specification
  14    became available,
  15    an implementation for &yaz; was quickly developed. For the first time, it is
  16    now as easy (or easier!) to develop clients than servers with &yaz;. This
  17    chapter describes the ZOOM C binding. Before going futher, please
  18    reconsider whether C is the right programming language for the job.
  19    There are other language bindings available for &yaz;, and still
  20    more
  21    are in active development. See the ZOOM website at
  22    <ulink url="http://zoom.z3950.org/">zoom.z3950.org</ulink> for
  23    more information.
  24   </para>
  25
  26   <para>
  27    In order to fully understand this chapter you should read and
  28    try the example programs <literal>zoomtst1.c</literal>,
  29    <literal>zoomtst2.c</literal>, .. in the <literal>zoom</literal>
  30    directory.
  31   </para>
  32
  33   <para>
  34    The C language misses many features found in object oriented languages
  35    such as C++, Java, etc. For example, you'll have to manually,
  36    destroy all objects you create, even though you may think of them as
  37    temporary. Most objects has a <literal>_create</literal> - and a
  38    <literal>_destroy</literal> variant.
  39    All objects are in fact pointers to internal stuff, but you don't see
  40    that because of typedefs. All destroy methods should gracefully ignore a
  41    <literal>NULL</literal> pointer.
  42   </para>
  43   <sect1 id="zoom.connections"><title>Connections</title>
  44
  45    <para>The Connection object is a session with a target.
  46    </para>
  47    <synopsis>
  48    #include &lt;yaz/zoom.h>
  49
  50    Z3950_connection Z3950_connection_new (const char *host, int portnum);
  51
  52    Z3950_connection Z3950_connection_create (Z3950_options options);
  53
  54    void Z3950_connection_connect(Z3950_connection c, const char *host,
  55                                  int portnum);
  56    void Z3950_connection_destroy (Z3950_connection c);
  57    </synopsis>
  58    <para>
  59     Connection objects are created with either function
  60     <function>Z3950_connection_new</function> or
  61     <function>Z3950_connection_create</function>.
  62     The former creates and automatically attempts to establish a network
  63     connection with the target. The latter doesn't establish
  64     a connection immediately, thus allowing you to specify options
  65     before establishing network connection using the function
  66     <function>Z3950_connection_connect</function>.
  67     If the portnumber, <literal>portnum</literal>, is zero, the
  68     <literal>host</literal> is consulted for a port specification.
  69     If no port is given, 210 is used. A colon denotes the beginning of
  70     a port number in the host string. If the host string includes a
  71     slash, the following part specifies a database for the connection.
  72    </para>
  73    <para>
  74     Connection objects should be destroyed using the function
  75     <function>Z3950_connection_destroy</function>.
  76    </para>
  77    <synopsis>
  78     const char *Z3950_connection_option (Z3950_connection c,
  79                                          const char *key,
  80                                          const char *val);
  81     const char *Z3950_connection_host (Z3950_connection c);
  82    </synopsis>
  83    <para>
  84     The <function>Z3950_connection_option</function> allows you to
  85     inspect or set an option given by <parameter>key</parameter>
  86     for the connection.
  87     If <parameter>val</parameter> is non-<literal>NULL</literal> that
  88     holds the new value for option.
  89     Otherwise, if <parameter>val</parameter> is
  90     <literal>NULL</literal>,
  91     the option is unchanged.
  92     The function returns the previous value of the option.
  93    </para>
  94    <table frame="top"><title>ZOOM Connection Options</title>
  95     <tgroup cols="3">
  96      <colspec colwidth="4*" colname="name"></colspec>
  97      <colspec colwidth="7*" colname="description"></colspec>
  98      <colspec colwidth="3*" colname="default"></colspec>
  99      <thead>
 100       <row>
 101        <entry>Option</entry>
 102        <entry>Description</entry>
 103        <entry>Default</entry>
 104       </row>
 105      </thead>
 106      <tbody>
 107       <row><entry>
 108         implementationName</entry><entry>Name of Your client
 109        </entry><entry>none</entry></row>
 110       <row><entry>
 111         user</entry><entry>Authentication user name
 112        </entry><entry>none</entry></row>
 113       <row><entry>
 114         group</entry><entry>Authentication group name
 115        </entry><entry>none</entry></row>
 116       <row><entry>
 117         pass</entry><entry>Authentication password
 118       </entry><entry>none</entry></row>
 119       <row><entry>
 120         proxy</entry><entry>Proxy host
 121        </entry><entry>none</entry></row>
 122       <row><entry>
 123         async</entry><entry>If true (1) the connection operates in
 124         asynchronous operation which means that all calls are non-blocking
 125         except <function>Z3950_event</function>.
 126        </entry><entry>0</entry></row>
 127       <row><entry>
 128         maximumRecordSize</entry><entry> Maximum size of single record.
 129        </entry><entry>1 MB</entry></row>
 130       <row><entry>
 131         preferredMessageSize</entry><entry> Maximum size of multiple records.
 132        </entry><entry>1 MB</entry></row>
 133      </tbody>
 134     </tgroup>
 135    </table>
 136    <para>
 137     Function <function>Z3950_connection_host</function> returns
 138      the host for the connection as specified in a call to
 139     <function>Z3950_connection_new</function> or
 140     <function>Z3950_connection_connect</function>.
 141     This function returns <literal>NULL</literal> if host isn't
 142     set for the connection.
 143    </para>
 144    <synopsis>
 145      int Z3950_connection_error (Z3950_connection c, const char **cp,
 146                                  const char **addinfo);
 147    </synopsis>
 148    <para>
 149     Use <function>Z3950_connection_error</function> to check for
 150     errors for the last operation(s) performed. The function returns
 151     zero if no errors occurred; non-zero otherwise indicating the error.
 152     Pointers <parameter>cp</parameter> and <parameter>addinfo</parameter>
 153     holds messages for the error and additional-info if passed as
 154     non-<literal>NULL</literal>.
 155    </para>
 156   </sect1>
 157   <sect1 id="zoom.query"><title>Queries</title>
 158    <para>
 159     Query objects represents queries.
 160    </para>
 161    <synopsis>
 162      Z3950_query Z3950_query_create(void);
 163
 164      void Z3950_query_destroy(Z3950_query q);
 165
 166      int Z3950_query_prefix(Z3950_query q, const char *str);
 167
 168      int Z3950_query_sortby(Z3950_query q, const char *criteria);
 169    </synopsis>
 170    <para>
 171     Create query objects using <function>Z3950_query_create</function>
 172     and destroy them by calling <function>Z3950_query_destroy</function>.
 173     RPN-queries can be specified in <link linkend="PQF">PQF</link>
 174     notation by using the
 175     function <function>Z3950_query_prefix</function>. More
 176     query types will be added later, such as
 177     <link linkend="CCL">CCL</link> to RPN-mapping, native CCL query,
 178     etc. In addition to a search, a sort criteria may be set. Function
 179     <function>Z3950_query_sortby</function> specifies a
 180     sort criteria using the same string notation for sort as offered by
 181     the <link linkend="sortspec">YAZ client</link>.
 182    </para>
 183   </sect1>
 184   <sect1 id="zoom.resultsets"><title>Result sets</title>
 185    <para>
 186     The result set object is a container for records returned from
 187     a target.
 188    </para>
 189    <synopsis>
 190      Z3950_resultset Z3950_connection_search(Z3950_connection,
 191                                              Z3950_query q);
 192
 193      Z3950_resultset Z3950_connection_search_pqf(Z3950_connection c,
 194                                                  const char *q);
 195
 196      void Z3950_resultset_destroy(Z3950_resultset r);
 197    </synopsis>
 198    <para>
 199     Function <function>Z3950_connection_search</function> creates
 200      a result set given a connection and query.
 201     Destroy a result set by calling
 202     <function>Z3950_resultset_destroy</function>.
 203     Simple clients may using PQF only may use function
 204     <function>Z3950_connection_search_pqf</function> in which case
 205     creating query objects is not necessary.
 206    </para>
 207    <synopsis>
 208      const char *Z3950_resultset_option (Z3950_resultset r,
 209                                          const char *key,
 210                                          const char *val);
 211
 212      int Z3950_resultset_size (Z3950_resultset r);
 213
 214      void *Z3950_resultset_get (Z3950_resultset s, size_t pos,
 215                                 const char *type, size_t *len);
 216    </synopsis>
 217    <para>
 218     Function <function>Z3950_resultset_options</function> sets or
 219     modifies an option for a result set similar to
 220     <function>Z3950_connection_option</function>.
 221    </para>
 222    <para>
 223     The number of hits also called result-count is returned by
 224     function <function>Z3950_resultset_size</function>.
 225    </para>
 226    <para>
 227     Function <function>Z3950_resultset_get</function> is similar to
 228     <link linkend="zoom.record.get">
 229      <function>Z3950_record_get</function></link> but
 230     instead of operating on a record object, it operates on a record on
 231     a given offset within a result set.
 232    </para>
 233    <table frame="top"><title>ZOOM Result set Options</title>
 234     <tgroup cols="3">
 235      <colspec colwidth="4*" colname="name"></colspec>
 236      <colspec colwidth="7*" colname="description"></colspec>
 237      <colspec colwidth="2*" colname="default"></colspec>
 238      <thead>
 239       <row>
 240        <entry>Option</entry>
 241        <entry>Description</entry>
 242        <entry>Default</entry>
 243       </row>
 244      </thead>
 245      <tbody>
 246       <row><entry>
 247         piggyback</entry><entry>True (1) if piggyback should be
 248         used in searches; false (0) if not.
 249        </entry><entry>1</entry></row>
 250       <row><entry>
 251         start</entry><entry>Offset of first record to be
 252         retrieved from target. First record has offset 0 unlike the
 253         protocol specifications where first record has position 1.
 254        </entry><entry>0</entry></row>
 255       <row><entry>
 256         count</entry><entry>Number of records to be retrieved.
 257        </entry><entry>0</entry></row>
 258       <row><entry>
 259         elementSetName</entry><entry>Element-Set name of records.
 260         Most targets should honor element set name <literal>B</literal>
 261         and <literal>F</literal> for brief and full respectively.
 262        </entry><entry>none</entry></row>
 263       <row><entry>
 264         preferredRecordSyntax</entry><entry>Preferred Syntax, such as
 265         <literal>USMARC</literal>, <literal>SUTRS</literal>, etc.
 266        </entry><entry>none</entry></row>
 267       <row><entry>
 268         smallSetUpperBound</entry><entry>If hits is less than or equal to this
 269         value, then target will return all records using small element set name
 270        </entry><entry>0</entry></row>
 271       <row><entry>
 272         largeSetLowerBound</entry><entry>If hits is greator than this value, the target
 273         will return no records.
 274        </entry><entry>1</entry></row>
 275       <row><entry>
 276         mediumSetPresentNumber</entry><entry>This value represents
 277         the number of records to be returned as part of a search when when
 278         hits is less than or equal to large set lower bound and if hits
 279         is greator than small set upper bound.
 280        </entry><entry>0</entry></row>
 281       <row><entry>
 282         smallSetElementSetName</entry><entry>
 283         The element set name to be used for small result sets.
 284        </entry><entry>none</entry></row>
 285       <row><entry>
 286         mediumSetElementSetName</entry><entry>
 287         The element set name to be for medium-sized result sets.
 288        </entry><entry>none</entry></row>
 289       <row><entry>
 290         databaseName</entry><entry>One or more database names
 291         separated by character plus (<literal>+</literal>).
 292        </entry><entry>Default</entry></row>
 293      </tbody>
 294     </tgroup>
 295    </table>
 296   </sect1>
 297   <sect1 id="zoom.records"><title>Records</title>
 298    <para>
 299     A record object is a retrival record on the client side -
 300     created from result sets.
 301    </para>
 302    <synopsis>
 303      void Z3950_resultset_records (Z3950_resultset r,
 304                                    Z3950_record *recs,
 305                                    size_t start, size_t count);
 306      Z3950_record Z3950_resultset_record (Z3950_resultset s, size_t pos);
 307
 308      void *Z3950_record_get (Z3950_record rec, const char *type,
 309                              size_t *len);
 310
 311      void Z3950_record_destroy (Z3950_record rec);
 312    </synopsis>
 313    <para>
 314     Records are created by functions
 315     <function>Z3950_resultset_records</function> or
 316     <function>Z3950_resultset_record</function>
 317     and destroyed by <function>Z3950_record_destroy</function>.
 318    </para>
 319    <para>
 320     A single record is created and returned by function
 321     <function>Z3950_resultset_record</function> that takes a
 322     position as argument. First record has position zero.
 323     If no record could be obtained <literal>NULL</literal> is returned.
 324    </para>
 325    <para>
 326     Function <function>Z3950_resultset_records</function> retrieves
 327     a number of records from a result set. Parameter <literal>start</literal>
 328     and <literal>count</literal> specifies the range of records to
 329     be returned. Upon completion array <literal>recs[0], ..recs[count-1]</literal>
 330     holds record objects for the records. The array of records
 331      <literal>recs</literal> should be allocate prior to calling
 332     <function>Z3950_resultset_records</function>. Note that for those
 333     records that couldn't be retrieved from the target
 334     <literal>recs[ ..]</literal> is set to <literal>NULL</literal>.
 335    </para>
 336    <para id="zoom.record.get">
 337     In order to extract information about a single record,
 338     <function>Z3950_record_get</function> is provided. The
 339     function returns a pointer to certain record information. The
 340     nature (type) of the pointer depends on the <function>type</function>
 341     given. In addition for certain types, the length
 342     <literal>len</literal> passed will be set to the size in bytes of
 343     the returned information. The types <literal>database</literal>,
 344     <literal>syntax</literal> and <literal>render</literal> are
 345     supported. More will be added later.
 346    </para>
 347   </sect1>
 348   <sect1 id="zoom.options"><title>Options</title>
 349    <para>
 350     Most &zoom; objects provide a way to specify options to default behaviour.
 351     From an implementation point of view a set of options is just like
 352     an associate array / hash array, etc.
 353    </para>
 354    <synopsis>
 355      Z3950_options Z3950_options_create (void);
 356
 357      Z3950_options Z3950_options_create_with_parent (Z3950_options parent);
 358
 359      void Z3950_options_destroy (Z3950_options opt);
 360    </synopsis>
 361    <synopsis>
 362      const char *Z3950_options_get (Z3950_options opt, const char *name);
 363
 364      void Z3950_options_set (Z3950_options opt, const char *name,
 365                              const char *v);
 366    </synopsis>
 367    <synopsis>
 368      typedef const char *(*Z3950_options_callback)
 369                                      (void *handle, const char *name);
 370
 371      Z3950_options_callback
 372              Z3950_options_set_callback (Z3950_options opt,
 373                                          Z3950_options_callback c,
 374                                          void *handle);
 375    </synopsis>
 376   </sect1>
 377   <sect1 id="zoom.events"><title>Events</title>
 378    <para>
 379     If you're developing non-blocking applications, you have to deal
 380     with events.
 381    </para>
 382    <synopsis>
 383     int Z3950_event (int no, Z3950_connection *cs);
 384    </synopsis>
 385    <para>
 386     The <function>Z3950_event</function> executes pending events for
 387     a number of connections. Supply the number of connections in
 388     <literal>no</literal> and an array of connections in
 389     <literal>cs</literal> (<literal>cs[0] ... cs[no-1]</literal>).
 390     A pending event could be a sending a search, receiving a response,
 391     etc.
 392     When an event has a occured for one of the connections, this function
 393     returns a positive integer <literal>n</literal> denoting that an event
 394     occurred for connection <literal>cs[n-1]</literal>.
 395     When no events are pending for the connections, a value of zero is
 396     returned.
 397     To make sure all outstanding requests are performed call this function
 398     repeatedly until zero is returned.
 399    </para>
 400   </sect1>
 401  </chapter>
 402
 403  <!-- Keep this comment at the end of the file
 404  Local variables:
 405  mode: sgml
 406  sgml-omittag:t
 407  sgml-shorttag:t
 408  sgml-minimize-attributes:nil
 409  sgml-always-quote-attributes:t
 410  sgml-indent-step:1
 411  sgml-indent-data:t
 412  sgml-parent-document: "yaz.xml"
 413  sgml-local-catalogs: nil
 414  sgml-namecase-general:t
 415  End:
 416  -->
 417